{"openapi":"3.1.0","info":{"title":"Cinch REST API","version":"1.0.0","description":"# Cinch REST API\n\nA read-first REST API for building dashboards and feeding Cinch data into your own outputs.\nAll endpoints require a Personal Access Token sent as `Authorization: Bearer cinch_xxx`.\n\n## Tokens & scoping\n\nCreate a token in Settings → Personal Access Tokens → **Create Token**. Choose a preset:\n\n- **Dashboard / Export (recommended for dashboards):** scoped to one or more projects within an organization, with an access level of **Read** (baseline) or **Read & Write**. Read tokens can only call `GET` endpoints; Read & Write tokens can also call `POST`/`PATCH`.\n- **AI Assistant (recommended for MCP):** organization-wide with preset scopes for AI tools. Also works with this REST API.\n- **Custom:** organization-wide with scopes you choose.\n\nProject-scoped Read tokens grant these scopes: company:read, project:read, task:read, comment:read, tag:read, customField:read, activity:read.\nProject-scoped Read & Write tokens add: project:write, task:write, comment:write, tag:write, customField:write.\n\n## Responses\n\nSuccessful responses are wrapped as `{ \"data\": <result> }`. Errors are wrapped as `{ \"error\": { \"code\", \"message\", \"details\" } }`.\nList endpoints return `{ \"data\": { \"<items>\": [...], \"nextCursor\": \"...\" } }`. Pass `cursor` to fetch the next page."},"servers":[{"url":"https://app.cinch.work","description":"Cinch API server"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"PAT","description":"Personal Access Token. Send as: Authorization: Bearer cinch_xxx"}}},"security":[{"bearerAuth":[]}],"tags":[{"name":"Account","description":"Current token / account info"},{"name":"Projects","description":"Project read & write"},{"name":"Tasks","description":"Task read & write"},{"name":"Comments","description":"Task comments"},{"name":"Tags","description":"Project tags"},{"name":"Custom Fields","description":"Project custom fields"},{"name":"Activity","description":"Project & task activity logs"}],"paths":{"/api/rest/me":{"get":{"tags":["Account"],"summary":"Get the current token, user, and scope","description":"Returns the authenticated user, the token organization, the projects the token is scoped to, its access level, and granted scopes. Useful to verify a token before building a dashboard.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Token and scope details.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"}}}}}},"401":{"description":"Missing or invalid token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/api/rest/projects":{"get":{"tags":["Projects"],"summary":"List projects in scope","description":"Lists the projects the token can access. Project-scoped tokens only see their selected projects; organization-wide tokens see all projects in their company.","security":[{"bearerAuth":[]}],"parameters":[{"name":"companyId","in":"query","required":false,"schema":{"type":"string"},"description":"Restrict to a specific organization (org-wide tokens only)."},{"name":"includeArchived","in":"query","required":false,"schema":{"type":"boolean"},"description":"Include archived projects."},{"name":"includeBackburner","in":"query","required":false,"schema":{"type":"boolean"},"description":"Include paused (backburner) projects."}],"responses":{"200":{"description":"A list of projects.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"}}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Forbidden.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}},"post":{"tags":["Projects"],"summary":"Create a project","description":"Creates a project in the token organization. Requires Read & Write access. Not available to project-scoped tokens — use an organization-wide (advanced) token to create projects.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","key"],"properties":{"name":{"type":"string"},"key":{"type":"string","description":"2–10 character project key."},"description":{"type":"string"},"scope":{"type":"string","enum":["ORGANIZATION","PERSONAL"]},"dueDate":{"type":"string","format":"date-time"},"color":{"type":"string"},"icon":{"type":"string"}}}}}},"responses":{"200":{"description":"The created project.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"}}}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Read-only token or no access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/api/rest/projects/{projectId}":{"get":{"tags":["Projects"],"summary":"Get a project","security":[{"bearerAuth":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"The Cinch project ID."}],"responses":{"200":{"description":"The project with members and counts.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"}}}}}},"404":{"description":"Project not found or out of scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}},"patch":{"tags":["Projects"],"summary":"Update a project","description":"Updates fields on a project. Requires Read & Write access.","security":[{"bearerAuth":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"The Cinch project ID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"archived":{"type":"boolean"},"backburner":{"type":"boolean"},"dueDate":{"type":"string","format":"date-time","nullable":true},"color":{"type":"string"},"icon":{"type":"string","nullable":true}}}}}},"responses":{"200":{"description":"The updated project.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"}}}}}},"403":{"description":"Read-only token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/api/rest/projects/{projectId}/tasks":{"get":{"tags":["Tasks"],"summary":"List tasks in a project","security":[{"bearerAuth":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"The Cinch project ID."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["BACKLOG","TODO","IN_PROGRESS","IN_REVIEW","DONE","CANCELLED"]}},{"name":"assigneeId","in":"query","required":false,"schema":{"type":"string"}},{"name":"includeSubtasks","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Pagination cursor returned by the previous page."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Maximum number of items to return per page."}],"responses":{"200":{"description":"Paginated tasks","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"tasks":{"type":"array","items":{"type":"object"}},"nextCursor":{"type":"string","nullable":true,"description":"Cursor for the next page; null when no more results."}}}}}}}},"404":{"description":"Project not in scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}},"post":{"tags":["Tasks"],"summary":"Create a task in a project","description":"Requires Read & Write access.","security":[{"bearerAuth":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"The Cinch project ID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"title":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["BACKLOG","TODO","IN_PROGRESS","IN_REVIEW","DONE","CANCELLED"]},"priority":{"type":"integer","minimum":0,"maximum":4},"assigneeId":{"type":"string"},"dueDate":{"type":"string","format":"date-time","description":"ISO timestamp. Pair with dueTimeZone for a timed task; omit the timezone for date-only."},"dueTimeZone":{"type":"string","description":"Source IANA timezone, e.g. America/New_York."},"startDate":{"type":"string","format":"date-time"},"startTimeZone":{"type":"string","description":"Source IANA timezone for a timed start."},"parentId":{"type":"string"}}}}}},"responses":{"200":{"description":"The created task.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"}}}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Read-only token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/api/rest/tasks/{taskId}":{"get":{"tags":["Tasks"],"summary":"Get a task","security":[{"bearerAuth":[]}],"parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"},"description":"The Cinch task ID."}],"responses":{"200":{"description":"The task with relations.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"}}}}}},"404":{"description":"Task not found or out of scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}},"patch":{"tags":["Tasks"],"summary":"Update a task","description":"Requires Read & Write access.","security":[{"bearerAuth":[]}],"parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"},"description":"The Cinch task ID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["BACKLOG","TODO","IN_PROGRESS","IN_REVIEW","DONE","CANCELLED"]},"priority":{"type":"integer","minimum":0,"maximum":4},"assigneeId":{"type":"string","nullable":true},"dueDate":{"type":"string","format":"date-time","nullable":true},"dueTimeZone":{"type":"string","nullable":true,"description":"Source IANA timezone. Set null to remove time while retaining the date."},"startDate":{"type":"string","format":"date-time","nullable":true},"startTimeZone":{"type":"string","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true}}}}}},"responses":{"200":{"description":"The updated task.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"}}}}}},"403":{"description":"Read-only token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/api/rest/tasks/{taskId}/comments":{"get":{"tags":["Comments"],"summary":"List comments on a task","security":[{"bearerAuth":[]}],"parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"},"description":"The Cinch task ID."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Pagination cursor returned by the previous page."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"Paginated comments","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"comments":{"type":"array","items":{"type":"object"}},"nextCursor":{"type":"string","nullable":true,"description":"Cursor for the next page; null when no more results."}}}}}}}},"404":{"description":"Task not in scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}},"post":{"tags":["Comments"],"summary":"Add a comment to a task","description":"Requires Read & Write access. Content may include Tiptap HTML.","security":[{"bearerAuth":[]}],"parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"},"description":"The Cinch task ID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content"],"properties":{"content":{"type":"string"},"parentId":{"type":"string","description":"Reply to a comment by ID."}}}}}},"responses":{"200":{"description":"The created comment.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"}}}}}},"403":{"description":"Read-only token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"404":{"description":"Task not in scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/api/rest/projects/{projectId}/tags":{"get":{"tags":["Tags"],"summary":"List tags for the project","security":[{"bearerAuth":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"The Cinch project ID."}],"responses":{"200":{"description":"A list of tags with task counts.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"}}}}}},"404":{"description":"Project not in scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/api/rest/projects/{projectId}/custom-fields":{"get":{"tags":["Custom Fields"],"summary":"List custom fields available to a project","security":[{"bearerAuth":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"The Cinch project ID."}],"responses":{"200":{"description":"Org-wide and project-specific custom fields.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"}}}}}},"404":{"description":"Project not in scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/api/rest/projects/{projectId}/activity":{"get":{"tags":["Activity"],"summary":"List recent activity in a project","security":[{"bearerAuth":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"The Cinch project ID."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Pagination cursor returned by the previous page."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Maximum number of items to return per page."}],"responses":{"200":{"description":"Paginated activity","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"activities":{"type":"array","items":{"type":"object"}},"nextCursor":{"type":"string","nullable":true,"description":"Cursor for the next page; null when no more results."}}}}}}}},"404":{"description":"Project not in scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}}}}