Zoho Projects Skill

Use the Zoho Projects V3 REST API (base: https://projectsapi.zoho.com/api/v3) to manage projects, tasks, milestones, and time logs.

Authentication

Every request must include:
CODEBLOCK0

Access tokens expire hourly. If you get a 401, tell the user their token has expired and they need to refresh it using their refresh token (see Setup below). Store the refreshed token with:
CODEBLOCK1

Environment Variables

Setup (First Time)

1. 1. Go to https://api-console.zoho.com/ → Create a Self Client application
2. Grant scopes: INLINECODE10
3. Generate a grant token (duration: 10 minutes is fine for initial setup)
4. Exchange it for access + refresh tokens:

curl -X POST "https://accounts.zoho.com/oauth/v2/token" \
  -d "grant_type=authorization_code" \
  -d "client_id=$ZOHO_CLIENT_ID" \
  -d "client_secret=$ZOHO_CLIENT_SECRET" \
  -d "redirect_uri=https://localhost" \
  -d "code=YOUR_GRANT_TOKEN"

1. 5. Save the access_token as ZOHO_ACCESS_TOKEN and refresh_token as INLINECODE14
2. Get your portal ID by calling List Portals below, then set INLINECODE15

Refreshing an Expired Token

If you get a 401 Unauthorized error, refresh the token:

curl -X POST "https://accounts.${ZOHO_DC:-zoho.com}/oauth/v2/token" \
  -d "grant_type=refresh_token" \
  -d "client_id=$ZOHO_CLIENT_ID" \
  -d "client_secret=$ZOHO_CLIENT_SECRET" \
  -d "refresh_token=$ZOHO_REFRESH_TOKEN"

API Reference

🏢 Portals

List Portals (use this to find your ZOHOPORTALID)

curl -s "https://projectsapi.zoho.com/api/v3/portals" \
  -H "Authorization: Zoho-oauthtoken $ZOHO_ACCESS_TOKEN"

📁 Projects

List all projects
CODEBLOCK5

Get a specific project
CODEBLOCK6

Create a project
CODEBLOCK7

Update a project (PATCH updates only specified fields)

curl -s -X PATCH "https://projectsapi.zoho.com/api/v3/portal/$ZOHO_PORTAL_ID/projects/$PROJECT_ID" \
  -H "Authorization: Zoho-oauthtoken $ZOHO_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Name", "status": "active"}'

✅ Tasks

Get my tasks (across all projects)

curl -s "https://projectsapi.zoho.com/api/v3/portal/$ZOHO_PORTAL_ID/mytasks" \
  -H "Authorization: Zoho-oauthtoken $ZOHO_ACCESS_TOKEN"

List tasks in a project

curl -s "https://projectsapi.zoho.com/api/v3/portal/$ZOHO_PORTAL_ID/projects/$PROJECT_ID/tasks" \
  -H "Authorization: Zoho-oauthtoken $ZOHO_ACCESS_TOKEN"

Get task details
CODEBLOCK11

Create a task

curl -s -X POST "https://projectsapi.zoho.com/api/v3/portal/$ZOHO_PORTAL_ID/projects/$PROJECT_ID/tasks" \
  -H "Authorization: Zoho-oauthtoken $ZOHO_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Task name",
    "description": "Task details",
    "due_date": "2026-04-15T00:00:00Z",
    "priority": "high"
  }'

Update / complete a task

curl -s -X PATCH "https://projectsapi.zoho.com/api/v3/portal/$ZOHO_PORTAL_ID/projects/$PROJECT_ID/tasks/$TASK_ID" \
  -H "Authorization: Zoho-oauthtoken $ZOHO_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "closed"}'

Delete a task
CODEBLOCK14

Add a comment to a task

curl -s -X POST "https://projectsapi.zoho.com/api/v3/portal/$ZOHO_PORTAL_ID/projects/$PROJECT_ID/tasks/$TASK_ID/comments" \
  -H "Authorization: Zoho-oauthtoken $ZOHO_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Your comment here"}'

🎯 Milestones

List milestones in a project
CODEBLOCK16

Create a milestone

curl -s -X POST "https://projectsapi.zoho.com/api/v3/portal/$ZOHO_PORTAL_ID/projects/$PROJECT_ID/milestones" \
  -H "Authorization: Zoho-oauthtoken $ZOHO_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Milestone name",
    "end_date": "2026-05-01T00:00:00Z",
    "flag": "internal"
  }'

⏱ Time Logs

Log time on a task
CODEBLOCK18

Get time logs for a project

curl -s "https://projectsapi.zoho.com/api/v3/portal/$ZOHO_PORTAL_ID/projects/$PROJECT_ID/logs" \
  -H "Authorization: Zoho-oauthtoken $ZOHO_ACCESS_TOKEN"

Tips

• - All dates must be ISO 8601 format: INLINECODE27
• Rate limit: 100 requests per 2 minutes. If you hit 429, wait 30 seconds before retrying.
• Use | python3 -m json.tool after curl commands to pretty-print JSON responses.
• For EU/AU/IN/JP Zoho accounts, set ZOHO_DC to the correct domain (e.g., zoho.eu) and use projectsapi.zoho.eu as the API base URL instead.
• When listing projects or tasks, extract the id or id_string field to use in subsequent calls.
• If the user asks to "show all open tasks", call the mytasks endpoint with ?status=open and format the results as a readable list.
• When creating tasks for sarvahealth.ai or Katprotech work, apply appropriate project IDs stored in memory.