{"openapi":"3.1.0","info":{"title":"TraqOS API","version":"1.0.0","description":"Public REST API. Authenticate with a Personal Access Token: `Authorization: Bearer traqos_pat_…`. A token never grants more than its owner's role allows (scopes ∩ RBAC). Rate limits are per token; watch X-RateLimit-* headers. Plan denials return HTTP 402 with the entitlement envelope. Resources you cannot see return 404."},"servers":[{"url":"/api/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"traqos_pat_…"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"required":["code","message"]}}},"EntitlementError":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable reason"},"code":{"type":"string","enum":["entitlement_denied"]},"key":{"type":"string"},"current":{"type":["integer","null"]},"max":{"type":["integer","null"]},"requiredPlan":{"type":"string"}}},"Task":{"type":"object","properties":{"id":{"type":"string","description":"Canonical task id"},"taskId":{"type":"integer","description":"Per-list numeric id (display)"},"name":{"type":"string"},"description":{"type":"string","description":"Tiptap JSON serialized as a string"},"descriptionPinned":{"type":"boolean"},"status":{"type":["string","null"]},"type":{"type":"string"},"color":{"type":["string","null"]},"startDate":{"type":["string","null"],"format":"date-time"},"endDate":{"type":["string","null"],"format":"date-time"},"duration":{"type":["number","null"]},"progress":{"type":"number","minimum":0,"maximum":100},"timeEstimate":{"type":["number","null"]},"timeTracked":{"type":"number"},"assigneeIds":{"type":"array","items":{"type":"string"}},"dependencies":{"type":"array","items":{"type":"string"},"description":"Predecessor strings, e.g. \"12FS\""},"parentId":{"type":["string","null"]},"sectionId":{"type":["string","null"]},"listId":{"type":"string"},"projectId":{"type":"string"},"boardId":{"type":["string","null"]},"customFieldValues":{"type":"object","additionalProperties":true},"checklists":{"type":"array","items":{"type":"object","additionalProperties":true}},"isRecurring":{"type":"boolean"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"},"display":{"type":"object","description":"Human-readable companions. Present only with ?expand=display, and on member-owned hook deliveries.","properties":{"url":{"type":"string","description":"Link to the task in the app"},"status":{"type":["string","null"],"description":"The status NAME (Task.status holds its value)"},"assignees":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}}}},"list":{"type":["string","null"],"description":"List name"},"project":{"type":["string","null"],"description":"Project name"},"description":{"type":"string","description":"The description as plain text"}}}}},"TaskInput":{"type":"object","description":"Public write fields. Unknown keys are rejected.","properties":{"name":{"type":"string","minLength":2,"maxLength":500},"description":{"type":"string"},"descriptionText":{"type":["string","null"],"description":"The description as plain text, one paragraph per line. Send this OR description, not both. \"\" clears it."},"descriptionPinned":{"type":"boolean"},"startDate":{"type":["string","null"]},"endDate":{"type":["string","null"]},"duration":{"type":["number","null"]},"progress":{"type":"number","minimum":0,"maximum":100},"status":{"type":["string","null"]},"type":{"type":"string"},"color":{"type":["string","null"]},"sectionId":{"type":["string","null"]},"assigneeIds":{"type":"array","items":{"type":"string"}},"dependencies":{"type":"array","items":{"type":"string"}},"timeEstimate":{"type":["number","null"]},"customFieldValues":{"type":"object","additionalProperties":true},"isRecurring":{"type":"boolean"},"recurrence":{"type":"object","additionalProperties":true},"checklists":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"Project":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"boardId":{"type":["string","null"]},"color":{"type":["string","null"]},"icon":{"type":["string","null"]},"privacy":{"type":"string","enum":["public","private"]},"isDefault":{"type":"boolean"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}}},"TaskList":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":["string","null"]},"icon":{"type":["string","null"]},"isDefault":{"type":"boolean"},"folderId":{"type":["string","null"]},"locked":{"type":"boolean","description":"true = metadata stub (no access to contents)"},"description":{"type":"string"},"statuses":{"type":"array","description":"Status options for this list. `value` is what Task.status stores.","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"},"color":{"type":["string","null"]},"category":{"type":["string","null"],"description":"not_started | active | closed"},"order":{"type":"integer"}}}},"taskTypes":{"type":"array","description":"Task types for this list. `id` is what Task.type stores.","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"icon":{"type":["string","null"]},"color":{"type":["string","null"]},"isEnabled":{"type":"boolean"},"order":{"type":"integer"}}}},"defaultTaskType":{"type":["string","null"]},"canEdit":{"type":"boolean"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}}},"Member":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"email":{"type":["string","null"]},"role":{"type":"string"}}},"Comment":{"type":"object","properties":{"id":{"type":"string"},"taskId":{"type":["integer","null"],"description":"Numeric TaskID (thread key)"},"parentId":{"type":["string","null"]},"threadDepth":{"type":"integer"},"content":{"type":"string","description":"Sanitized HTML"},"plainText":{"type":"string"},"author":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]}}},"mentions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}}}},"replyCount":{"type":"integer"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}}},"CustomField":{"type":"object","properties":{"fieldId":{"type":"string","description":"The key used inside Task.customFieldValues"},"name":{"type":"string"},"type":{"type":"string"},"description":{"type":["string","null"]},"options":{"type":"array","items":{"type":"object","additionalProperties":true}},"order":{"type":"integer"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}}},"Webhook":{"type":"object","description":"A workspace webhook: every event of the workspace, or of one project. Managed by developer-admins.","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["task.created","task.updated","task.deleted","task.status_changed","task.assignee_added","task.assignee_removed","task.due_date_changed","task.start_date_changed","task.custom_field_changed","task.form_submitted","task.email_received","comment.created"]}},"status":{"type":"string","enum":["active","paused","auto_disabled"],"description":"auto_disabled = 20 failed deliveries in a row. Fix the endpoint, then PATCH status to active."},"projectId":{"type":["string","null"],"description":"Set = only this project's events"},"consecutiveFailures":{"type":"integer"},"lastDeliveryAt":{"type":["string","null"],"format":"date-time"},"lastDeliveryStatus":{"type":["string","null"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}}},"WebhookInput":{"type":"object","required":["name","url","events"],"properties":{"name":{"type":"string","maxLength":100},"url":{"type":"string","format":"uri","description":"https URL on a public host. Private, loopback and link-local addresses are refused."},"events":{"type":"array","minItems":1,"items":{"type":"string","enum":["task.created","task.updated","task.deleted","task.status_changed","task.assignee_added","task.assignee_removed","task.due_date_changed","task.start_date_changed","task.custom_field_changed","task.form_submitted","task.email_received","comment.created"]}},"projectId":{"type":["string","null"],"description":"Limit the webhook to one project"}}},"WebhookPatch":{"type":"object","description":"Send only the fields to change.","properties":{"name":{"type":"string","maxLength":100},"url":{"type":"string","format":"uri"},"events":{"type":"array","minItems":1,"items":{"type":"string","enum":["task.created","task.updated","task.deleted","task.status_changed","task.assignee_added","task.assignee_removed","task.due_date_changed","task.start_date_changed","task.custom_field_changed","task.form_submitted","task.email_received","comment.created"]}},"projectId":{"type":["string","null"]},"status":{"type":"string","enum":["active","paused"],"description":"paused = keep the subscription, send nothing. active = resume, also after auto_disabled."}}},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"eventType":{"type":"string"},"status":{"type":"string","enum":["pending","processing","succeeded","failed","dead"]},"attempts":{"type":"integer"},"responseStatus":{"type":["integer","null"]},"responseBodySnippet":{"type":["string","null"],"description":"First 1024 characters of your answer"},"durationMs":{"type":["integer","null"]},"lastError":{"type":["string","null"]},"nextAttemptAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":["string","null"],"format":"date-time"},"payload":{"type":"object","additionalProperties":true,"description":"The EventEnvelope that was sent"}}},"Hook":{"type":"object","description":"A member hook: the events of ONE task list, owned by the token's user, carrying only what that user can read.","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["task.created","task.updated","task.deleted","task.status_changed","task.assignee_added","task.assignee_removed","task.due_date_changed","task.start_date_changed","task.form_submitted","task.email_received","comment.created"]}},"listId":{"type":"string"},"projectId":{"type":["string","null"]},"status":{"type":"string","enum":["active","paused","auto_disabled"]},"createdAt":{"type":["string","null"],"format":"date-time"}}},"HookInput":{"type":"object","required":["url","events","listId"],"properties":{"url":{"type":"string","format":"uri","description":"Where to POST deliveries. https, public host."},"events":{"type":"array","minItems":1,"items":{"type":"string","enum":["task.created","task.updated","task.deleted","task.status_changed","task.assignee_added","task.assignee_removed","task.due_date_changed","task.start_date_changed","task.form_submitted","task.email_received","comment.created"]}},"listId":{"type":"string","description":"The task list to watch. Must be readable by the token's owner, otherwise 404."},"name":{"type":"string","maxLength":100}}},"EventEnvelope":{"type":"object","description":"The body of every delivery. `data` holds `task` (+ `changes` with from/to per field) for task events and `comment` for comment events.","required":["id","type","createdAt","tenantId","data"],"properties":{"id":{"type":"string","description":"Unique per event; a retry keeps the same id"},"type":{"type":"string","enum":["task.created","task.updated","task.deleted","task.status_changed","task.assignee_added","task.assignee_removed","task.due_date_changed","task.start_date_changed","task.custom_field_changed","task.form_submitted","task.email_received","comment.created","webhook.test"]},"createdAt":{"type":"string","format":"date-time"},"tenantId":{"type":"string"},"projectId":{"type":["string","null"]},"listId":{"type":["string","null"]},"actor":{"type":"object","properties":{"userId":{"type":["string","null"],"description":"Who caused the event"}}},"data":{"type":"object","additionalProperties":true,"description":"task.* → { task: Task, changes?: { <field>: { from, to } } }. comment.created → { comment: Comment }. Member-hook deliveries always include task.display; a status change adds changes.status.fromName and toName; a comment adds comment.display.taskRef { id, taskId }."}}}}},"paths":{"/me":{"get":{"summary":"Token introspection","responses":{"200":{"description":"Who am I","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":["string","null"]}}},"tenant":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}}},"authKind":{"type":"string","enum":["pat","oauth","session"]},"scopes":{"type":["array","null"],"items":{"type":"string"},"description":"null = full user rights (session)"},"plan":{"type":"string"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects":{"get":{"summary":"List accessible projects","description":"Requires scope projects:read.","parameters":[{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Page of projects","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Project"}},"nextCursor":{"type":["string","null"],"description":"Opaque cursor; pass back as ?cursor="}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a project","description":"Requires scope projects:write. Defaults to the General board when boardId is omitted.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"boardId":{"type":"string"},"privacy":{"type":"string","enum":["public","private"]}}}}}},"responses":{"201":{"description":"Created project","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"}}}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan limit (locked envelope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntitlementError"}}}},"403":{"description":"Missing scope / insufficient permissions / workspace read-only","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}":{"get":{"summary":"Get a project","description":"Requires scope projects:read. 404 when missing OR not visible to you.","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Project","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}/lists":{"get":{"summary":"List task lists in a project","description":"Requires scope lists:read. Private lists you can't view are omitted; folder fences apply.","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Task lists","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TaskList"}},"nextCursor":{"type":["string","null"],"description":"Opaque cursor; pass back as ?cursor="}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a task list","description":"Requires scope lists:write. v1 creates public lists (privacy/grants are in-app flows).","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"}}}}}},"responses":{"201":{"description":"Created list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaskList"}}}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan limit (locked envelope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntitlementError"}}}},"403":{"description":"Missing scope / insufficient permissions / workspace read-only","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/lists/{listId}/tasks":{"get":{"summary":"List tasks in a list","description":"Requires scope tasks:read.","parameters":[{"name":"listId","in":"path","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"assigneeId","in":"query","schema":{"type":"string"}},{"name":"updatedSince","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"asc"},"description":"By creation time. desc = newest first."},{"name":"expand","in":"query","schema":{"type":"string","enum":["display"]},"description":"display = add Task.display (link, status name, assignee names, list, project, plain-text description)"},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Page of tasks","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Task"}},"nextCursor":{"type":["string","null"],"description":"Opaque cursor; pass back as ?cursor="}}}}}},"400":{"description":"Bad filter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a task","description":"Requires scope tasks:write. Fires the same realtime/automation events as in-app creation.","parameters":[{"name":"listId","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","schema":{"type":"string","enum":["display"]},"description":"display = add Task.display (link, status name, assignee names, list, project, plain-text description)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TaskInput"}],"required":["name"]}}}},"responses":{"201":{"description":"Created task","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Task"}}}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan limit (locked envelope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntitlementError"}}}},"403":{"description":"Missing scope / insufficient permissions / workspace read-only","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tasks/{taskId}":{"get":{"summary":"Get a task","description":"taskId is the canonical id (Task.id). Requires scope tasks:read.","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","schema":{"type":"string","enum":["display"]},"description":"display = add Task.display (link, status name, assignee names, list, project, plain-text description)"}],"responses":{"200":{"description":"Task","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Task"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update a task","description":"Requires scope tasks:write. Formula fields recompute; realtime/automation events fire.","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","schema":{"type":"string","enum":["display"]},"description":"display = add Task.display (link, status name, assignee names, list, project, plain-text description)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskInput"}}}},"responses":{"200":{"description":"Updated task","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Task"}}}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan limit (locked envelope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntitlementError"}}}},"403":{"description":"Missing scope / insufficient permissions / workspace read-only","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a task","description":"Requires scope tasks:write. Full cascade (time entries, comments, files) — same as in-app deletion.","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope / insufficient permissions / workspace read-only","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/members":{"get":{"summary":"List workspace members","description":"Requires scope members:read AND the member-view role permission. Use ids for assigneeIds and mentions. Guests are never listed.","responses":{"200":{"description":"Members","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Member"}},"nextCursor":{"type":["string","null"],"description":"Opaque cursor; pass back as ?cursor="}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope / insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/search":{"get":{"summary":"Search the workspace","description":"Requires scope tasks:read. Name search across tasks, projects, lists; docs included only when the token carries docs:read. Same access fences as the in-app search.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2}}],"responses":{"200":{"description":"Grouped results","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tasks/{taskId}/comments":{"get":{"summary":"List task comments","description":"Requires scope comments:read. Newest first. Same thread the app UI shows.","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Comments","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Comment"}},"nextCursor":{"type":["string","null"],"description":"Opaque cursor; pass back as ?cursor="}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope / insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Add a comment","description":"Requires scope comments:write. Mentioned member ids are validated and notified (same machinery as in-app comments).","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content"],"properties":{"content":{"type":"string","maxLength":10000},"mentions":{"type":"array","items":{"type":"string"}},"parentId":{"type":"string"}}}}}},"responses":{"201":{"description":"Created comment","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Comment"}}}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope / insufficient permissions / workspace read-only","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/lists/{listId}/custom-fields":{"get":{"summary":"List custom-field definitions","description":"Requires scope custom-fields:read. fieldId is the key Task.customFieldValues uses. Private fields you can't view are omitted.","parameters":[{"name":"listId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Custom fields","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"nextCursor":{"type":["string","null"],"description":"Opaque cursor; pass back as ?cursor="}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope / insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks":{"get":{"summary":"List workspace webhooks","description":"Requires scope webhooks:manage and the developer-admin permission.","responses":{"200":{"description":"Webhooks","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}},"nextCursor":{"type":["string","null"],"description":"Opaque cursor; pass back as ?cursor="}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope / not a developer-admin","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a workspace webhook","description":"Requires scope webhooks:manage and the developer-admin permission. The signing secret is returned once, in this response only. Counts toward the plan's webhooksMax.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookInput"}}}},"responses":{"201":{"description":"Created webhook, with its secret (shown only here)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Webhook"},{"type":"object","properties":{"secret":{"type":"string","description":"The signing secret. Shown only in this response; store it."}}}]}}}}}},"400":{"description":"Validation failed (name, URL, events)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan limit (locked envelope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntitlementError"}}}},"403":{"description":"Missing scope / not a developer-admin / workspace read-only","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{webhookId}":{"get":{"summary":"Get a workspace webhook","description":"Requires scope webhooks:manage and the developer-admin permission.","parameters":[{"name":"webhookId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Webhook","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Webhook"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope / not a developer-admin","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update, pause or resume a workspace webhook","description":"Requires scope webhooks:manage and the developer-admin permission. Send only the fields to change; status accepts active or paused (active also clears auto_disabled).","parameters":[{"name":"webhookId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPatch"}}}},"responses":{"200":{"description":"Updated webhook","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Webhook"}}}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope / not a developer-admin / workspace read-only","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a workspace webhook","description":"Requires scope webhooks:manage and the developer-admin permission. Its delivery log goes with it.","parameters":[{"name":"webhookId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean"}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope / not a developer-admin","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{webhookId}/deliveries":{"get":{"summary":"Delivery log of a workspace webhook","description":"The last 50 deliveries, newest first: status, attempts, your response code, the payload that was sent.","parameters":[{"name":"webhookId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deliveries","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"nextCursor":{"type":["string","null"],"description":"Opaque cursor; pass back as ?cursor="}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope / not a developer-admin","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{webhookId}/test":{"post":{"summary":"Send a test delivery","description":"Posts a webhook.test event to the endpoint right now and returns the outcome.","parameters":[{"name":"webhookId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Outcome of the attempt","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["succeeded","failed","dead"]},"responseStatus":{"type":["integer","null"]},"durationMs":{"type":["integer","null"]},"error":{"type":["string","null"]}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope / not a developer-admin","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/hooks":{"post":{"summary":"Subscribe to one list's events (member hook)","description":"Requires scope hooks:manage plus the read scope of each event family (tasks:read, comments:read). The list must be readable by you now (otherwise 404), and every delivery is checked again when it is sent. Repeating the same request (same URL, list and events) answers 200 with the existing hook instead of creating another. Counts toward the plan's apiHooksMax.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookInput"}}}},"responses":{"200":{"description":"The same hook already existed; returned again with its secret","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Hook"},{"type":"object","properties":{"secret":{"type":"string","description":"The signing secret. Shown only in this response; store it."}}}]}}}}}},"201":{"description":"Created hook, with its secret (shown only here)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Hook"},{"type":"object","properties":{"secret":{"type":"string","description":"The signing secret. Shown only in this response; store it."}}}]}}}}}},"400":{"description":"Validation failed (events, URL)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan limit (locked envelope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntitlementError"}}}},"403":{"description":"Missing scope / events not allowed for your role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"List not found or not visible to you","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/hooks/{hookId}":{"delete":{"summary":"Unsubscribe (delete a member hook)","description":"Only your own hooks; anyone else's answer 404. Never blocked by the plan.","parameters":[{"name":"hookId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean"}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/openapi":{"get":{"summary":"This document","security":[],"responses":{"200":{"description":"OpenAPI 3.1 spec"}}}}},"webhooks":{"taskEvent":{"post":{"summary":"A task event","description":"Sent for every task.* event the subscription carries.","parameters":[{"name":"X-TraqOS-Event","in":"header","schema":{"type":"string"},"description":"The event type"},{"name":"X-TraqOS-Delivery","in":"header","schema":{"type":"string"},"description":"Unique per delivery; a retry reuses it"},{"name":"X-TraqOS-Signature","in":"header","schema":{"type":"string"},"description":"t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<body>\" with the secret>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventEnvelope"}}}},"responses":{"410":{"description":"Member hooks only: the hook is removed and nothing more is sent"},"429":{"description":"Retried after Retry-After; never counted as a failure"},"2XX":{"description":"Received. Answer within 10 seconds."},"default":{"description":"Retried after 1, 5, 30, 120 and 360 minutes (5 attempts); 20 failures in a row disable the subscription"}}}},"commentEvent":{"post":{"summary":"A comment event","description":"Sent for comment.created.","parameters":[{"name":"X-TraqOS-Event","in":"header","schema":{"type":"string"},"description":"The event type"},{"name":"X-TraqOS-Delivery","in":"header","schema":{"type":"string"},"description":"Unique per delivery; a retry reuses it"},{"name":"X-TraqOS-Signature","in":"header","schema":{"type":"string"},"description":"t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<body>\" with the secret>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventEnvelope"}}}},"responses":{"410":{"description":"Member hooks only: the hook is removed and nothing more is sent"},"429":{"description":"Retried after Retry-After; never counted as a failure"},"2XX":{"description":"Received. Answer within 10 seconds."},"default":{"description":"Retried after 1, 5, 30, 120 and 360 minutes (5 attempts); 20 failures in a row disable the subscription"}}}},"testEvent":{"post":{"summary":"A test delivery","description":"Sent by the test button or POST /webhooks/{webhookId}/test; data is a small sample.","parameters":[{"name":"X-TraqOS-Event","in":"header","schema":{"type":"string"},"description":"The event type"},{"name":"X-TraqOS-Delivery","in":"header","schema":{"type":"string"},"description":"Unique per delivery; a retry reuses it"},{"name":"X-TraqOS-Signature","in":"header","schema":{"type":"string"},"description":"t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<body>\" with the secret>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventEnvelope"}}}},"responses":{"410":{"description":"Member hooks only: the hook is removed and nothing more is sent"},"429":{"description":"Retried after Retry-After; never counted as a failure"},"2XX":{"description":"Received. Answer within 10 seconds."},"default":{"description":"Retried after 1, 5, 30, 120 and 360 minutes (5 attempts); 20 failures in a row disable the subscription"}}}}}}