{"openapi":"3.1.0","info":{"title":"Utter API","version":"1.0.0","description":"Public REST API for Utter (utter.ae). All endpoints require a workspace-scoped bearer API key. Paths are nested under `/v1/workspaces/{slug}/…`."},"servers":[{"url":"https://utter.ae/api"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"Workspace API key. Send as `Authorization: Bearer utp_live_…`. Each key is bound to exactly one workspace and carries a set of scopes."}},"schemas":{"ErrorEnvelope":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation","rate_limited","conflict","idempotency_violation","internal_error"],"example":"validation"},"message":{"type":"string","example":"Label \"foo\" does not exist on this project."},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]},"Workspace":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string","example":"utter"},"name":{"type":"string","example":"Utter"},"default_locale":{"type":"string","example":"en"},"created_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["id","slug","name","default_locale","created_at"]},"WorkspacePatchInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"example":"Utter"}},"required":["name"]},"Project":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string","example":"WEB"},"slug":{"type":"string","example":"web"},"name":{"type":"string","example":"Website"},"description_md":{"type":["string","null"]},"lead_user_id":{"type":["string","null"]},"scoped":{"type":"boolean","description":"True when access is restricted to explicit project members."},"estimation_unit":{"type":"string","enum":["time","points","none"],"description":"How this project estimates work (POINTS-01): time (estimate_minutes), points (story_points), or none."},"archived_at":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z"},"created_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["id","key","slug","name","description_md","lead_user_id","scoped","estimation_unit","archived_at","created_at","updated_at"]},"Label":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","example":"frontend"},"color":{"type":"string","example":"#f5c518"},"created_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["id","name","color","created_at"]},"ProjectStatus":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","example":"In Review"},"name_ar":{"type":["string","null"],"example":"قيد المراجعة"},"color":{"type":"string","example":"#4FE8E5"},"category":{"type":"string","enum":["backlog","todo","in_progress","in_review","done","failed","cancelled"],"description":"System category the status maps to (open/done semantics)."},"rank":{"type":"string","description":"LexoRank ordering string."}},"required":["id","name","name_ar","color","category","rank"]},"Issue":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string","example":"WEB-39"},"url":{"type":"string","example":"https://utter.ae/w/utter/p/web/WEB-39"},"number":{"type":"integer"},"type":{"type":"string","enum":["epic","story","task","bug","subtask"]},"title":{"type":"string"},"description_md":{"type":["string","null"]},"status":{"type":"string","enum":["backlog","todo","in_progress","in_review","done","failed","cancelled"]},"status_id":{"type":["string","null"],"description":"Specific board status id (project_statuses). See GET .../statuses."},"status_name":{"type":["string","null"],"description":"Display name of the board status."},"priority":{"type":"string","enum":["lowest","low","medium","high","highest","critical"]},"assignee_id":{"type":["string","null"],"description":"Primary assignee (compat). Equals assignees[0], or null when unassigned."},"assignees":{"type":"array","items":{"type":"string"},"description":"All assignee user ids, primary first. Set via PATCH assignee_ids."},"reporter_id":{"type":"string"},"parent_id":{"type":["string","null"]},"epic_id":{"type":["string","null"]},"milestone_id":{"type":["string","null"],"description":"Attached milestone id, or null."},"sprint_id":{"type":["string","null"],"description":"Attached sprint id, or null."},"release_id":{"type":["string","null"],"description":"Attached release id, or null."},"labels":{"type":"array","items":{"$ref":"#/components/schemas/Label"}},"estimate_minutes":{"type":["integer","null"]},"story_points":{"type":["integer","null"],"description":"Story points estimate (POINTS-01); used when the project's estimation_unit is \"points\". Null = unestimated."},"spent_minutes":{"type":["integer","null"]},"completion_pct":{"type":["integer","null"]},"start_at":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z"},"due_at":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z"},"resolved_at":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z"},"archived_at":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z"},"created_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["id","key","url","number","type","title","description_md","status","status_id","status_name","priority","assignee_id","assignees","reporter_id","parent_id","epic_id","milestone_id","sprint_id","release_id","labels","estimate_minutes","story_points","spent_minutes","completion_pct","start_at","due_at","resolved_at","archived_at","created_at","updated_at"]},"Comment":{"type":"object","properties":{"id":{"type":"string"},"issue_id":{"type":"string"},"author_id":{"type":"string"},"body_md":{"type":"string"},"body_html":{"type":"string"},"created_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["id","issue_id","author_id","body_md","body_html","created_at","updated_at"]},"Activity":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","example":"status_changed"},"actor_id":{"type":["string","null"]},"payload":{"type":"object","additionalProperties":{}},"created_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["id","kind","actor_id","payload","created_at"]},"Watcher":{"type":"object","properties":{"user_id":{"type":"string"},"created_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["user_id","created_at"]},"Attachment":{"type":"object","properties":{"id":{"type":"string"},"issue_id":{"type":"string"},"comment_id":{"type":["string","null"]},"file_name":{"type":"string"},"mime":{"type":"string"},"byte_size":{"type":"integer"},"uploader_id":{"type":"string"},"url":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["id","issue_id","comment_id","file_name","mime","byte_size","uploader_id","url","created_at"]},"UploadIntent":{"type":"object","properties":{"r2_key":{"type":"string"},"url":{"type":"string","description":"Pre-signed R2 PUT URL."},"headers":{"type":"object","additionalProperties":{"type":"string"}},"expires_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["r2_key","url","headers","expires_at"]},"CustomFieldDef":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","example":"severity"},"kind":{"type":"string","enum":["text","number","select","multi_select","date","checkbox","url","user","project","doc"]},"options":{"type":"array","items":{"type":"string"}},"applies_to":{"type":"array","items":{"type":"string","enum":["epic","story","task","bug","subtask"]}},"required":{"type":"boolean"},"rank":{"type":"string"}},"required":["id","name","kind","options","applies_to","required","rank"]},"CustomFieldValue":{"type":"object","properties":{"field_id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"},"value":{}},"required":["field_id"]},"Sprint":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","example":"Sprint 7"},"goal":{"type":["string","null"],"description":"Sprint goal (markdown)."},"status":{"type":"string","enum":["planned","active","completed"]},"start_at":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z"},"end_at":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z"},"rank":{"type":"string"}},"required":["id","name","goal","status","start_at","end_at","rank"]},"Milestone":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","example":"v2.0 Release"},"description_md":{"type":["string","null"],"description":"Milestone description (markdown)."},"status":{"type":"string","enum":["planned","active","completed"]},"start_at":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z"},"due_at":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z"},"rank":{"type":"string"}},"required":["id","name","description_md","status","start_at","due_at","rank"]},"Release":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","example":"Autumn Launch"},"version":{"type":["string","null"],"example":"2.1.0","description":"Semantic version or build tag."},"description_md":{"type":["string","null"],"description":"Release notes (markdown)."},"status":{"type":"string","enum":["planned","in_progress","released","cancelled"]},"target_date":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z","description":"Planned ship date."},"released_at":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z","description":"Actual ship time; set when status becomes released."},"rank":{"type":"string"}},"required":["id","name","version","description_md","status","target_date","released_at","rank"]},"Report":{"type":"object","properties":{"report":{"type":"string","enum":["velocity","burndown","cycle-time","throughput","status-breakdown","type-breakdown","workload"],"description":"Which report this payload describes."},"data":{"description":"Report-specific payload. Shape depends on `report`: velocity (bars + average), burndown (points), cycle-time (buckets + percentiles), throughput (weekly created vs resolved), status/type-breakdown (slices), workload (rows by assignee). Sprint-dependent reports may be null when the project has no sprints."}},"required":["report"]},"SavedView":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"filter":{"description":"Opaque filter blob (issueTypes[], priorities[], assigneeId, sort…)."},"is_shared":{"type":"boolean"},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["id","name","is_shared","created_by","created_at","updated_at"]},"TimeTracking":{"type":"object","properties":{"issue_key":{"type":"string","example":"WEB-12"},"estimate_minutes":{"type":["integer","null"]},"story_points":{"type":["integer","null"]},"spent_minutes":{"type":["integer","null"]},"completion_pct":{"type":["integer","null"]}},"required":["issue_key","estimate_minutes","story_points","spent_minutes","completion_pct"]},"IssueLink":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["relates_to","blocks","duplicates"]},"direction":{"type":"string","enum":["out","in"],"description":"\"out\" = anchor → target, \"in\" = target → anchor."},"target_key":{"type":"string","example":"WEB-12"},"target_title":{"type":"string"},"target_status":{"type":"string"},"target_project_slug":{"type":"string"}},"required":["id","kind","direction","target_key","target_title","target_status","target_project_slug"]},"CommitRef":{"type":"object","properties":{"id":{"type":"string"},"repo":{"type":"string","example":"utter-ae/product"},"sha":{"type":"string","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"},"message":{"type":"string"},"url":{"type":"string","example":"https://github.com/utter-ae/product/commit/a1b2c3"},"author":{"type":["string","null"]},"committed_at":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["id","repo","sha","message","url","author","committed_at"]},"Doc":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"project_id":{"type":["string","null"]},"parent_id":{"type":["string","null"]},"icon":{"type":["string","null"]},"body_md":{"type":["string","null"]},"body_json":{},"created_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["id","title","project_id","parent_id","icon","body_md","created_at","updated_at"]},"Member":{"type":"object","properties":{"user_id":{"type":"string"},"email":{"type":"string"},"name":{"type":["string","null"]},"role":{"type":"string","enum":["owner","admin","member","viewer"]}},"required":["user_id","email","name","role"]},"Invite":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string","example":"user@example.com"},"role":{"type":"string","enum":["admin","member","viewer","guest"]},"invited_by_user_id":{"type":"string"},"expires_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"},"created_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["id","email","role","invited_by_user_id","expires_at","created_at"]},"InviteCreateInput":{"type":"object","properties":{"email":{"type":"string","format":"email","example":"user@example.com"},"role":{"type":"string","enum":["admin","member","viewer","guest"]}},"required":["email","role"]},"ProjectMember":{"type":"object","properties":{"user_id":{"type":"string"},"email":{"type":"string"},"name":{"type":["string","null"]},"role":{"type":"string","enum":["admin","member","viewer"]},"added_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["user_id","email","name","role","added_at"]},"ProjectMemberAddInput":{"type":"object","properties":{"user_id":{"type":"string","description":"ID of an existing workspace member."},"role":{"type":"string","enum":["admin","member","viewer"]}},"required":["user_id","role"]},"MemberPatchInput":{"type":"object","properties":{"role":{"type":"string","enum":["admin","member","viewer"],"description":"New role for the member. Cannot promote to owner; use the ownership-transfer flow."}},"required":["role"]},"Notification":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","example":"assigned"},"read_at":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z"},"created_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["id","kind","read_at","created_at"]},"SearchResult":{"type":"object","properties":{"type":{"type":"string","enum":["issue","doc"]},"id":{"type":"string"},"title":{"type":"string"},"url":{"type":["string","null"]}},"required":["type","id","title"]},"Me":{"type":"object","properties":{"keyId":{"type":"string"},"name":{"type":"string"},"workspaceSlug":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"expiresAt":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["keyId","name","workspaceSlug","scopes","expiresAt"]},"ApiKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","example":"CI deploy bot"},"prefix":{"type":"string","example":"utp_live_abcd"},"scopes":{"type":"array","items":{"type":"string"},"example":["issues:read","issues:write"]},"project_ids":{"type":["array","null"],"items":{"type":"string"}},"rate_limit_per_minute":{"type":["integer","null"]},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"},"expires_at":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z"},"last_used_at":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z"},"last_used_ip":{"type":["string","null"]},"revoked_at":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z"},"revoke_reason":{"type":["string","null"]}},"required":["id","name","prefix","scopes","project_ids","rate_limit_per_minute","created_by","created_at","expires_at","last_used_at","last_used_ip","revoked_at","revoke_reason"]},"CreatedApiKey":{"allOf":[{"$ref":"#/components/schemas/ApiKey"},{"type":"object","properties":{"plaintext":{"type":"string","example":"utp_live_abcd1234...","description":"Returned exactly once on create. Store it securely."}},"required":["plaintext"]}]},"Webhook":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri","example":"https://example.com/utter/webhook"},"event_types":{"type":"array","items":{"type":"string"},"example":["issue.created","comment.created"]},"secret_prefix":{"type":"string"},"disabled_at":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z"},"last_delivery_at":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z"},"last_delivery_status":{"type":["integer","null"]},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["id","url","event_types","secret_prefix","disabled_at","last_delivery_at","last_delivery_status","created_by","created_at"]},"CreatedWebhook":{"allOf":[{"$ref":"#/components/schemas/Webhook"},{"type":"object","properties":{"secret":{"type":"string","example":"utwhsec_...","description":"Returned exactly once on create or rotation."}},"required":["secret"]}]},"WebhookDelivery":{"type":"object","properties":{"delivery_id":{"type":"string"},"event_type":{"type":"string","example":"webhook.test"},"attempt":{"type":"integer","example":1},"status":{"type":"integer","example":200},"latency_ms":{"type":"integer","example":123},"error":{"type":"string"},"final":{"type":"integer","example":1},"ts":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["delivery_id","event_type","attempt","status","latency_ms","error","final","ts"]},"ApiKeyUsageDayPoint":{"type":"object","properties":{"date":{"type":"string","example":"2026-06-15"},"requests":{"type":"integer"},"errors":{"type":"integer"},"p50_ms":{"type":"integer"},"p95_ms":{"type":"integer"},"p99_ms":{"type":"integer"}},"required":["date","requests","errors","p50_ms","p95_ms","p99_ms"]},"ApiKeyUsage":{"type":"object","properties":{"key_id":{"type":"string"},"from":{"type":"string","example":"2026-05-17"},"to":{"type":"string","example":"2026-06-15"},"granularity":{"type":"string","enum":["day"]},"series":{"type":"array","items":{"$ref":"#/components/schemas/ApiKeyUsageDayPoint"}},"totals":{"type":"object","properties":{"requests":{"type":"integer"},"errors":{"type":"integer"},"p95_ms":{"type":"integer"}},"required":["requests","errors","p95_ms"]}},"required":["key_id","from","to","granularity","series","totals"]},"OauthApp":{"type":"object","properties":{"client_id":{"type":"string","example":"utoc_..."},"name":{"type":"string","example":"My CI Integration"},"redirect_uris":{"type":"array","items":{"type":"string","format":"uri"},"example":["https://example.com/callback"]},"scopes":{"type":"array","items":{"type":"string"},"example":["issues:read","comments:write"]},"is_public":{"type":"boolean","description":"True = PKCE public client (no secret)."},"created_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["client_id","name","redirect_uris","scopes","is_public","created_at"]},"CreatedOauthApp":{"allOf":[{"$ref":"#/components/schemas/OauthApp"},{"type":"object","properties":{"client_secret":{"type":["string","null"],"example":"utos_...","description":"Returned exactly once on create. Null for public (PKCE) clients."}},"required":["client_secret"]}]},"OauthAppCreateInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120,"example":"My CI Integration"},"redirect_uris":{"type":"array","items":{"type":"string","format":"uri"},"minItems":1,"maxItems":20,"example":["https://example.com/callback"]},"scopes":{"type":"array","items":{"type":"string"},"minItems":1,"example":["issues:read"]},"is_public":{"type":"boolean","description":"Set true for PKCE public clients (no secret).","example":false}},"required":["name","redirect_uris","scopes"]},"ProjectCreateInput":{"type":"object","properties":{"key":{"type":"string","example":"WEB"},"name":{"type":"string"},"slug":{"type":"string"},"description_md":{"type":"string"},"lead_user_id":{"type":"string"}},"required":["key","name"]},"ProjectPatchInput":{"type":"object","properties":{"name":{"type":"string"},"description_md":{"type":["string","null"]},"lead_user_id":{"type":["string","null"]},"estimation_unit":{"type":"string","enum":["time","points","none"]}}},"IssueCreateInput":{"type":"object","properties":{"type":{"type":"string","enum":["epic","story","task","bug","subtask"]},"title":{"type":"string"},"description_md":{"type":"string"},"status":{"type":"string","enum":["backlog","todo","in_progress","in_review","done","failed","cancelled"]},"status_id":{"type":"string","description":"Board status id (project_statuses); wins over status."},"priority":{"type":"string","enum":["lowest","low","medium","high","highest","critical"]},"assignee":{"type":"string","description":"user_id or email","example":"omar@haris.bz"},"labels":{"type":"array","items":{"type":"string"},"description":"label ids or names"},"parent":{"type":"string","example":"WEB-2"},"epic":{"type":"string","example":"WEB-2"},"start_at":{"type":["string","null"]},"due_at":{"type":["string","null"]},"estimate_minutes":{"type":["integer","null"]},"story_points":{"type":["integer","null"]}},"required":["type","title"]},"IssuePatchInput":{"type":"object","properties":{"title":{"type":"string"},"description_md":{"type":["string","null"]},"status":{"type":"string","enum":["backlog","todo","in_progress","in_review","done","failed","cancelled"]},"status_id":{"type":"string","description":"Board status id (project_statuses); wins over status."},"priority":{"type":"string","enum":["lowest","low","medium","high","highest","critical"]},"assignee":{"type":["string","null"],"description":"Primary assignee (user_id or email), or null to unassign. Back-compat single field; seeds a one-element assignee set."},"assignee_ids":{"type":"array","items":{"type":"string"},"description":"Full ordered assignee set (user_ids or emails), primary first. Wins over `assignee`; pass [] to unassign everyone."},"labels":{"type":"array","items":{"type":"string"}},"milestone_id":{"type":["string","null"]},"sprint_id":{"type":["string","null"],"description":"Attach the issue to a sprint (sprint id), or null to detach. This is how issues are added to / removed from a sprint."},"release_id":{"type":["string","null"],"description":"Attach the issue to a release (release id), or null to detach. This is how issues are added to / removed from a release."},"estimate_minutes":{"type":["integer","null"]},"story_points":{"type":["integer","null"]},"spent_minutes":{"type":["integer","null"]},"completion_pct":{"type":["integer","null"]},"start_at":{"type":["string","null"]},"due_at":{"type":["string","null"]}}},"IssueTransitionInput":{"type":"object","properties":{"status":{"type":"string","enum":["backlog","todo","in_progress","in_review","done","failed","cancelled"]},"rank":{"type":"string"}},"required":["status"]},"CommentCreateInput":{"type":"object","properties":{"body_md":{"type":"string"}},"required":["body_md"]},"LabelCreateInput":{"type":"object","properties":{"name":{"type":"string"},"color":{"type":"string"}},"required":["name","color"]},"LabelPatchInput":{"type":"object","properties":{"name":{"type":"string"},"color":{"type":"string"}}},"CustomFieldDefCreateInput":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["text","number","select","multi_select","date","checkbox","url","user","project","doc"]},"options":{"type":"array","items":{"type":"string"}},"applies_to":{"type":"array","items":{"type":"string","enum":["epic","story","task","bug","subtask"]}},"required":{"type":"boolean"}},"required":["name","kind"]},"CustomFieldValueInput":{"type":"object","properties":{"value":{}}},"SprintCreateInput":{"type":"object","properties":{"name":{"type":"string","example":"Sprint 7"},"goal":{"type":["string","null"],"description":"Sprint goal (markdown)."},"status":{"type":"string","enum":["planned","active","completed"]},"start_at":{"type":["string","null"],"description":"Date or ISO 8601."},"end_at":{"type":["string","null"],"description":"Date or ISO 8601."}},"required":["name"]},"StatusCreateInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80,"example":"In Review"},"name_ar":{"type":"string","maxLength":80,"example":"قيد المراجعة"},"color":{"type":"string","example":"#4FE8E5","description":"Hex color #RRGGBB."},"category":{"type":"string","enum":["backlog","todo","in_progress","in_review","done","failed","cancelled"],"description":"System category the column maps to (drives open/done semantics)."}},"required":["name","color","category"]},"StatusPatchInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"name_ar":{"type":["string","null"],"maxLength":80},"color":{"type":"string","description":"Hex color #RRGGBB."},"category":{"type":"string","enum":["backlog","todo","in_progress","in_review","done","failed","cancelled"],"description":"System category the column maps to (drives open/done semantics)."}}},"SprintPatchInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120,"example":"Sprint 7"},"goal":{"type":["string","null"],"description":"Sprint goal (markdown)."},"status":{"type":"string","enum":["planned","active","completed"]},"start_at":{"type":["string","null"],"description":"Date or ISO 8601."},"end_at":{"type":["string","null"],"description":"Date or ISO 8601."}}},"MilestoneCreateInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120,"example":"v2.0 Release"},"description_md":{"type":["string","null"],"description":"Description (markdown)."},"status":{"type":"string","enum":["planned","active","completed"]},"start_at":{"type":["string","null"],"description":"Date (YYYY-MM-DD) or ISO 8601."},"due_at":{"type":["string","null"],"description":"Date (YYYY-MM-DD) or ISO 8601."}},"required":["name"]},"MilestonePatchInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description_md":{"type":["string","null"]},"status":{"type":"string","enum":["planned","active","completed"]},"start_at":{"type":["string","null"]},"due_at":{"type":["string","null"]}}},"ReleaseCreateInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120,"example":"Autumn Launch"},"version":{"type":["string","null"],"maxLength":64,"example":"2.1.0"},"description_md":{"type":["string","null"],"description":"Release notes (markdown)."},"status":{"type":"string","enum":["planned","in_progress","released","cancelled"]},"target_date":{"type":["string","null"],"description":"Date (YYYY-MM-DD) or ISO 8601."}},"required":["name"]},"ReleasePatchInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"version":{"type":["string","null"],"maxLength":64},"description_md":{"type":["string","null"]},"status":{"type":"string","enum":["planned","in_progress","released","cancelled"],"description":"Setting status=released stamps released_at; leaving it clears released_at."},"target_date":{"type":["string","null"],"description":"Date (YYYY-MM-DD) or ISO 8601."}}},"SavedViewCreateInput":{"type":"object","properties":{"name":{"type":"string"},"filter":{},"is_shared":{"type":"boolean"}},"required":["name"]},"TimePatchInput":{"type":"object","properties":{"estimate_minutes":{"type":["integer","null"]},"story_points":{"type":["integer","null"]},"spent_minutes":{"type":["integer","null"]},"completion_pct":{"type":["integer","null"]}}},"IssueLinkCreateInput":{"type":"object","properties":{"kind":{"type":"string","enum":["relates_to","blocks","duplicates"]},"direction":{"type":"string","enum":["out","in"],"description":"\"out\" = anchor blocks/relates_to/duplicates target; \"in\" = target → anchor."},"target_key":{"type":"string","description":"Target issue KEY-NUM (e.g. WEB-12). Cross-project within the workspace is supported.","example":"WEB-12"}},"required":["kind","direction","target_key"]},"DocCreateInput":{"type":"object","properties":{"title":{"type":"string"},"project":{"type":"string","description":"project key to scope the doc"},"parent_id":{"type":"string"},"body_md":{"type":"string"},"body_json":{},"icon":{"type":"string"}}},"AttachmentIntentInput":{"type":"object","properties":{"file_name":{"type":"string"},"mime":{"type":"string"},"byte_size":{"type":"integer"},"comment_id":{"type":"string"}},"required":["file_name","mime","byte_size"]},"AttachmentCommitInput":{"type":"object","properties":{"r2_key":{"type":"string","description":"The exact r2_key returned by the intent call."},"file_name":{"type":"string"},"mime":{"type":"string"},"byte_size":{"type":"integer"},"comment_id":{"type":"string"}},"required":["r2_key","file_name","mime","byte_size"]},"ApiKeyCreateInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"scopes":{"type":"array","items":{"type":"string"},"minItems":1},"project_ids":{"type":["array","null"],"items":{"type":"string"}},"expires_at":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z"},"rate_limit_per_minute":{"type":["integer","null"],"minimum":1,"maximum":100000}},"required":["name","scopes"]},"ApiKeyPatchInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"rate_limit_per_minute":{"type":["integer","null"],"minimum":1,"maximum":100000},"expires_at":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z"}}},"WebhookCreateInput":{"type":"object","properties":{"url":{"type":"string","format":"uri","example":"https://example.com/utter/webhook"},"event_types":{"type":"array","items":{"type":"string"},"minItems":1,"example":["*"]}},"required":["url","event_types"]},"WebhookPatchInput":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"event_types":{"type":"array","items":{"type":"string"},"minItems":1},"enabled":{"type":"boolean"}}},"BulkIssuesCreateInput":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/IssueCreateInput"},"minItems":1,"maxItems":50}},"required":["items"]},"BulkCommentsCreateInput":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CommentCreateInput"},"minItems":1,"maxItems":50}},"required":["items"]},"BulkDocsCreateInput":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/DocCreateInput"},"minItems":1,"maxItems":50}},"required":["items"]},"BulkIssueResult":{"anyOf":[{"type":"object","properties":{"index":{"type":"integer"},"ok":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Issue"}},"required":["index","ok","data"]},{"type":"object","properties":{"index":{"type":"integer"},"ok":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation","rate_limited","conflict","idempotency_violation","internal_error"],"example":"validation"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["index","ok","error"]}]},"BulkCommentResult":{"anyOf":[{"type":"object","properties":{"index":{"type":"integer"},"ok":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Comment"}},"required":["index","ok","data"]},{"type":"object","properties":{"index":{"type":"integer"},"ok":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation","rate_limited","conflict","idempotency_violation","internal_error"],"example":"validation"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["index","ok","error"]}]},"BulkDocResult":{"anyOf":[{"type":"object","properties":{"index":{"type":"integer"},"ok":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Doc"}},"required":["index","ok","data"]},{"type":"object","properties":{"index":{"type":"integer"},"ok":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation","rate_limited","conflict","idempotency_violation","internal_error"],"example":"validation"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["index","ok","error"]}]},"Agent":{"type":"object","properties":{"agent_id":{"type":"string","example":"019e6f12-…","description":"The agent's user id — the value to pass as agent_id elsewhere and the id used when assigning issues to the agent."},"name":{"type":"string","example":"Omar's Claude Code"},"kind":{"type":"string","example":"claude","description":"Provider: claude, openai, cursor, copilot, gemini, deepseek, kimi, perplexity, or custom."},"owner_user_id":{"type":"string","description":"The human member who connected this agent."},"running_sessions":{"type":"integer","example":1},"last_activity_at":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z"},"created_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["agent_id","name","kind","owner_user_id","running_sessions","last_activity_at","created_at"]},"AgentSession":{"type":"object","properties":{"id":{"type":"string"},"agent_id":{"type":"string"},"agent_name":{"type":"string","example":"Omar's Claude Code"},"agent_kind":{"type":"string","example":"claude"},"state":{"type":"string","enum":["running","needs_input","review","done","failed","cancelled"],"example":"running"},"title":{"type":"string","example":"Fix flaky auth test"},"note":{"type":["string","null"],"description":"The agent's latest status note."},"external_url":{"type":["string","null"],"description":"Where the output lives — typically the PR URL."},"issue_id":{"type":["string","null"]},"issue_key":{"type":["string","null"],"example":"WEB-39"},"started_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"},"last_activity_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"},"ended_at":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["id","agent_id","agent_name","agent_kind","state","title","note","external_url","issue_id","issue_key","started_at","last_activity_at","ended_at"]},"ChatChannel":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["public","private","dm"]},"name":{"type":["string","null"],"description":"Null for DM channels."},"slug":{"type":["string","null"]},"topic":{"type":["string","null"]},"created_by":{"type":"string"},"archived_at":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z"},"last_message_at":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z"},"created_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"},"member_count":{"type":"integer"},"is_member":{"type":"boolean"}},"required":["id","kind","name","slug","topic","created_by","archived_at","last_message_at","created_at"]},"ChatChannelMember":{"type":"object","properties":{"user_id":{"type":"string"},"role":{"type":"string","enum":["owner","member"]},"joined_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["user_id","role","joined_at"]},"ChatMessage":{"type":"object","properties":{"id":{"type":"string"},"channel_id":{"type":"string"},"author_id":{"type":"string"},"body_md":{"type":"string"},"parent_id":{"type":["string","null"],"description":"The message this one replies to (may itself be a reply); null when top-level."},"root_id":{"type":["string","null"],"description":"Thread root message id; null for a top-level message."},"reply_count":{"type":"integer"},"last_reply_at":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z"},"edited_at":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z"},"created_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"},"reactions":{"type":"array","items":{"type":"object","properties":{"emoji":{"type":"string"},"count":{"type":"integer"},"user_ids":{"type":"array","items":{"type":"string"}}},"required":["emoji","count","user_ids"]}}},"required":["id","channel_id","author_id","body_md","parent_id","root_id","reply_count","last_reply_at","edited_at","created_at","reactions"]},"ChatReactions":{"type":"object","properties":{"message_id":{"type":"string"},"reactions":{"type":"array","items":{"type":"object","properties":{"emoji":{"type":"string"},"count":{"type":"integer"},"user_ids":{"type":"array","items":{"type":"string"}}},"required":["emoji","count","user_ids"]}}},"required":["message_id","reactions"]},"ChatChannelCreateInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"kind":{"type":"string","enum":["public","private"],"description":"Defaults to public. DMs cannot be created over the API."},"topic":{"type":"string","maxLength":280}},"required":["name"]},"ChatChannelPatchInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"topic":{"type":["string","null"],"maxLength":280},"archived":{"type":"boolean"}}},"ChatMessageCreateInput":{"type":"object","properties":{"body_md":{"type":"string","minLength":1,"maxLength":64000},"parent_id":{"type":"string","description":"Reply to this message — the thread root or any reply within it (nested replies are supported)."}},"required":["body_md"]},"FormField":{"type":"object","properties":{"id":{"type":"string"},"position":{"type":"integer"},"kind":{"type":"string","enum":["short_text","long_text","select","multi_select","number","date","email","radio","phone","url","rating","section","file","checkbox"]},"label":{"type":"string"},"help_text":{"type":["string","null"]},"placeholder":{"type":["string","null"]},"required":{"type":"boolean"},"options":{"type":"array","items":{"type":"string"}},"mapping":{"type":"string","enum":["none","title","description","priority"]},"min_value":{"type":["number","null"]},"max_value":{"type":["number","null"]},"max_length":{"type":["integer","null"]},"default_value":{"type":["string","null"]},"visibility_rule":{},"created_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["id","position","kind","label","help_text","placeholder","required","options","mapping","min_value","max_value","max_length","default_value","created_at"]},"FormSummary":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":["string","null"]},"status":{"type":"string","enum":["draft","published","closed"]},"public_enabled":{"type":"boolean"},"share_url":{"type":["string","null"],"description":"Public /f/<token> URL; null unless public sharing is enabled."},"submission_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["id","title","description","status","public_enabled","share_url","submission_count","created_at","updated_at"]},"Form":{"allOf":[{"$ref":"#/components/schemas/FormSummary"},{"type":"object","properties":{"issue_type":{"type":"string","enum":["task","story","bug"]},"priority":{"type":"string"},"success_message":{"type":["string","null"]},"accent_color":{"type":["string","null"]},"header_text":{"type":["string","null"]},"show_project_header":{"type":"boolean"},"close_at":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z"},"response_limit":{"type":["integer","null"]},"one_per_email":{"type":"boolean"},"confirmation_mode":{"type":"string","enum":["message","redirect"]},"redirect_url":{"type":["string","null"]},"default_assignee_id":{"type":["string","null"]},"default_label_ids":{"type":"array","items":{"type":"string"}},"default_sprint_id":{"type":["string","null"]},"default_status_id":{"type":["string","null"]},"access_mode":{"type":"string","enum":["anyone","members","invited"]},"allowed_emails":{"type":"array","items":{"type":"string"}},"has_password":{"type":"boolean"},"notify_submission":{"type":"boolean"},"confirmation_email":{"type":"boolean"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/FormField"}}},"required":["issue_type","priority","success_message","accent_color","header_text","show_project_header","close_at","response_limit","one_per_email","confirmation_mode","redirect_url","default_assignee_id","default_label_ids","default_sprint_id","default_status_id","access_mode","allowed_emails","has_password","notify_submission","confirmation_email","fields"]}]},"FormSubmission":{"type":"object","properties":{"id":{"type":"string"},"answers":{"type":"object","additionalProperties":{},"description":"field_id → submitted value, stored verbatim."},"submitter_email":{"type":["string","null"]},"source":{"type":"string","enum":["public","internal"]},"created_issue_id":{"type":["string","null"]},"created_issue_key":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["id","answers","submitter_email","source","created_issue_id","created_issue_key","created_at"]},"FormCreateInput":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":2000},"issue_type":{"type":"string","enum":["task","story","bug"]},"priority":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["short_text","long_text","select","multi_select","number","date","email","radio","phone","url","rating","section","file","checkbox"]},"label":{"type":"string","minLength":1,"maxLength":200},"required":{"type":"boolean"},"options":{"type":"array","items":{"type":"string","maxLength":200},"maxItems":50},"placeholder":{"type":"string","maxLength":200},"help_text":{"type":"string","maxLength":500},"mapping":{"type":"string","enum":["none","title","description","priority"]},"min_value":{"type":"number"},"max_value":{"type":"number"},"max_length":{"type":"integer","minimum":1,"maximum":20000},"default_value":{"type":"string","maxLength":500}},"required":["kind","label"]},"maxItems":200}},"required":["title"]},"FormPatchInput":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"description":{"type":["string","null"],"maxLength":2000},"status":{"type":"string","enum":["draft","published","closed"]},"issue_type":{"type":"string","enum":["task","story","bug"]},"priority":{"type":"string"},"success_message":{"type":["string","null"]},"accent_color":{"type":["string","null"]},"header_text":{"type":["string","null"]},"show_project_header":{"type":"boolean"},"close_at":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z"},"response_limit":{"type":["integer","null"],"minimum":1,"maximum":1000000},"one_per_email":{"type":"boolean"},"confirmation_mode":{"type":"string","enum":["message","redirect"]},"redirect_url":{"type":["string","null"]},"default_assignee_id":{"type":["string","null"]},"default_label_ids":{"type":"array","items":{"type":"string"}},"default_sprint_id":{"type":["string","null"]},"default_status_id":{"type":["string","null"]},"access_mode":{"type":"string","enum":["anyone","members","invited"]},"allowed_emails":{"type":"array","items":{"type":"string"},"maxItems":500},"notify_submission":{"type":"boolean"},"confirmation_email":{"type":"boolean"},"public_enabled":{"type":"boolean"}}},"Automation":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"enabled":{"type":"boolean"},"trigger":{"type":"string","enum":["issue.created","issue.status_changed","issue.priority_changed","issue.assigned","issue.unassigned","comment.added"]},"conditions":{"type":["object","null"],"properties":{"match":{"type":"string","enum":["all","any"]},"rules":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["project","type","priority","status","assignee","label","title"]},"op":{"type":"string","enum":["is","is_not","is_one_of","contains","is_set","is_empty"]},"value":{"anyOf":[{"type":"string","maxLength":500},{"type":"array","items":{"type":"string","maxLength":100},"maxItems":50}]}},"required":["field","op"]},"maxItems":10}},"required":["match","rules"]},"actions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["set_status","set_priority","assign_to","unassign","add_label","remove_label","move_to_sprint","add_comment","notify_agent"]},"status":{"type":"string"},"priority":{"type":"string"},"assign_target":{"type":"string","enum":["member","triggering_user"]},"member_id":{"type":"string"},"label_id":{"type":"string"},"sprint_target":{"type":"string","enum":["active","specific","backlog"]},"sprint_id":{"type":"string"},"comment":{"type":"string","maxLength":2000},"agent_user_id":{"type":"string"}},"required":["type"]}},"project_id":{"type":["string","null"],"description":"Derived from a project-is condition; null = all projects."},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["id","name","enabled","trigger","conditions","actions","project_id","created_by","created_at","updated_at"]},"AutomationRun":{"type":"object","properties":{"id":{"type":"string"},"automation_id":{"type":"string"},"issue_id":{"type":["string","null"]},"trigger":{"type":"string"},"status":{"type":"string","enum":["ok","partial","error"]},"actions_applied":{"type":["array","null"],"items":{"type":"object","properties":{"type":{"type":"string"},"ok":{"type":"boolean"},"detail":{"type":"string"}},"required":["type","ok"]}},"detail":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["id","automation_id","issue_id","trigger","status","actions_applied","detail","created_at"]},"AutomationCreateInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"trigger":{"type":"string","enum":["issue.created","issue.status_changed","issue.priority_changed","issue.assigned","issue.unassigned","comment.added"]},"conditions":{"type":["object","null"],"properties":{"match":{"type":"string","enum":["all","any"]},"rules":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["project","type","priority","status","assignee","label","title"]},"op":{"type":"string","enum":["is","is_not","is_one_of","contains","is_set","is_empty"]},"value":{"anyOf":[{"type":"string","maxLength":500},{"type":"array","items":{"type":"string","maxLength":100},"maxItems":50}]}},"required":["field","op"]},"maxItems":10}},"required":["match","rules"]},"actions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["set_status","set_priority","assign_to","unassign","add_label","remove_label","move_to_sprint","add_comment","notify_agent"]},"status":{"type":"string"},"priority":{"type":"string"},"assign_target":{"type":"string","enum":["member","triggering_user"]},"member_id":{"type":"string"},"label_id":{"type":"string"},"sprint_target":{"type":"string","enum":["active","specific","backlog"]},"sprint_id":{"type":"string"},"comment":{"type":"string","maxLength":2000},"agent_user_id":{"type":"string"}},"required":["type"]},"minItems":1,"maxItems":10},"project_id":{"type":["string","null"]},"enabled":{"type":"boolean"}},"required":["name","trigger","actions"]},"AutomationPatchInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"trigger":{"type":"string","enum":["issue.created","issue.status_changed","issue.priority_changed","issue.assigned","issue.unassigned","comment.added"]},"conditions":{"type":["object","null"],"properties":{"match":{"type":"string","enum":["all","any"]},"rules":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["project","type","priority","status","assignee","label","title"]},"op":{"type":"string","enum":["is","is_not","is_one_of","contains","is_set","is_empty"]},"value":{"anyOf":[{"type":"string","maxLength":500},{"type":"array","items":{"type":"string","maxLength":100},"maxItems":50}]}},"required":["field","op"]},"maxItems":10}},"required":["match","rules"]},"actions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["set_status","set_priority","assign_to","unassign","add_label","remove_label","move_to_sprint","add_comment","notify_agent"]},"status":{"type":"string"},"priority":{"type":"string"},"assign_target":{"type":"string","enum":["member","triggering_user"]},"member_id":{"type":"string"},"label_id":{"type":"string"},"sprint_target":{"type":"string","enum":["active","specific","backlog"]},"sprint_id":{"type":"string"},"comment":{"type":"string","maxLength":2000},"agent_user_id":{"type":"string"}},"required":["type"]},"minItems":1,"maxItems":10},"project_id":{"type":["string","null"]},"enabled":{"type":"boolean"}}},"WorkflowNode":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["start","agent","person","condition","parallel","end"]},"assignee_user_id":{"type":["string","null"],"description":"The agent (isAgent user) or person for agent/person nodes; null otherwise."},"config":{"description":"Kind-specific config. condition: { match, rules } (AutomationConditions shape). agent: { title?, instructions? }. parallel: { join: \"all\"|\"any\" }."},"label":{"type":["string","null"]},"pos_x":{"type":"integer"},"pos_y":{"type":"integer"}},"required":["id","kind","assignee_user_id","label","pos_x","pos_y"]},"WorkflowEdge":{"type":"object","properties":{"id":{"type":"string"},"source_node_id":{"type":"string"},"target_node_id":{"type":"string"},"branch_label":{"type":["string","null"],"description":"\"true\"|\"false\" on a condition node's out-edges; null otherwise."}},"required":["id","source_node_id","target_node_id","branch_label"]},"Workflow":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","example":"Triage and build"},"description":{"type":["string","null"]},"status":{"type":"string","enum":["draft","enabled"]},"created_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["id","name","description","status","created_at","updated_at"]},"WorkflowDetail":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"status":{"type":"string","enum":["draft","enabled"]},"nodes":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowNode"}},"edges":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowEdge"}},"created_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["id","name","description","status","nodes","edges","created_at","updated_at"]},"WorkflowRun":{"type":"object","properties":{"id":{"type":"string"},"issue_id":{"type":"string"},"status":{"type":"string","enum":["running","completed","failed","cancelled"]},"current_summary":{"type":["string","null"]},"started_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"},"ended_at":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["id","issue_id","status","current_summary","started_at","ended_at"]},"WorkflowRunNode":{"type":"object","properties":{"node_id":{"type":"string"},"state":{"type":"string","enum":["pending","active","done","skipped","failed"]},"branch_taken":{"type":["string","null"]}},"required":["node_id","state","branch_taken"]},"WorkflowRunDetail":{"type":"object","properties":{"id":{"type":"string"},"workflow_id":{"type":"string"},"workflow_name":{"type":"string"},"issue_id":{"type":"string"},"status":{"type":"string","enum":["running","completed","failed","cancelled"]},"current_summary":{"type":["string","null"]},"nodes":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowRunNode"}},"started_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"},"ended_at":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["id","workflow_id","workflow_name","issue_id","status","current_summary","nodes","started_at","ended_at"]},"WorkflowCreateInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":"string","maxLength":500}},"required":["name"]},"WorkflowPatchInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":["string","null"],"maxLength":500},"status":{"type":"string","enum":["draft","enabled"]}}},"WorkflowGraphInput":{"type":"object","properties":{"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"kind":{"type":"string","enum":["start","agent","person","condition","parallel","end"]},"assignee_user_id":{"type":["string","null"]},"config":{},"label":{"type":["string","null"],"maxLength":120},"pos_x":{"type":"integer"},"pos_y":{"type":"integer"}},"required":["id","kind","pos_x","pos_y"]},"maxItems":200},"edges":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"source_node_id":{"type":"string","minLength":1},"target_node_id":{"type":"string","minLength":1},"branch_label":{"type":["string","null"],"maxLength":120}},"required":["id","source_node_id","target_node_id"]},"maxItems":400}},"required":["nodes","edges"]},"WorkflowStartInput":{"type":"object","properties":{"workflow_id":{"type":"string","minLength":1}},"required":["workflow_id"]},"WorkflowCompleteStageInput":{"type":"object","properties":{"node_id":{"type":"string","minLength":1,"description":"Complete this active stage; omit to complete all active stages."}}},"WorkspaceView":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"filter":{"description":"Cross-project filter blob (projectIds[], statuses[], priorities[], types[], assigneeId, sort)."},"is_shared":{"type":"boolean"},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["id","name","is_shared","created_by","created_at","updated_at"]},"WorkspaceViewCreateInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"filter":{"type":"object","properties":{"projectIds":{"type":"array","items":{"type":"string"}},"statuses":{"type":"array","items":{"type":"string"}},"priorities":{"type":"array","items":{"type":"string"}},"types":{"type":"array","items":{"type":"string"}},"assigneeId":{"type":["string","null"]},"sort":{"type":"string","enum":["updated_desc","created_desc","priority_desc","due_asc"]}},"required":["projectIds","statuses","priorities","types","assigneeId","sort"]},"is_shared":{"type":"boolean","description":"Defaults to true."}},"required":["name"]},"WorkspaceUsage":{"type":"object","properties":{"plan":{"type":"object","properties":{"plan":{"type":"string","enum":["free","pro","business"]},"status":{"type":["string","null"]},"trialing":{"type":"boolean"},"cycle":{"type":["string","null"]},"current_period_end":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["plan","status","trialing","cycle","current_period_end"]},"storage":{"type":"object","properties":{"used_bytes":{"type":"integer"},"cap_bytes":{"type":"integer"},"base_cap_bytes":{"type":"integer"},"addon_bytes":{"type":"integer"},"remaining_bytes":{"type":"integer"},"used_pct":{"type":"integer"}},"required":["used_bytes","cap_bytes","base_cap_bytes","addon_bytes","remaining_bytes","used_pct"]},"ai_credits":{"type":"object","properties":{"monthly_grant":{"type":"integer"},"used":{"type":"integer"},"remaining":{"type":"integer"},"topup_balance":{"type":"integer"},"daily_limit":{"type":"integer"},"daily_used":{"type":"integer"},"daily_remaining":{"type":"integer"}},"required":["monthly_grant","used","remaining","topup_balance","daily_limit","daily_used","daily_remaining"]}},"required":["plan","storage","ai_credits"]},"DocComment":{"type":"object","properties":{"id":{"type":"string"},"doc_id":{"type":"string"},"parent_id":{"type":["string","null"]},"author":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","email","name"]},"body_md":{"type":"string"},"body_html":{"type":"string"},"created_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["id","doc_id","parent_id","author","body_md","body_html","created_at","updated_at"]},"DocVersionSummary":{"type":"object","properties":{"id":{"type":"string"},"doc_id":{"type":"string"},"title":{"type":"string"},"created_by":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","email","name"]},"created_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"},"body_md_length":{"type":"integer"}},"required":["id","doc_id","title","created_by","created_at","body_md_length"]},"DocVersion":{"type":"object","properties":{"id":{"type":"string"},"doc_id":{"type":"string"},"title":{"type":"string"},"body_json":{},"body_md":{"type":["string","null"]},"created_by":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","email","name"]},"created_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["id","doc_id","title","body_md","created_by","created_at"]},"Portfolio":{"type":"object","properties":{"id":{"type":"string"},"workspace_id":{"type":"string"},"name":{"type":"string","example":"Platform"},"description_md":{"type":["string","null"]},"color":{"type":"string","example":"#8b8f98"},"lead_user_id":{"type":["string","null"]},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["id","workspace_id","name","description_md","color","lead_user_id","created_by","created_at","updated_at"]},"PortfolioCreateInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description_md":{"type":["string","null"],"maxLength":10000},"color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","example":"#8b8f98"},"lead_user_id":{"type":["string","null"]}},"required":["name"]},"PortfolioPatchInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description_md":{"type":["string","null"],"maxLength":10000},"color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"lead_user_id":{"type":["string","null"]}}},"PortfolioProject":{"type":"object","properties":{"portfolio_id":{"type":"string"},"project_id":{"type":"string"}},"required":["portfolio_id","project_id"]},"PortfolioProjectAddInput":{"type":"object","properties":{"project_id":{"type":"string","minLength":1}},"required":["project_id"]},"KeyResult":{"type":"object","properties":{"id":{"type":"string"},"goal_id":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["manual","auto"]},"unit":{"type":["string","null"],"example":"%"},"start_value":{"type":["number","null"]},"target_value":{"type":["number","null"]},"current_value":{"type":["number","null"]},"weight":{"type":"number","example":1},"scope":{"type":["object","null"],"properties":{"project_ids":{"type":"array","items":{"type":"string"}},"issue_types":{"type":"array","items":{"type":"string","enum":["epic","story","task","bug","subtask"]}},"label_ids":{"type":"array","items":{"type":"string"}},"assignee_id":{"type":["string","null"]}},"description":"Auto-KR work scope; null = inherit the goal's portfolio/workspace scope. Unknown ids are dropped."},"progress_pct":{"type":["integer","null"]},"created_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["id","goal_id","title","kind","unit","start_value","target_value","current_value","weight","scope","progress_pct","created_at","updated_at"]},"KeyResultCreateInput":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"kind":{"type":"string","enum":["manual","auto"]},"unit":{"type":["string","null"],"maxLength":24},"start_value":{"type":["number","null"]},"target_value":{"type":["number","null"]},"current_value":{"type":["number","null"]},"weight":{"type":"number","exclusiveMinimum":0,"maximum":999,"description":"Relative weight in the goal roll-up (default 1)."},"scope":{"type":["object","null"],"properties":{"project_ids":{"type":"array","items":{"type":"string"}},"issue_types":{"type":"array","items":{"type":"string","enum":["epic","story","task","bug","subtask"]}},"label_ids":{"type":"array","items":{"type":"string"}},"assignee_id":{"type":["string","null"]}},"description":"Auto KRs only; ignored for manual."}},"required":["title","kind"]},"KeyResultPatchInput":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"unit":{"type":["string","null"],"maxLength":24},"start_value":{"type":["number","null"]},"target_value":{"type":["number","null"]},"current_value":{"type":["number","null"]},"weight":{"type":"number","exclusiveMinimum":0,"maximum":999},"scope":{"type":["object","null"],"properties":{"project_ids":{"type":"array","items":{"type":"string"}},"issue_types":{"type":"array","items":{"type":"string","enum":["epic","story","task","bug","subtask"]}},"label_ids":{"type":"array","items":{"type":"string"}},"assignee_id":{"type":["string","null"]}},"description":"Applied only to auto KRs."}}},"Goal":{"type":"object","properties":{"id":{"type":"string"},"workspace_id":{"type":"string"},"title":{"type":"string","example":"Reach 1,000 active workspaces"},"description_md":{"type":["string","null"]},"portfolio_id":{"type":["string","null"],"description":"null = company goal (not grouped under a portfolio)."},"parent_goal_id":{"type":["string","null"]},"owner_user_id":{"type":["string","null"]},"cycle_start_at":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z"},"cycle_due_at":{"type":["string","null"],"format":"date-time","example":"2026-05-28T14:30:00Z"},"status_override":{"type":["string","null"],"enum":["on_track","at_risk","off_track","done","not_started",null],"description":"Manual status override, or null when the status is fully derived."},"status":{"type":"string","enum":["on_track","at_risk","off_track","done","not_started"],"description":"Derived roll-up status (override applied). not_started = no measured progress yet."},"progress_pct":{"type":["integer","null"],"description":"Rolled-up 0-100, or null when nothing is measured."},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-05-28T14:30:00Z"}},"required":["id","workspace_id","title","description_md","portfolio_id","parent_goal_id","owner_user_id","cycle_start_at","cycle_due_at","status_override","status","progress_pct","created_by","created_at","updated_at"]},"GoalDetail":{"allOf":[{"$ref":"#/components/schemas/Goal"},{"type":"object","properties":{"portfolio_name":{"type":["string","null"]},"parent_title":{"type":["string","null"]},"key_results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["manual","auto"]},"unit":{"type":["string","null"]},"start_value":{"type":["number","null"]},"target_value":{"type":["number","null"]},"current_value":{"type":["number","null"]},"weight":{"type":"number"},"scope":{"type":["object","null"],"properties":{"project_ids":{"type":"array","items":{"type":"string"}},"issue_types":{"type":"array","items":{"type":"string","enum":["epic","story","task","bug","subtask"]}},"label_ids":{"type":"array","items":{"type":"string"}},"assignee_id":{"type":["string","null"]}},"description":"Auto-KR work scope; null = inherit the goal's portfolio/workspace scope. Unknown ids are dropped."},"progress_pct":{"type":["integer","null"]}},"required":["id","title","kind","unit","start_value","target_value","current_value","weight","scope","progress_pct"]}},"children":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"progress_pct":{"type":["integer","null"]},"status":{"type":"string","enum":["on_track","at_risk","off_track","done","not_started"],"description":"Derived roll-up status (override applied). not_started = no measured progress yet."}},"required":["id","title","progress_pct","status"]}},"watcher_count":{"type":"integer"}},"required":["portfolio_name","parent_title","key_results","children","watcher_count"]}]},"GoalCreateInput":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"description_md":{"type":["string","null"],"maxLength":20000},"portfolio_id":{"type":["string","null"],"description":"Group under a portfolio, or omit/null for a company goal."},"parent_goal_id":{"type":["string","null"],"description":"Alignment parent. Must stay acyclic and within the depth cap."},"owner_user_id":{"type":["string","null"]},"cycle_start_at":{"type":["string","null"],"example":"2026-07-01"},"cycle_due_at":{"type":["string","null"],"example":"2026-09-30"}},"required":["title"]},"GoalPatchInput":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"description_md":{"type":["string","null"],"maxLength":20000},"portfolio_id":{"type":["string","null"]},"parent_goal_id":{"type":["string","null"]},"owner_user_id":{"type":["string","null"]},"cycle_start_at":{"type":["string","null"]},"cycle_due_at":{"type":["string","null"]},"status_override":{"type":["string","null"],"enum":["on_track","at_risk","off_track","done",null],"description":"Set a manual status, or null to clear the override."}}},"Pagination":{"type":"object","properties":{"next_cursor":{"type":["string","null"],"example":null}},"required":["next_cursor"]}},"parameters":{}},"paths":{"/v1/me":{"get":{"summary":"Identity for this API key.","tags":["Meta"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Me"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces":{"get":{"summary":"List workspaces this key can access.","tags":["Workspaces"],"security":[{"bearerAuth":["workspaces:read"]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Workspace"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}":{"get":{"summary":"Workspace detail.","tags":["Workspaces"],"security":[{"bearerAuth":["workspaces:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Workspace"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"summary":"Update workspace name.","tags":["Workspaces"],"security":[{"bearerAuth":["workspaces:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspacePatchInput"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Workspace"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/api-keys":{"get":{"summary":"List API keys.","tags":["Developer"],"security":[{"bearerAuth":["api_keys:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Create an API key. Plaintext is returned exactly once.","tags":["Developer"],"security":[{"bearerAuth":["api_keys:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreateInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CreatedApiKey"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/api-keys/{id}":{"get":{"summary":"API key detail.","tags":["Developer"],"security":[{"bearerAuth":["api_keys:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApiKey"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"summary":"Update API key rate limit.","tags":["Developer"],"security":[{"bearerAuth":["api_keys:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyPatchInput"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApiKey"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Revoke an API key.","tags":["Developer"],"security":[{"bearerAuth":["api_keys:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"revoked":{"type":"boolean","enum":[true]}},"required":["id","revoked"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/api-keys/{id}/usage":{"get":{"summary":"Per-day request/error/latency rollup for a single API key (max 90-day window).","tags":["Developer"],"security":[{"bearerAuth":["api_keys:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","example":"2026-05-17","description":"Start date (YYYY-MM-DD). Defaults to 30 days ago. Window capped at 90 days."},"required":false,"description":"Start date (YYYY-MM-DD). Defaults to 30 days ago. Window capped at 90 days.","name":"from","in":"query"},{"schema":{"type":"string","example":"2026-06-15","description":"End date (YYYY-MM-DD). Defaults to today."},"required":false,"description":"End date (YYYY-MM-DD). Defaults to today.","name":"to","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApiKeyUsage"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/webhooks":{"get":{"summary":"List webhooks.","tags":["Developer"],"security":[{"bearerAuth":["webhooks:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Create a webhook. Signing secret is returned exactly once.","tags":["Developer"],"security":[{"bearerAuth":["webhooks:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreateInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CreatedWebhook"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/webhooks/{id}":{"get":{"summary":"Webhook detail.","tags":["Developer"],"security":[{"bearerAuth":["webhooks:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Webhook"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"summary":"Update or re-enable a webhook.","tags":["Developer"],"security":[{"bearerAuth":["webhooks:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPatchInput"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Webhook"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Delete a webhook.","tags":["Developer"],"security":[{"bearerAuth":["webhooks:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/webhooks/{id}/deliveries":{"get":{"summary":"List recent webhook delivery history.","tags":["Developer"],"security":[{"bearerAuth":["webhooks:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/webhooks/{id}/rotate-secret":{"post":{"summary":"Rotate webhook signing secret. New secret is returned exactly once.","tags":["Developer"],"security":[{"bearerAuth":["webhooks:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CreatedWebhook"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/webhooks/{id}/test":{"post":{"summary":"Send one signed webhook.test delivery to the endpoint.","tags":["Developer"],"security":[{"bearerAuth":["webhooks:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"responses":{"202":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookDelivery"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/oauth-apps":{"get":{"summary":"List OAuth apps.","tags":["Developer"],"security":[{"bearerAuth":["oauth_apps:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OauthApp"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Register an OAuth app. client_secret is returned exactly once (null for public/PKCE clients).","tags":["Developer"],"security":[{"bearerAuth":["oauth_apps:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OauthAppCreateInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CreatedOauthApp"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/oauth-apps/{clientId}":{"get":{"summary":"OAuth app detail.","tags":["Developer"],"security":[{"bearerAuth":["oauth_apps:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"utoc_...","description":"OAuth app client ID."},"required":true,"description":"OAuth app client ID.","name":"clientId","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OauthApp"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Revoke an OAuth app.","tags":["Developer"],"security":[{"bearerAuth":["oauth_apps:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"utoc_...","description":"OAuth app client ID."},"required":true,"description":"OAuth app client ID.","name":"clientId","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"client_id":{"type":"string"},"revoked":{"type":"boolean","enum":[true]}},"required":["client_id","revoked"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects":{"get":{"summary":"List projects.","tags":["Projects"],"security":[{"bearerAuth":["projects:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Project"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Create a project.","tags":["Projects"],"security":[{"bearerAuth":["projects:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectCreateInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}":{"get":{"summary":"Project detail.","tags":["Projects"],"security":[{"bearerAuth":["projects:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"summary":"Update a project.","tags":["Projects"],"security":[{"bearerAuth":["projects:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectPatchInput"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Archive a project (soft).","tags":["Projects"],"security":[{"bearerAuth":["projects:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/restore":{"post":{"summary":"Restore an archived project.","tags":["Projects"],"security":[{"bearerAuth":["projects:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/members":{"get":{"summary":"List project members (explicit access list for scoped projects).","tags":["Projects"],"security":[{"bearerAuth":["projects:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProjectMember"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Add or update a project member. Idempotent — updates role if already a member. User must be a workspace member. Admin-only scope.","tags":["Projects"],"security":[{"bearerAuth":["projects:admin"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectMemberAddInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectMember"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/members/{userId}":{"delete":{"summary":"Remove a user from the project member list. Admin-only scope.","tags":["Projects"],"security":[{"bearerAuth":["projects:admin"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string"},"required":true,"name":"userId","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"user_id":{"type":"string"},"removed":{"type":"boolean","enum":[true]}},"required":["user_id","removed"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/issues":{"get":{"summary":"List issues.","tags":["Issues"],"security":[{"bearerAuth":["issues:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string"},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","description":"user_id, email, or \"me\" (the calling key's own user)."},"required":false,"description":"user_id, email, or \"me\" (the calling key's own user).","name":"assignee","in":"query"},{"schema":{"type":"string","description":"user_id, email, or \"me\" (the calling key's own user)."},"required":false,"description":"user_id, email, or \"me\" (the calling key's own user).","name":"reporter","in":"query"},{"schema":{"type":"string"},"required":false,"name":"label","in":"query"},{"schema":{"type":"string"},"required":false,"name":"priority","in":"query"},{"schema":{"type":"string"},"required":false,"name":"type","in":"query"},{"schema":{"type":"string","description":"Sprint id to filter by."},"required":false,"description":"Sprint id to filter by.","name":"sprint","in":"query"},{"schema":{"type":"string","description":"Milestone id to filter by."},"required":false,"description":"Milestone id to filter by.","name":"milestone","in":"query"},{"schema":{"type":"string","description":"Issue id to list its subtasks. Pass \"none\" to return only top-level issues (no parent)."},"required":false,"description":"Issue id to list its subtasks. Pass \"none\" to return only top-level issues (no parent).","name":"parent","in":"query"},{"schema":{"type":"string"},"required":false,"name":"q","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Issue"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Create an issue.","tags":["Issues"],"security":[{"bearerAuth":["issues:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssueCreateInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Issue"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/issues/{issueKey}":{"get":{"summary":"Issue detail.","tags":["Issues"],"security":[{"bearerAuth":["issues:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"WEB-39","description":"Issue key (KEY-N)."},"required":true,"description":"Issue key (KEY-N).","name":"issueKey","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Issue"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"summary":"Update an issue.","tags":["Issues"],"security":[{"bearerAuth":["issues:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"WEB-39","description":"Issue key (KEY-N)."},"required":true,"description":"Issue key (KEY-N).","name":"issueKey","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssuePatchInput"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Issue"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Archive an issue (soft).","tags":["Issues"],"security":[{"bearerAuth":["issues:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"WEB-39","description":"Issue key (KEY-N)."},"required":true,"description":"Issue key (KEY-N).","name":"issueKey","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Issue"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/issues/{issueKey}/restore":{"post":{"summary":"Restore an archived issue.","tags":["Issues"],"security":[{"bearerAuth":["issues:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"WEB-39","description":"Issue key (KEY-N)."},"required":true,"description":"Issue key (KEY-N).","name":"issueKey","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Issue"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/issues/{issueKey}/transition":{"post":{"summary":"Transition status (board move).","tags":["Issues"],"security":[{"bearerAuth":["issues:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"WEB-39","description":"Issue key (KEY-N)."},"required":true,"description":"Issue key (KEY-N).","name":"issueKey","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssueTransitionInput"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Issue"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/issues/bulk":{"post":{"summary":"Bulk-create issues (1–50). Returns a per-item result array; 201 when all succeed, 207 when some fail.","tags":["Issues"],"security":[{"bearerAuth":["issues:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkIssuesCreateInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BulkIssueResult"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/issues/{issueKey}/comments":{"get":{"summary":"List comments.","tags":["Comments"],"security":[{"bearerAuth":["comments:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"WEB-39","description":"Issue key (KEY-N)."},"required":true,"description":"Issue key (KEY-N).","name":"issueKey","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Comment"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Create a comment.","tags":["Comments"],"security":[{"bearerAuth":["comments:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"WEB-39","description":"Issue key (KEY-N)."},"required":true,"description":"Issue key (KEY-N).","name":"issueKey","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentCreateInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Comment"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/issues/{issueKey}/comments/bulk":{"post":{"summary":"Bulk-create comments on one issue (1–50). Returns a per-item result array; 201 when all succeed, 207 when some fail.","tags":["Comments"],"security":[{"bearerAuth":["comments:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"WEB-39","description":"Issue key (KEY-N)."},"required":true,"description":"Issue key (KEY-N).","name":"issueKey","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkCommentsCreateInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BulkCommentResult"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/issues/{issueKey}/comments/{id}":{"patch":{"summary":"Edit a comment.","tags":["Comments"],"security":[{"bearerAuth":["comments:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"WEB-39","description":"Issue key (KEY-N)."},"required":true,"description":"Issue key (KEY-N).","name":"issueKey","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentCreateInput"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Comment"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Delete a comment.","tags":["Comments"],"security":[{"bearerAuth":["comments:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"WEB-39","description":"Issue key (KEY-N)."},"required":true,"description":"Issue key (KEY-N).","name":"issueKey","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/issues/{issueKey}/activity":{"get":{"summary":"List issue activity.","tags":["Activity"],"security":[{"bearerAuth":["issues:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"WEB-39","description":"Issue key (KEY-N)."},"required":true,"description":"Issue key (KEY-N).","name":"issueKey","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Activity"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/issues/{issueKey}/watchers":{"get":{"summary":"List watchers.","tags":["Watchers"],"security":[{"bearerAuth":["issues:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"WEB-39","description":"Issue key (KEY-N)."},"required":true,"description":"Issue key (KEY-N).","name":"issueKey","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Watcher"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Watch the issue (current key's user).","tags":["Watchers"],"security":[{"bearerAuth":["issues:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"WEB-39","description":"Issue key (KEY-N)."},"required":true,"description":"Issue key (KEY-N).","name":"issueKey","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Watcher"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/issues/{issueKey}/watchers/{userId}":{"delete":{"summary":"Unwatch the issue.","tags":["Watchers"],"security":[{"bearerAuth":["issues:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"WEB-39","description":"Issue key (KEY-N)."},"required":true,"description":"Issue key (KEY-N).","name":"issueKey","in":"path"},{"schema":{"type":"string"},"required":true,"name":"userId","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"user_id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["user_id","deleted"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/issues/{issueKey}/links":{"get":{"summary":"List links for an issue (both directions).","tags":["Issues"],"security":[{"bearerAuth":["issues:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"WEB-39","description":"Issue key (KEY-N)."},"required":true,"description":"Issue key (KEY-N).","name":"issueKey","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/IssueLink"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Create a link between this issue and another (by KEY-NUM). Cross-project within the workspace is supported.","tags":["Issues"],"security":[{"bearerAuth":["issues:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"WEB-39","description":"Issue key (KEY-N)."},"required":true,"description":"Issue key (KEY-N).","name":"issueKey","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssueLinkCreateInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/IssueLink"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/issues/{issueKey}/links/{id}":{"delete":{"summary":"Remove a link.","tags":["Issues"],"security":[{"bearerAuth":["issues:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"WEB-39","description":"Issue key (KEY-N)."},"required":true,"description":"Issue key (KEY-N).","name":"issueKey","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/issues/{issueKey}/commits":{"get":{"summary":"List git commit references associated with this issue (populated by the GitHub/GitLab integration).","tags":["Issues"],"security":[{"bearerAuth":["issues:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"WEB-39","description":"Issue key (KEY-N)."},"required":true,"description":"Issue key (KEY-N).","name":"issueKey","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommitRef"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/issues/{issueKey}/attachments":{"get":{"summary":"List attachments.","tags":["Attachments"],"security":[{"bearerAuth":["attachments:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"WEB-39","description":"Issue key (KEY-N)."},"required":true,"description":"Issue key (KEY-N).","name":"issueKey","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Attachment"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Create a pre-signed upload intent.","tags":["Attachments"],"security":[{"bearerAuth":["attachments:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"WEB-39","description":"Issue key (KEY-N)."},"required":true,"description":"Issue key (KEY-N).","name":"issueKey","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachmentIntentInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UploadIntent"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/issues/{issueKey}/attachments/commit":{"post":{"summary":"Finalize an upload after the R2 PUT.","tags":["Attachments"],"security":[{"bearerAuth":["attachments:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"WEB-39","description":"Issue key (KEY-N)."},"required":true,"description":"Issue key (KEY-N).","name":"issueKey","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachmentCommitInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Attachment"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/issues/{issueKey}/attachments/{id}":{"delete":{"summary":"Delete an attachment.","tags":["Attachments"],"security":[{"bearerAuth":["attachments:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"WEB-39","description":"Issue key (KEY-N)."},"required":true,"description":"Issue key (KEY-N).","name":"issueKey","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/issues/{issueKey}/custom-fields":{"get":{"summary":"List custom-field values on an issue.","tags":["Custom fields"],"security":[{"bearerAuth":["custom_fields:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"WEB-39","description":"Issue key (KEY-N)."},"required":true,"description":"Issue key (KEY-N).","name":"issueKey","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomFieldValue"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/issues/{issueKey}/custom-fields/{fieldId}":{"put":{"summary":"Set a custom-field value.","tags":["Custom fields"],"security":[{"bearerAuth":["custom_fields:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"WEB-39","description":"Issue key (KEY-N)."},"required":true,"description":"Issue key (KEY-N).","name":"issueKey","in":"path"},{"schema":{"type":"string"},"required":true,"name":"fieldId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomFieldValueInput"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomFieldValue"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Clear a custom-field value.","tags":["Custom fields"],"security":[{"bearerAuth":["custom_fields:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"WEB-39","description":"Issue key (KEY-N)."},"required":true,"description":"Issue key (KEY-N).","name":"issueKey","in":"path"},{"schema":{"type":"string"},"required":true,"name":"fieldId","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomFieldValue"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/issues/{issueKey}/time":{"get":{"summary":"Get time tracking.","tags":["Time"],"security":[{"bearerAuth":["issues:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"WEB-39","description":"Issue key (KEY-N)."},"required":true,"description":"Issue key (KEY-N).","name":"issueKey","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TimeTracking"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"summary":"Update time tracking.","tags":["Time"],"security":[{"bearerAuth":["issues:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"WEB-39","description":"Issue key (KEY-N)."},"required":true,"description":"Issue key (KEY-N).","name":"issueKey","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimePatchInput"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TimeTracking"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/labels":{"get":{"summary":"List labels.","tags":["Labels"],"security":[{"bearerAuth":["labels:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Label"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Create a label.","tags":["Labels"],"security":[{"bearerAuth":["labels:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LabelCreateInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Label"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/labels/{id}":{"patch":{"summary":"Update a label.","tags":["Labels"],"security":[{"bearerAuth":["labels:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LabelPatchInput"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Label"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Delete a label.","tags":["Labels"],"security":[{"bearerAuth":["labels:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/statuses":{"get":{"summary":"List a project's board statuses (ordered).","tags":["Statuses"],"security":[{"bearerAuth":["projects:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProjectStatus"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Create a board status column (max 12 per project).","tags":["Statuses"],"security":[{"bearerAuth":["projects:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusCreateInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectStatus"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/statuses/{id}":{"patch":{"summary":"Update a board status. Changing category re-categorises all issues in the column.","tags":["Statuses"],"security":[{"bearerAuth":["projects:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusPatchInput"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectStatus"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Delete a board status (soft). All issues in the column are soft-deleted. Refuses if it is the last status.","tags":["Statuses"],"security":[{"bearerAuth":["projects:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]},"issues_deleted":{"type":"integer"}},"required":["id","deleted","issues_deleted"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/custom-field-defs":{"get":{"summary":"List custom-field definitions.","tags":["Custom fields"],"security":[{"bearerAuth":["custom_fields:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomFieldDef"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Create a custom-field definition.","tags":["Custom fields"],"security":[{"bearerAuth":["custom_fields:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomFieldDefCreateInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomFieldDef"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/custom-field-defs/{id}":{"patch":{"summary":"Update a custom-field definition.","tags":["Custom fields"],"security":[{"bearerAuth":["custom_fields:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["text","number","select","multi_select","date","checkbox","url","user","project","doc"]},"options":{"type":"array","items":{"type":"string"}},"applies_to":{"type":"array","items":{"type":"string","enum":["epic","story","task","bug","subtask"]}},"required":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomFieldDef"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Delete a custom-field definition.","tags":["Custom fields"],"security":[{"bearerAuth":["custom_fields:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/saved-views":{"get":{"summary":"List saved views.","tags":["Saved views"],"security":[{"bearerAuth":["saved_views:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SavedView"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Create a saved view.","tags":["Saved views"],"security":[{"bearerAuth":["saved_views:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedViewCreateInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SavedView"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/saved-views/{id}":{"patch":{"summary":"Update a saved view.","tags":["Saved views"],"security":[{"bearerAuth":["saved_views:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"filter":{},"is_shared":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SavedView"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Delete a saved view.","tags":["Saved views"],"security":[{"bearerAuth":["saved_views:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/sprints":{"get":{"summary":"List sprints for a project.","tags":["Sprints"],"security":[{"bearerAuth":["projects:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Sprint"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Create a sprint. Attach issues by PATCHing issue sprint_id.","tags":["Sprints"],"security":[{"bearerAuth":["projects:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SprintCreateInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Sprint"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/sprints/{id}":{"get":{"summary":"Sprint detail.","tags":["Sprints"],"security":[{"bearerAuth":["projects:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Sprint"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"summary":"Update a sprint. Setting status=active demotes any other active sprint.","tags":["Sprints"],"security":[{"bearerAuth":["projects:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SprintPatchInput"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Sprint"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Delete a sprint (soft). Issues are detached.","tags":["Sprints"],"security":[{"bearerAuth":["projects:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/milestones":{"get":{"summary":"List milestones for a project.","tags":["Milestones"],"security":[{"bearerAuth":["projects:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Milestone"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Create a milestone.","tags":["Milestones"],"security":[{"bearerAuth":["projects:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MilestoneCreateInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Milestone"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/milestones/{id}":{"get":{"summary":"Milestone detail.","tags":["Milestones"],"security":[{"bearerAuth":["projects:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Milestone"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"summary":"Update a milestone.","tags":["Milestones"],"security":[{"bearerAuth":["projects:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MilestonePatchInput"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Milestone"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Delete a milestone (soft). Issues are detached.","tags":["Milestones"],"security":[{"bearerAuth":["projects:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/releases":{"get":{"summary":"List releases for a project.","tags":["Releases"],"security":[{"bearerAuth":["projects:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Release"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Create a release. Attach issues by PATCHing issue release_id.","tags":["Releases"],"security":[{"bearerAuth":["projects:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReleaseCreateInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Release"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/releases/{id}":{"get":{"summary":"Release detail.","tags":["Releases"],"security":[{"bearerAuth":["projects:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Release"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"summary":"Update a release. Setting status=released stamps released_at.","tags":["Releases"],"security":[{"bearerAuth":["projects:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReleasePatchInput"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Release"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Delete a release (soft). Issues are detached.","tags":["Releases"],"security":[{"bearerAuth":["projects:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/reports/{report}":{"get":{"summary":"Get a project report (velocity, burndown, cycle-time, throughput, status/type breakdown, workload). Paid feature.","tags":["Reports"],"security":[{"bearerAuth":["projects:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"velocity","description":"Report id: velocity | burndown | cycle-time | throughput | status-breakdown | type-breakdown | workload."},"required":true,"description":"Report id: velocity | burndown | cycle-time | throughput | status-breakdown | type-breakdown | workload.","name":"report","in":"path"},{"schema":{"type":"string","enum":["json","csv"],"description":"Response format. `csv` returns a downloadable text/csv body; default is JSON."},"required":false,"description":"Response format. `csv` returns a downloadable text/csv body; default is JSON.","name":"format","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Report"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/docs":{"get":{"summary":"List docs (workspace or project-scoped).","tags":["Docs"],"security":[{"bearerAuth":["docs:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","description":"Filter to a project key."},"required":false,"description":"Filter to a project key.","name":"project","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Doc"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Create a doc.","tags":["Docs"],"security":[{"bearerAuth":["docs:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocCreateInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Doc"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/docs/bulk":{"post":{"summary":"Bulk-create docs (1–50). Returns a per-item result array; 201 when all succeed, 207 when some fail.","tags":["Docs"],"security":[{"bearerAuth":["docs:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkDocsCreateInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BulkDocResult"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/docs/{id}":{"get":{"summary":"Doc detail.","tags":["Docs"],"security":[{"bearerAuth":["docs:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Doc"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"summary":"Update a doc.","tags":["Docs"],"security":[{"bearerAuth":["docs:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"project":{"type":"string","description":"project key to scope the doc"},"parent_id":{"type":"string"},"body_md":{"type":"string"},"body_json":{},"icon":{"type":"string"}}}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Doc"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Archive a doc (soft).","tags":["Docs"],"security":[{"bearerAuth":["docs:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/docs/{id}/export":{"get":{"summary":"Export a doc as md / html / pdf.","tags":["Docs"],"security":[{"bearerAuth":["docs:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["md","html","pdf"]},"required":false,"name":"format","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"format":{"type":"string"},"content":{"type":"string"}},"required":["format","content"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/search":{"get":{"summary":"Search issues + docs.","tags":["Search"],"security":[{"bearerAuth":["search:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"ghost placeholder"},"required":true,"name":"q","in":"query"},{"schema":{"type":"string","example":"issue,doc"},"required":false,"name":"types","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SearchResult"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/members":{"get":{"summary":"List members.","tags":["Members"],"security":[{"bearerAuth":["members:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Member"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/members/{userId}":{"patch":{"summary":"Update a member's role (admin-only scope).","tags":["Members"],"security":[{"bearerAuth":["members:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string"},"required":true,"name":"userId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemberPatchInput"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Member"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Remove a member from the workspace (admin-only scope).","tags":["Members"],"security":[{"bearerAuth":["members:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string"},"required":true,"name":"userId","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"user_id":{"type":"string"},"removed":{"type":"boolean","enum":[true]}},"required":["user_id","removed"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/invites":{"get":{"summary":"List pending invites.","tags":["Members"],"security":[{"bearerAuth":["members:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Invite"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Send a workspace invite email (admin+). Revoke-and-replace if the email already has a live invite.","tags":["Members"],"security":[{"bearerAuth":["members:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteCreateInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Invite"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/invites/{id}":{"delete":{"summary":"Revoke a pending invite.","tags":["Members"],"security":[{"bearerAuth":["members:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"revoked":{"type":"boolean","enum":[true]}},"required":["id","revoked"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/notifications":{"get":{"summary":"List notifications for the key's user.","tags":["Notifications"],"security":[{"bearerAuth":["notifications:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Notification"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/notifications/{id}":{"patch":{"summary":"Mark a notification read.","tags":["Notifications"],"security":[{"bearerAuth":["notifications:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"read":{"type":"boolean"}},"required":["read"]}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Notification"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/notifications/mark-all-read":{"post":{"summary":"Mark all unread notifications as read for the calling user in this workspace. Returns the count of rows updated.","tags":["Notifications"],"security":[{"bearerAuth":["notifications:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"count":{"type":"integer"}},"required":["count"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/agents":{"get":{"summary":"List the workspace's connected agents (named coding agents like Claude Code, Codex, Cursor). Assign issues to an agent's agent_id like any member.","tags":["Agents"],"security":[{"bearerAuth":["agents:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Agent"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/agent-sessions":{"get":{"summary":"List agent work sessions, newest activity first. Filter by state to see which agents are running, blocked (needs_input), or ready for review.","tags":["Agents"],"security":[{"bearerAuth":["agents:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"running","description":"Filter: running, needs_input, review, done, failed, cancelled."},"required":false,"description":"Filter: running, needs_input, review, done, failed, cancelled.","name":"state","in":"query"},{"schema":{"type":"string","example":"WEB-39"},"required":false,"name":"issue_key","in":"query"},{"schema":{"type":"string"},"required":false,"name":"agent_id","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgentSession"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Start an agent work session. Call this when you pick up an issue so the team can follow your progress on the ticket and the Agents hub.","tags":["Agents"],"security":[{"bearerAuth":["agents:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":300,"example":"Fix flaky auth test","description":"What the agent is working on."},"issue_key":{"type":"string","example":"WEB-39","description":"Anchor the session to an issue so the team sees it on the ticket. Strongly recommended."},"note":{"type":"string","maxLength":2000,"description":"Optional first status note."},"external_url":{"type":"string","format":"uri"},"agent_id":{"type":"string","description":"Only needed when calling with a personal (non-agent) token: the agent to act as, from GET /agents. Agent keys act as themselves."}},"required":["title"]}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentSession"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/agent-sessions/{id}":{"get":{"summary":"Get one agent session.","tags":["Agents"],"security":[{"bearerAuth":["agents:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentSession"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"summary":"Update your session: heartbeat (any PATCH bumps last_activity_at), progress note, state change (needs_input when blocked, review when the PR is ready, done/failed to finish), or the PR link.","tags":["Agents"],"security":[{"bearerAuth":["agents:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","enum":["running","needs_input","review","done","failed","cancelled"],"description":"Set needs_input when blocked on a human, review when a PR is ready, done/failed when finished. Terminal states end the session."},"title":{"type":"string","minLength":1,"maxLength":300},"note":{"type":["string","null"],"maxLength":2000,"description":"Replace the status note ('opened PR #42', 'blocked on env var')."},"external_url":{"type":["string","null"],"format":"uri","description":"The PR / output URL."},"agent_id":{"type":"string","description":"Only for personal (non-agent) tokens — see POST /agent-sessions."}}}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentSession"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/chat/channels":{"get":{"summary":"List channels visible to the key's user (public + own private/DM).","tags":["Chat"],"security":[{"bearerAuth":["chat:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ChatChannel"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Create a channel.","tags":["Chat"],"security":[{"bearerAuth":["chat:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatChannelCreateInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChatChannel"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/chat/channels/{channelId}":{"get":{"summary":"Get a channel.","tags":["Chat"],"security":[{"bearerAuth":["chat:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Chat channel id."},"required":true,"description":"Chat channel id.","name":"channelId","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChatChannel"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"summary":"Rename, set topic, or (un)archive a channel.","tags":["Chat"],"security":[{"bearerAuth":["chat:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Chat channel id."},"required":true,"description":"Chat channel id.","name":"channelId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatChannelPatchInput"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChatChannel"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/chat/channels/{channelId}/members":{"get":{"summary":"List channel members.","tags":["Chat"],"security":[{"bearerAuth":["chat:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Chat channel id."},"required":true,"description":"Chat channel id.","name":"channelId","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ChatChannelMember"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Add a member (self-join on public channels).","tags":["Chat"],"security":[{"bearerAuth":["chat:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Chat channel id."},"required":true,"description":"Chat channel id.","name":"channelId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":"string"}},"required":["user_id"]}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChatChannelMember"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/chat/channels/{channelId}/members/{userId}":{"delete":{"summary":"Remove a member (self always; others need manage rights).","tags":["Chat"],"security":[{"bearerAuth":["chat:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Chat channel id."},"required":true,"description":"Chat channel id.","name":"channelId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"userId","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"channel_id":{"type":"string"},"user_id":{"type":"string"},"removed":{"type":"boolean","enum":[true]}},"required":["channel_id","user_id","removed"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/chat/channels/{channelId}/messages":{"get":{"summary":"List messages (newest first, cursor-paginated).","tags":["Chat"],"security":[{"bearerAuth":["chat:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Chat channel id."},"required":true,"description":"Chat channel id.","name":"channelId","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ChatMessage"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Send a message (optionally as a thread reply).","tags":["Chat"],"security":[{"bearerAuth":["chat:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Chat channel id."},"required":true,"description":"Chat channel id.","name":"channelId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatMessageCreateInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChatMessage"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/chat/channels/{channelId}/messages/stream":{"post":{"summary":"Stream a message live (AGENT-COLLAB-01): omit message_id to open, then append deltas, then send done:true to finalize. Members watch it grow in real time.","tags":["Chat"],"security":[{"bearerAuth":["chat:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Chat channel id."},"required":true,"description":"Chat channel id.","name":"channelId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"message_id":{"type":"string"},"delta":{"type":"string","maxLength":16000},"done":{"type":"boolean"}}}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"message_id":{"type":"string"},"done":{"type":"boolean"}},"required":["message_id","done"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/chat/channels/{channelId}/messages/{messageId}":{"patch":{"summary":"Edit your own message.","tags":["Chat"],"security":[{"bearerAuth":["chat:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Chat channel id."},"required":true,"description":"Chat channel id.","name":"channelId","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Chat message id."},"required":true,"description":"Chat message id.","name":"messageId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body_md":{"type":"string","minLength":1,"maxLength":64000}},"required":["body_md"]}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChatMessage"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Delete a message (own; owner/admin may delete any).","tags":["Chat"],"security":[{"bearerAuth":["chat:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Chat channel id."},"required":true,"description":"Chat channel id.","name":"channelId","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Chat message id."},"required":true,"description":"Chat message id.","name":"messageId","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/chat/channels/{channelId}/messages/{messageId}/reactions":{"post":{"summary":"Add a reaction (idempotent).","tags":["Chat"],"security":[{"bearerAuth":["chat:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Chat channel id."},"required":true,"description":"Chat channel id.","name":"channelId","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Chat message id."},"required":true,"description":"Chat message id.","name":"messageId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"emoji":{"type":"string","minLength":1,"maxLength":16}},"required":["emoji"]}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChatReactions"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/chat/channels/{channelId}/messages/{messageId}/reactions/{emoji}":{"delete":{"summary":"Remove your reaction.","tags":["Chat"],"security":[{"bearerAuth":["chat:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Chat channel id."},"required":true,"description":"Chat channel id.","name":"channelId","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Chat message id."},"required":true,"description":"Chat message id.","name":"messageId","in":"path"},{"schema":{"type":"string","example":"👍"},"required":true,"name":"emoji","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChatReactions"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/forms":{"get":{"summary":"List project forms.","tags":["Forms"],"security":[{"bearerAuth":["forms:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FormSummary"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Create a form (admin-tier scope).","tags":["Forms"],"security":[{"bearerAuth":["forms:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormCreateInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Form"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/forms/{id}":{"get":{"summary":"Get a form with its ordered fields.","tags":["Forms"],"security":[{"bearerAuth":["forms:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Form id."},"required":true,"description":"Form id.","name":"id","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Form"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"summary":"Update form settings / publish / enable public sharing.","tags":["Forms"],"security":[{"bearerAuth":["forms:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Form id."},"required":true,"description":"Form id.","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormPatchInput"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Form"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Soft-delete a form (disables public sharing).","tags":["Forms"],"security":[{"bearerAuth":["forms:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Form id."},"required":true,"description":"Form id.","name":"id","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/forms/{id}/fields":{"get":{"summary":"List a form's fields in order.","tags":["Forms"],"security":[{"bearerAuth":["forms:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Form id."},"required":true,"description":"Form id.","name":"id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FormField"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/forms/{id}/submissions":{"get":{"summary":"List form submissions.","tags":["Forms"],"security":[{"bearerAuth":["forms:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Form id."},"required":true,"description":"Form id.","name":"id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FormSubmission"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/forms/{id}/submissions/{sid}":{"get":{"summary":"Get a single submission.","tags":["Forms"],"security":[{"bearerAuth":["forms:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Form id."},"required":true,"description":"Form id.","name":"id","in":"path"},{"schema":{"type":"string","description":"Submission id."},"required":true,"description":"Submission id.","name":"sid","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FormSubmission"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/automations":{"get":{"summary":"List automation rules.","tags":["Automations"],"security":[{"bearerAuth":["automations:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Automation"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Create an automation rule (admin-tier scope; Pro/Business plans).","tags":["Automations"],"security":[{"bearerAuth":["automations:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationCreateInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Automation"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/automations/{id}":{"get":{"summary":"Get an automation rule.","tags":["Automations"],"security":[{"bearerAuth":["automations:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Automation"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"summary":"Update or enable/disable an automation rule.","tags":["Automations"],"security":[{"bearerAuth":["automations:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationPatchInput"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Automation"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Delete an automation rule.","tags":["Automations"],"security":[{"bearerAuth":["automations:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/automations/{id}/runs":{"get":{"summary":"List an automation's run history (newest first).","tags":["Automations"],"security":[{"bearerAuth":["automations:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AutomationRun"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/workflows":{"get":{"summary":"List workflows.","tags":["Workflows"],"security":[{"bearerAuth":["workflows:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Workflow"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Create a workflow (draft; admin-tier scope).","tags":["Workflows"],"security":[{"bearerAuth":["workflows:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowCreateInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Workflow"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/workflows/{id}":{"get":{"summary":"Get a workflow with its nodes and edges.","tags":["Workflows"],"security":[{"bearerAuth":["workflows:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowDetail"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"summary":"Update name/description, or enable/disable (enabling enforces the plan cap and graph validity).","tags":["Workflows"],"security":[{"bearerAuth":["workflows:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowPatchInput"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Workflow"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Soft-delete a workflow. Refuses while runs are in flight unless ?cancel_runs=true.","tags":["Workflows"],"security":[{"bearerAuth":["workflows:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/workflows/{id}/graph":{"put":{"summary":"Replace a workflow's nodes and edges atomically (referential + acyclicity checked).","tags":["Workflows"],"security":[{"bearerAuth":["workflows:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowGraphInput"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowDetail"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/workflows/{id}/runs":{"get":{"summary":"List a workflow's runs (newest first).","tags":["Workflows"],"security":[{"bearerAuth":["workflows:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowRun"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/workflow-runs/{id}":{"get":{"summary":"Get a workflow run with its stage states.","tags":["Workflows"],"security":[{"bearerAuth":["workflows:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowRunDetail"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/workflow-runs/{id}/advance":{"post":{"summary":"Force-advance a run's state machine.","tags":["Workflows"],"security":[{"bearerAuth":["workflows:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowRunDetail"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/workflow-runs/{id}/complete-stage":{"post":{"summary":"Complete the current active stage(s) of a run (member-tier workflow.run).","tags":["Workflows"],"security":[{"bearerAuth":["issues:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowCompleteStageInput"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowRunDetail"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/projects/{key}/issues/{issueKey}/workflow":{"post":{"summary":"Route an issue through an enabled workflow (member-tier workflow.run).","tags":["Workflows"],"security":[{"bearerAuth":["issues:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"WEB-39","description":"Issue key (KEY-N)."},"required":true,"description":"Issue key (KEY-N).","name":"issueKey","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowStartInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"run_id":{"type":"string"}},"required":["run_id"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Cancel the issue's active workflow run (member-tier workflow.run).","tags":["Workflows"],"security":[{"bearerAuth":["issues:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"web","description":"Project key."},"required":true,"description":"Project key.","name":"key","in":"path"},{"schema":{"type":"string","example":"WEB-39","description":"Issue key (KEY-N)."},"required":true,"description":"Issue key (KEY-N).","name":"issueKey","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"issue_key":{"type":"string"},"cancelled":{"type":"boolean","enum":[true]}},"required":["issue_key","cancelled"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/views":{"get":{"summary":"List cross-project workspace views (shared + own).","tags":["Workspace views"],"security":[{"bearerAuth":["saved_views:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkspaceView"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Create a workspace view.","tags":["Workspace views"],"security":[{"bearerAuth":["saved_views:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceViewCreateInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkspaceView"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/views/{id}":{"get":{"summary":"Get a workspace view.","tags":["Workspace views"],"security":[{"bearerAuth":["saved_views:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkspaceView"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"summary":"Update a workspace view (creator or owner/admin).","tags":["Workspace views"],"security":[{"bearerAuth":["saved_views:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"filter":{"type":"object","properties":{"projectIds":{"type":"array","items":{"type":"string"}},"statuses":{"type":"array","items":{"type":"string"}},"priorities":{"type":"array","items":{"type":"string"}},"types":{"type":"array","items":{"type":"string"}},"assigneeId":{"type":["string","null"]},"sort":{"type":"string","enum":["updated_desc","created_desc","priority_desc","due_asc"]}},"required":["projectIds","statuses","priorities","types","assigneeId","sort"]},"is_shared":{"type":"boolean","description":"Defaults to true."}}}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkspaceView"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Delete a workspace view.","tags":["Workspace views"],"security":[{"bearerAuth":["saved_views:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/usage":{"get":{"summary":"Read-only plan, storage, and AI-credit usage for the workspace.","tags":["Workspaces"],"security":[{"bearerAuth":["workspaces:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkspaceUsage"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/docs/{id}/comments":{"get":{"summary":"List doc comments (oldest first).","tags":["Docs"],"security":[{"bearerAuth":["docs:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Doc id."},"required":true,"description":"Doc id.","name":"id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DocComment"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Add a doc comment (optionally threaded).","tags":["Docs"],"security":[{"bearerAuth":["docs:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Doc id."},"required":true,"description":"Doc id.","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body_md":{"type":"string","minLength":1,"maxLength":64000},"parent_id":{"type":["string","null"]}},"required":["body_md"]}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DocComment"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/docs/{id}/comments/{commentId}":{"patch":{"summary":"Edit a doc comment (author; owner/admin may edit any).","tags":["Docs"],"security":[{"bearerAuth":["docs:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Doc id."},"required":true,"description":"Doc id.","name":"id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"commentId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body_md":{"type":"string","minLength":1,"maxLength":64000}},"required":["body_md"]}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DocComment"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Delete a doc comment.","tags":["Docs"],"security":[{"bearerAuth":["docs:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Doc id."},"required":true,"description":"Doc id.","name":"id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"commentId","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/docs/{id}/versions":{"get":{"summary":"List doc version snapshots (newest first; no bodies).","tags":["Docs"],"security":[{"bearerAuth":["docs:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Doc id."},"required":true,"description":"Doc id.","name":"id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DocVersionSummary"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/docs/{id}/versions/{versionId}":{"get":{"summary":"Get a full version snapshot.","tags":["Docs"],"security":[{"bearerAuth":["docs:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Doc id."},"required":true,"description":"Doc id.","name":"id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"versionId","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DocVersion"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/docs/{id}/versions/{versionId}/restore":{"post":{"summary":"Restore the doc to this snapshot.","tags":["Docs"],"security":[{"bearerAuth":["docs:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Doc id."},"required":true,"description":"Doc id.","name":"id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"versionId","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Doc"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/portfolios":{"get":{"summary":"List portfolios.","tags":["Portfolios"],"security":[{"bearerAuth":["portfolios:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Portfolio"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Create a portfolio (owner/admin-tier scope; per-plan cap).","tags":["Portfolios"],"security":[{"bearerAuth":["portfolios:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortfolioCreateInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Portfolio"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/portfolios/{portfolioId}":{"get":{"summary":"Get a portfolio.","tags":["Portfolios"],"security":[{"bearerAuth":["portfolios:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Portfolio id."},"required":true,"description":"Portfolio id.","name":"portfolioId","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Portfolio"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"summary":"Update a portfolio.","tags":["Portfolios"],"security":[{"bearerAuth":["portfolios:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Portfolio id."},"required":true,"description":"Portfolio id.","name":"portfolioId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortfolioPatchInput"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Portfolio"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Delete a portfolio (soft). Its goals become company goals; project links are removed.","tags":["Portfolios"],"security":[{"bearerAuth":["portfolios:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Portfolio id."},"required":true,"description":"Portfolio id.","name":"portfolioId","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/portfolios/{portfolioId}/projects":{"get":{"summary":"List a portfolio's member projects.","tags":["Portfolios"],"security":[{"bearerAuth":["portfolios:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Portfolio id."},"required":true,"description":"Portfolio id.","name":"portfolioId","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PortfolioProject"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Add a project to a portfolio. Idempotent.","tags":["Portfolios"],"security":[{"bearerAuth":["portfolios:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Portfolio id."},"required":true,"description":"Portfolio id.","name":"portfolioId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortfolioProjectAddInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PortfolioProject"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/portfolios/{portfolioId}/projects/{projectId}":{"delete":{"summary":"Remove a project from a portfolio. Idempotent.","tags":["Portfolios"],"security":[{"bearerAuth":["portfolios:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Portfolio id."},"required":true,"description":"Portfolio id.","name":"portfolioId","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Project id."},"required":true,"description":"Project id.","name":"projectId","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"portfolio_id":{"type":"string"},"project_id":{"type":"string"},"removed":{"type":"boolean","enum":[true]}},"required":["portfolio_id","project_id","removed"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/goals":{"get":{"summary":"List goals (optionally filtered by portfolio or company scope).","tags":["Goals"],"security":[{"bearerAuth":["goals:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","description":"Only goals grouped under this portfolio."},"required":false,"description":"Only goals grouped under this portfolio.","name":"portfolio_id","in":"query"},{"schema":{"type":"string","enum":["company"],"description":"scope=company returns only company goals (no portfolio). Mutually exclusive with portfolio_id."},"required":false,"description":"scope=company returns only company goals (no portfolio). Mutually exclusive with portfolio_id.","name":"scope","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Goal"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Create a goal (per-plan cap; acyclic parent).","tags":["Goals"],"security":[{"bearerAuth":["goals:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoalCreateInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Goal"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/goals/{goalId}":{"get":{"summary":"Get a goal with its rolled-up progress, status, key results, and alignment.","tags":["Goals"],"security":[{"bearerAuth":["goals:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Goal id."},"required":true,"description":"Goal id.","name":"goalId","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GoalDetail"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"summary":"Update a goal.","tags":["Goals"],"security":[{"bearerAuth":["goals:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Goal id."},"required":true,"description":"Goal id.","name":"goalId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoalPatchInput"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Goal"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Delete a goal (soft). Child goals are orphaned (kept, unaligned).","tags":["Goals"],"security":[{"bearerAuth":["goals:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Goal id."},"required":true,"description":"Goal id.","name":"goalId","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/goals/{goalId}/key-results":{"get":{"summary":"List a goal's key results.","tags":["Key results"],"security":[{"bearerAuth":["goals:read"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Goal id."},"required":true,"description":"Goal id.","name":"goalId","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KeyResult"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Create a key result (manual metric or auto scope roll-up).","tags":["Key results"],"security":[{"bearerAuth":["goals:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Goal id."},"required":true,"description":"Goal id.","name":"goalId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyResultCreateInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KeyResult"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/{slug}/goals/{goalId}/key-results/{keyResultId}":{"patch":{"summary":"Update a key result.","tags":["Key results"],"security":[{"bearerAuth":["goals:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Goal id."},"required":true,"description":"Goal id.","name":"goalId","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Key result id."},"required":true,"description":"Key result id.","name":"keyResultId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyResultPatchInput"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KeyResult"}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Delete a key result (soft).","tags":["Key results"],"security":[{"bearerAuth":["goals:write"]}],"parameters":[{"schema":{"type":"string","example":"utter","description":"Workspace slug."},"required":true,"description":"Workspace slug.","name":"slug","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Goal id."},"required":true,"description":"Goal id.","name":"goalId","in":"path"},{"schema":{"type":"string","example":"019e6f12-…","description":"Key result id."},"required":true,"description":"Key result id.","name":"keyResultId","in":"path"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"]}},"required":["data"]}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing / invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or cross-workspace — never leaked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}},"webhooks":{}}