{ "openapi": "3.1.0", "info": { "title": "Plansmith API", "version": "1.0.0", "description": "Plan, spec and push from anything. Credentials act as the person who created them: they reach exactly the plans that person can reach.", "contact": { "url": "https://www.plansmith.co/docs/developers/api" } }, "servers": [ { "url": "https://api.plansmith.co" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Document collaboration", "description": "Threads, comments, suggested edits and document discussion permissions." }, { "name": "Identity", "description": "Who a credential is, and what it may do." }, { "name": "Projects", "description": "Projects, their Context and their formats." }, { "name": "Plans", "description": "Plans, Specs, dependencies, sharing, prototypes and push." }, { "name": "Context", "description": "The sources the planning agent reads." }, { "name": "Formats", "description": "The Spec and Epic document shapes." }, { "name": "Prototype template", "description": "The chrome every prototype is assembled into, per workspace or project." }, { "name": "Instructions", "description": "The standing context the agent is given every turn." }, { "name": "Skills", "description": "The playbooks the agent opens when they are relevant." }, { "name": "Connectors", "description": "Issue trackers and MCP servers." }, { "name": "Credentials", "description": "API keys and connected apps." }, { "name": "Workspace", "description": "Members and invites." }, { "name": "Usage", "description": "Who has usage left, and moving it between people." }, { "name": "Spec", "description": "This document." } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A personal API key (`psk_…`) or an OAuth access token (`plan_at_…`). Scopes: read, write." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "not_found" }, "message": { "type": "string" }, "details": {} }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "Workspace": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id" ] }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "scope": { "type": "string", "enum": [ "read", "write" ] }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "prefix", "scope", "createdAt" ] }, "Member": { "type": "object", "properties": { "userId": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "role": { "type": "string", "enum": [ "OWNER", "MEMBER", "VIEWER" ] }, "joinedAt": { "type": [ "string", "null" ], "format": "date-time" }, "isPlatformAdmin": { "type": "boolean" } }, "required": [ "userId", "role", "isPlatformAdmin" ] }, "Invite": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "OWNER", "MEMBER", "VIEWER" ] }, "status": { "type": "string", "enum": [ "PENDING", "ACCEPTED", "REVOKED" ] }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "email", "role", "status", "createdAt" ] }, "OAuthConnection": { "type": "object", "properties": { "id": { "type": "string" }, "clientId": { "type": "string" }, "clientName": { "type": "string" }, "scope": { "type": "string", "enum": [ "read", "write" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "clientId", "clientName", "scope", "createdAt" ] }, "Project": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "repositoryId": { "type": [ "string", "null" ] }, "repositoryIds": { "type": "array", "items": { "type": "string" } }, "repositories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "fullName": { "type": "string" }, "defaultBranch": { "type": "string" }, "primary": { "type": "boolean" }, "index": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "indexed", "indexing", "waiting_for_connector", "failed" ], "description": "indexed: search answers from an index. The others: no index yet, and why." }, "commit": { "type": [ "string", "null" ], "description": "The commit the index covers; null before the first index." }, "indexedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When that index was built." }, "nextStatus": { "type": [ "string", "null" ], "enum": [ "indexing", "waiting_for_connector", "failed", null ], "description": "A newer index in progress, waiting, or failed; null when none." }, "nextRequiredVersion": { "type": [ "string", "null" ], "description": "While waiting for the private-network connector: the version it needs." } }, "required": [ "status", "commit", "indexedAt", "nextStatus", "nextRequiredVersion" ] } }, "required": [ "id", "provider", "fullName", "defaultBranch", "primary" ] } } }, "required": [ "id", "name" ] }, "Dependency": { "type": "object", "properties": { "id": { "type": "string" }, "fromPlanId": { "type": [ "string", "null" ] }, "fromSpecId": { "type": [ "string", "null" ] }, "toPlanId": { "type": [ "string", "null" ] }, "toSpecId": { "type": [ "string", "null" ] } }, "required": [ "id" ] }, "PushStatus": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "linear", "jira", "radial" ] }, "total": { "type": "integer" }, "pushedCount": { "type": "integer" }, "changedCount": { "type": "integer" }, "lastPushedAt": { "type": [ "string", "null" ], "format": "date-time" }, "neverPushed": { "type": "boolean" }, "externalUrl": { "type": [ "string", "null" ] }, "externalKey": { "type": [ "string", "null" ] } }, "required": [ "provider", "total", "pushedCount", "changedCount", "neverPushed" ] }, "Plan": { "type": "object", "properties": { "id": { "type": "string" }, "shortId": { "type": [ "string", "null" ], "description": "The handle, e.g. `PLAN-12`." }, "archivedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Non-null means the plan is hidden and scheduled for deletion; writes 409." }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "PLANNING", "READY", "PUSHED", "BUILDING", "DONE" ] }, "statusLabel": { "type": "string", "description": "The word the console shows for `status`." }, "projectId": { "type": "string" }, "parentPlanId": { "type": [ "string", "null" ] }, "rootPlanId": { "type": "string" }, "visibility": { "type": [ "string", "null" ], "enum": [ "PRIVATE", "TEAM", null ] }, "ownerUserId": { "type": [ "string", "null" ] }, "capability": { "type": "string", "enum": [ "NONE", "READ", "EDIT", "OWN" ], "description": "Your access to this plan. Present on reads that resolve it." }, "specCount": { "type": "integer" } }, "required": [ "id", "name", "status", "statusLabel", "projectId", "rootPlanId" ] }, "Spec": { "type": "object", "properties": { "id": { "type": "string" }, "shortId": { "type": "string", "description": "The handle within its plan, e.g. `SPEC-3`." }, "trackerKey": { "type": [ "string", "null" ], "description": "The issue key in the tracker this spec is linked to, e.g. `SIT-123`; null when it has never been imported or pushed. Accepted anywhere `shortId` is, so a client can address a spec by the name its team already uses." }, "kind": { "type": "string", "enum": [ "spec", "epic" ], "description": "`spec` is one buildable thing; `epic` is a narrative document. The plan's `specCount` counts SPECS only, so this list may contain more entries than that number — the difference is exactly the epics. Build from the specs." }, "title": { "type": "string" }, "content": { "type": "string", "description": "Markdown, including the numbered acceptance criteria." }, "revision": { "type": "string", "description": "A hash of what `plansmith plan pull` writes for this spec: its title, body, parent, what it needs first and its issue tracker key. The same value the pull index carries, so a copy can be checked against it; a status or readiness change does not move it. On the plan’s own epic it is the epic’s revision. Send it back as `expectedRevision` on a PATCH or an image append, and the write lands only if the spec is unchanged since." }, "status": { "type": "string" }, "parentSpecId": { "type": [ "string", "null" ] }, "parentShortId": { "type": [ "string", "null" ] }, "needsFirst": { "type": "array", "items": { "type": "string" }, "description": "SHORT IDS, not uuids, so a client can render \"needs SPEC-3 first\" directly." }, "effort": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 5 }, "effortLabel": { "type": [ "string", "null" ], "description": "Low · Med · High." }, "readiness": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 5 }, "readinessLabel": { "type": [ "string", "null" ], "description": "Rough · Shaping · Ready." }, "readinessHold": { "type": [ "object", "null" ], "description": "Why this spec is held below Ready, when a gate is holding it: the checklist, the team’s format, or the second reader. Null when nothing holds it — and null when the stored record describes an earlier revision than the body in this payload.", "properties": { "source": { "type": "string", "enum": [ "checklist", "format", "second_reader" ], "description": "Which gate held it." }, "criteria": { "type": "array", "items": { "type": "string" }, "description": "Stable ids for what failed, for grouping. Not a published vocabulary." }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "One sentence per finding." } } }, "readinessReasons": { "type": "array", "items": { "type": "string" }, "description": "What to tell a person about why this spec is not Ready yet. Empty for a Ready spec. Falls back to the live checks for a spec saved before holds were recorded." }, "openQuestions": { "type": "object", "properties": { "open": { "type": "integer", "description": "Questions still waiting on an answer." }, "resolved": { "type": "integer", "description": "Entries in the Spec's Decision Log." } }, "required": [ "open", "resolved" ], "description": "Derived from the Spec body: `**OQn:**` lines are open, Decision Log lines are resolved. A Spec with an open question is held at Shaping." } }, "required": [ "id", "shortId", "title", "content", "status", "needsFirst" ] }, "SpecWithCriteria": { "allOf": [ { "$ref": "#/components/schemas/Spec" }, { "type": "object", "properties": { "acceptanceCriteria": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "text": { "type": "string" }, "checked": { "type": "boolean" }, "body": { "type": "string", "description": "The lines written under the criterion (a Given/When/Then block, sub-checks), dedented. Empty when the criterion is one line." } } } }, "doneWhen": { "type": "array", "items": { "type": "string" }, "deprecated": true, "description": "DEPRECATED text-only alias of `acceptanceCriteria`, kept for plansmith.co CLI v0.1.x. Labels are stripped, so do not string-match these back against `content`." } } } ] }, "PlanPullIndex": { "type": "object", "properties": { "format": { "type": "string", "const": "plansmith.plan-pull/1" }, "plan": { "type": "object", "properties": { "shortId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "revision": { "type": "string" } }, "required": [ "shortId", "name", "revision" ] }, "epic": { "oneOf": [ { "type": "object", "properties": { "revision": { "type": "string" }, "content": { "type": "string" } }, "required": [ "revision", "content" ] }, { "type": "null" } ] }, "specs": { "type": "array", "description": "Tree order: a parent before its children.", "items": { "type": "object", "properties": { "shortId": { "type": "string" }, "kind": { "type": "string", "enum": [ "spec", "epic" ] }, "title": { "type": "string" }, "trackerKey": { "type": [ "string", "null" ] }, "parentShortId": { "type": [ "string", "null" ] }, "needsFirst": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "effortLabel": { "type": "string" }, "readinessLabel": { "type": "string" }, "openQuestions": { "type": "object", "properties": { "open": { "type": "integer" }, "resolved": { "type": "integer" } }, "required": [ "open", "resolved" ] }, "revision": { "type": "string" }, "acceptanceCriteria": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "text": { "type": "string" }, "checked": { "type": "boolean" }, "body": { "type": "string" } }, "required": [ "id", "text", "checked", "body" ] } }, "outline": { "type": "array", "items": { "type": "object", "properties": { "level": { "type": "integer" }, "text": { "type": "string" } }, "required": [ "level", "text" ] } }, "content": { "type": "string" } }, "required": [ "shortId", "title", "revision", "acceptanceCriteria", "outline", "content" ] } } }, "required": [ "format", "plan", "epic", "specs" ] }, "ReviewUpdate": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "product" ] }, "path": { "type": "string", "description": "Plan-relative path of the review file, e.g. `context/readiness-reviews/SPEC-3.md`." }, "retired": { "type": "array", "items": { "type": "string" }, "description": "Handles this edit closed (`OQ3`, `F1`)." }, "ambiguous": { "type": "array", "items": { "type": "string" }, "description": "Findings whose criterion changed without the rewrite the finding proposed. Left open; the agent decides." }, "findings": { "type": "array", "items": { "type": "string" }, "description": "`Fn` handles still open after the update." }, "open_questions": { "type": "array", "items": { "type": "string" }, "description": "`OQn` handles still open after the update." }, "readiness": { "type": "integer", "minimum": 1, "maximum": 5 }, "verdict": { "type": "string", "enum": [ "Rough", "Shaping", "Ready" ] }, "recount": { "type": "array", "items": { "type": "string" }, "description": "Summary rows whose count needs a judgment the product did not make." }, "held": { "type": "string", "description": "Present when the table read Ready and the readiness gate refused it." } }, "required": [ "mode", "path", "retired", "ambiguous", "findings", "open_questions", "readiness", "verdict", "recount" ] }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "skipped" ] }, "path": { "type": "string" }, "reason": { "type": "string", "enum": [ "predates-updates", "unlocatable", "ambiguous", "failed" ] }, "message": { "type": "string" }, "retired": { "type": "array", "items": { "type": "string" } }, "ambiguous": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "path", "reason", "message", "retired", "ambiguous" ] } ] }, "ContextSource": { "type": "object", "properties": { "id": { "type": "string" }, "scope": { "type": "string", "enum": [ "TEAM", "PROJECT", "PLAN" ] }, "kind": { "type": "string", "description": "Free-form source kind, e.g. `prd`." }, "sourceKind": { "type": [ "string", "null" ], "enum": [ "PASTED", "UPLOADED", "URL", "RESEARCH", null ] }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "tokenCount": { "type": "integer" }, "folderPath": { "type": "string", "description": "Empty string at the scope root, never null." }, "hasFile": { "type": "boolean" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "degraded": { "type": "boolean" }, "skipped": { "type": "boolean" }, "replaced": { "type": "boolean" }, "keptBothAs": { "type": "string" }, "pictureCount": { "type": "integer", "description": "Pictures kept from a `.docx`, `.doc` or `.pptx`. Returned ONLY on the upload response, and only for those three formats; never present when reading a source back." }, "sizeBytes": { "type": [ "integer", "null" ], "description": "What this source adds to a download of its scope, in bytes: the stored file, or the text for a note, a web page or a recording (whose transcript is what a download carries). Returned by the context LIST routes only; null when the size is unknown." }, "enrichment": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "running", "done", "failed", "skipped" ], "description": "Where the body is in the LAND → ENRICH split. A recording lands with a placeholder and reaches `done` when its transcript is written; poll this to tell \"still working\" from \"finished\"." }, "reason": { "type": [ "string", "null" ], "description": "Why it failed or was skipped, in plain language (\"no usage left\", \"no speech was found in this recording\"). Null while working or on success. Never a provider message." } }, "required": [ "status" ] } }, "required": [ "id", "scope", "kind", "title", "tokenCount", "folderPath", "hasFile" ] }, "ContextSourceDetail": { "allOf": [ { "$ref": "#/components/schemas/ContextSource" }, { "type": "object", "properties": { "text": { "type": [ "string", "null" ], "description": "Truncated at 1,000,000 characters." }, "textChars": { "type": "integer", "description": "The FULL length, even when `text` is truncated." }, "url": { "type": [ "string", "null" ] } } } ] }, "Format": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "spec", "epic" ] }, "tier": { "type": "string", "enum": [ "built-in", "company", "project" ] }, "effectiveRevision": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] }, "overrideRevision": { "type": [ "string", "null" ], "description": "Revision of the override at the requested scope. Null means absent. Omitted when unreadable, in which case do not write." }, "overrideReadable": { "type": "boolean" }, "documentUrl": { "type": [ "string", "null" ], "description": "App-relative authenticated path for the effective source; the company page also displays the Plansmith standard." }, "scopeDocumentUrl": { "type": [ "string", "null" ], "description": "App-relative authenticated document path for the requested scope." }, "markdown": { "type": "string", "description": "Whole Markdown without spec_format or epic_format prompt wrapper tags, at every tier." }, "path": { "type": [ "string", "null" ] }, "problem": { "type": [ "object", "null" ], "description": "Set when a saved override exists but could not be read.", "properties": { "path": { "type": "string" }, "tier": { "type": "string" } } }, "bytes": { "type": "integer", "description": "Size of the markdown IN FORCE — which at `built-in` tier is the shipped default, not a stored override of yours." }, "maxBytes": { "type": "integer", "description": "A write is refused above this." } }, "required": [ "kind", "tier", "markdown", "bytes", "maxBytes", "effectiveRevision", "overrideReadable", "documentUrl", "scopeDocumentUrl", "updatedAt" ] }, "PrototypeTemplate": { "type": "object", "properties": { "tier": { "type": "string", "enum": [ "built-in", "company", "project" ] }, "html": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "problem": { "type": [ "object", "null" ], "description": "Set when a stored copy exists and was SKIPPED: it failed validation or could not be read. `findings` name the rules it broke.", "properties": { "tier": { "type": "string", "enum": [ "company", "project" ] }, "path": { "type": "string" }, "state": { "type": "string", "enum": [ "invalid", "unreadable" ] }, "findings": { "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "string" }, "detail": { "type": "string" }, "line": { "type": "integer" } }, "required": [ "rule", "detail" ] } } } }, "bytes": { "type": "integer", "description": "Size of the template IN FORCE." }, "maxBytes": { "type": "integer", "description": "A write is refused above this." } }, "required": [ "tier", "html", "bytes", "maxBytes" ] }, "Instructions": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "company", "project", "user", "plan" ] }, "markdown": { "type": "string", "description": "Empty when none have been written. Absent and empty are the same state." }, "path": { "type": "string" }, "bytes": { "type": "integer" }, "maxBytes": { "type": "integer", "description": "A write is refused above this." }, "characters": { "type": "integer" }, "maxInjectedCharacters": { "type": "integer", "description": "Above this the agent is given the first part and told it was clipped. Smaller than the write cap on purpose." }, "proposalPending": { "type": "boolean", "description": "The agent has proposed a change an owner has not answered yet. Reported, never consumed: approving stays a click in Settings. Company tier only — always false at the project, plan and user scopes, which have no proposal flow." } }, "required": [ "scope", "markdown", "path", "bytes", "maxBytes", "characters", "maxInjectedCharacters", "proposalPending" ] }, "InstructionsRestored": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "company", "project", "user", "plan" ] }, "markdown": { "type": "string" }, "path": { "type": "string" }, "bytes": { "type": "integer" }, "maxBytes": { "type": "integer" }, "characters": { "type": "integer" }, "maxInjectedCharacters": { "type": "integer" }, "proposalPending": { "type": "boolean" }, "restoredFrom": { "type": "integer", "description": "The version number that was put back — the ordinal a person sees, not the seq. The restore is itself recorded as a NEW version, so nothing leaves the record." } }, "required": [ "scope", "markdown", "path", "bytes", "maxBytes", "characters", "maxInjectedCharacters", "proposalPending", "restoredFrom" ] }, "Skill": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "scope": { "type": "string", "enum": [ "built-in", "company", "project" ] }, "path": { "type": "string" }, "editable": { "type": "boolean" }, "body": { "type": "string", "description": "Present on a single-skill read, absent from the list." }, "bytes": { "type": "integer", "description": "Size of the stored file. Authored skills only." }, "extends": { "type": "string", "nullable": true, "description": "The built-in skill this one extends, or null when it stands alone. On a PUT: omit to keep what is stored, send null to clear it. Only readiness-review, prototype-builder, spec-writer, epic-writer, acceptance-review can be extended." }, "maxBytes": { "type": "integer", "description": "A write is refused above this. Reported on every skill, built-ins included, because the cap governs the override you would author at that slug." } }, "required": [ "slug", "name", "description", "scope", "path", "editable", "extends" ] }, "Connector": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "tracker", "mcp" ] }, "provider": { "type": [ "string", "null" ], "enum": [ "linear", "jira", "radial", null ] }, "label": { "type": "string" }, "vendor": { "type": "string" }, "description": { "type": "string" }, "connectScope": { "type": "string", "enum": [ "personal", "workspace" ] }, "auth": { "type": "object", "properties": { "oauth": { "type": "boolean" }, "oauthOnly": { "type": "boolean" }, "acceptsApiKey": { "type": "boolean" } } }, "tools": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "curated": { "type": "integer" } } }, "connection": { "description": "Discriminated by `scope`: personal grants versus a workspace key.", "type": "object" }, "links": { "type": "object", "properties": { "connect": { "type": "string" }, "toolsets": { "type": "string" } } } }, "required": [ "id", "kind", "label", "connectScope", "auth", "tools", "connection", "links" ] }, "PolicyState": { "type": "object", "properties": { "workspace": { "type": "boolean" }, "project": { "type": [ "boolean", "null" ], "description": "null means it follows the workspace." }, "effective": { "type": "boolean" } }, "required": [ "workspace", "effective" ] }, "McpServer": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "connectorId": { "type": "string", "description": "The `x_`-prefixed connector id." }, "label": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string" }, "authMode": { "type": "string", "enum": [ "anonymous", "bearer" ] }, "enabled": { "type": "boolean" }, "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "enabled": { "type": "boolean" }, "access": { "type": "string", "enum": [ "read", "write" ] } } } }, "toolCap": { "type": "integer" }, "lastProbe": { "type": "object", "properties": { "status": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "at": { "type": [ "string", "null" ], "format": "date-time" } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "slug", "connectorId", "label", "url", "authMode", "enabled", "tools" ] } } }, "paths": { "/v1/documents/{documentId}/mention-candidates": { "get": { "operationId": "getV1DocumentsByDocumentIdMentionCandidates", "summary": "Find teammates who can read this discussion", "tags": [ "Document collaboration" ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The documentId." }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Name or email fragment." }, { "name": "discussionPlanId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The plan using this document." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "candidates": { "type": "array", "items": { "type": "object", "properties": { "membershipId": { "type": "string" }, "userId": { "type": "string" }, "label": { "type": "string" }, "email": { "type": "string" } }, "required": [ "membershipId", "userId", "label", "email" ] } } }, "required": [ "candidates" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/notifications": { "get": { "operationId": "getV1Notifications", "summary": "Read your Inbox with current document access checks", "tags": [ "Document collaboration" ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor returned by the preceding page." }, { "name": "unread", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Return only unread items." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "string" }, "type": { "type": "string" }, "eventType": { "type": [ "string", "null" ] }, "threadId": { "type": [ "string", "null" ] }, "actorName": { "type": "string" }, "activity": { "type": "string" }, "documentTitle": { "type": "string" }, "excerpt": { "type": [ "string", "null" ] }, "url": { "type": "string" }, "mentioned": { "type": "boolean" }, "read": { "type": "boolean" }, "createdAt": { "type": "string" } }, "required": [ "id", "sequence", "type", "eventType", "threadId", "actorName", "activity", "documentTitle", "excerpt", "url", "mentioned", "read", "createdAt" ] } }, "unread": { "type": "integer" }, "watermark": { "type": "string" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "items", "unread", "watermark", "nextCursor" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/notifications/{notificationId}": { "get": { "operationId": "getV1NotificationsByNotificationId", "summary": "Read one of your notifications with current access checks", "tags": [ "Document collaboration" ], "parameters": [ { "name": "notificationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The notificationId." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "string" }, "type": { "type": "string" }, "eventType": { "type": [ "string", "null" ] }, "threadId": { "type": [ "string", "null" ] }, "actorName": { "type": "string" }, "activity": { "type": "string" }, "documentTitle": { "type": "string" }, "excerpt": { "type": [ "string", "null" ] }, "url": { "type": "string" }, "mentioned": { "type": "boolean" }, "read": { "type": "boolean" }, "createdAt": { "type": "string" } }, "required": [ "id", "sequence", "type", "eventType", "threadId", "actorName", "activity", "documentTitle", "excerpt", "url", "mentioned", "read", "createdAt" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updateV1NotificationsByNotificationId", "summary": "Mark your notification read or unread", "tags": [ "Document collaboration" ], "parameters": [ { "name": "notificationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The notificationId." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "read": { "type": "boolean" } }, "required": [ "read" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "changed": { "type": "integer" } }, "required": [ "changed" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/notifications/read-all": { "post": { "operationId": "createV1NotificationsReadAll", "summary": "Mark notifications read through a viewed watermark", "tags": [ "Document collaboration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "watermark": { "type": "string" } }, "required": [ "watermark" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "changed": { "type": "integer" } }, "required": [ "changed" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/notifications/preferences": { "get": { "operationId": "getV1NotificationsPreferences", "summary": "Read your email notification preferences", "tags": [ "Document collaboration" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "emailMentions": { "type": "boolean" }, "emailUpdates": { "type": "boolean" }, "emailNewDiscussions": { "type": "boolean" }, "emailReplies": { "type": "boolean" }, "emailReviewDecisions": { "type": "boolean" } }, "required": [ "emailMentions", "emailUpdates", "emailNewDiscussions", "emailReplies", "emailReviewDecisions" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updateV1NotificationsPreferences", "summary": "Change your email preferences without disabling Inbox mentions", "tags": [ "Document collaboration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "emailMentions": { "type": "boolean" }, "emailUpdates": { "type": "boolean" }, "emailNewDiscussions": { "type": "boolean" }, "emailReplies": { "type": "boolean" }, "emailReviewDecisions": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "emailMentions": { "type": "boolean" }, "emailUpdates": { "type": "boolean" }, "emailNewDiscussions": { "type": "boolean" }, "emailReplies": { "type": "boolean" }, "emailReviewDecisions": { "type": "boolean" } }, "required": [ "emailMentions", "emailUpdates", "emailNewDiscussions", "emailReplies", "emailReviewDecisions" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/documents/{documentId}/suggestions": { "get": { "operationId": "getV1DocumentsByDocumentIdSuggestions", "summary": "List document suggestions in a discussion plan", "tags": [ "Document collaboration" ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The documentId." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor returned by the preceding page." }, { "name": "discussionPlanId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Plan using this document." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "suggestions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "threadId": { "type": "string" }, "documentId": { "type": "string" }, "state": { "type": "string", "enum": [ "PENDING", "ACCEPTED", "REJECTED", "WITHDRAWN", "APPLIED_EXTERNALLY" ] }, "version": { "type": "integer" }, "proposal": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "native" }, "operation": { "type": "string", "enum": [ "insert", "replace", "delete" ] }, "baseRevision": { "type": "string", "minLength": 1, "maxLength": 256 }, "sourceRevision": { "default": null, "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256 }, { "type": "null" } ] }, "destinationRevision": { "type": "string", "minLength": 1, "maxLength": 256 }, "start": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "original": { "type": "string", "maxLength": 1000000 }, "proposed": { "type": "string", "maxLength": 1000000 } }, "required": [ "mode", "operation", "baseRevision", "sourceRevision", "destinationRevision", "start", "end", "original", "proposed" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "external" }, "baseRevision": { "type": "string", "minLength": 1, "maxLength": 256 }, "sourceRevision": { "default": null, "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256 }, { "type": "null" } ] }, "destinationRevision": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": { "type": "string", "minLength": 1, "maxLength": 20000 } }, "required": [ "mode", "baseRevision", "sourceRevision", "destinationRevision", "description" ], "additionalProperties": false } ] }, "authorUserId": { "type": [ "string", "null" ] }, "predecessorId": { "type": [ "string", "null" ] }, "decidedAt": { "type": [ "string", "null" ] }, "decidedBy": { "type": [ "string", "null" ] }, "acceptedRevision": { "type": [ "string", "null" ] }, "freshness": { "type": "string", "enum": [ "current", "document-changed", "passage-changed", "source-unavailable" ] }, "capabilities": { "type": "object", "properties": { "canRevise": { "type": "boolean" }, "canRefresh": { "type": "boolean" }, "canAccept": { "type": "boolean" }, "canReject": { "type": "boolean" }, "canWithdraw": { "type": "boolean" }, "canMarkAppliedExternally": { "type": "boolean" } }, "required": [ "canRevise", "canRefresh", "canAccept", "canReject", "canWithdraw", "canMarkAppliedExternally" ] } }, "required": [ "id", "threadId", "documentId", "state", "version", "proposal", "authorUserId", "predecessorId", "decidedAt", "decidedBy", "acceptedRevision", "freshness", "capabilities" ] } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "suggestions", "nextCursor" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createV1DocumentsByDocumentIdSuggestions", "summary": "Propose an exact native edit or an external change", "tags": [ "Document collaboration" ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The documentId." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "discussionPlanId": { "default": null, "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "proposal": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "native" }, "operation": { "type": "string", "enum": [ "insert", "replace", "delete" ] }, "baseRevision": { "type": "string", "minLength": 1, "maxLength": 256 }, "sourceRevision": { "default": null, "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256 }, { "type": "null" } ] }, "destinationRevision": { "type": "string", "minLength": 1, "maxLength": 256 }, "start": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "original": { "type": "string", "maxLength": 1000000 }, "proposed": { "type": "string", "maxLength": 1000000 } }, "required": [ "mode", "operation", "baseRevision", "sourceRevision", "destinationRevision", "start", "end", "original", "proposed" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "external" }, "baseRevision": { "type": "string", "minLength": 1, "maxLength": 256 }, "sourceRevision": { "default": null, "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256 }, { "type": "null" } ] }, "destinationRevision": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": { "type": "string", "minLength": 1, "maxLength": 20000 } }, "required": [ "mode", "baseRevision", "sourceRevision", "destinationRevision", "description" ], "additionalProperties": false } ] }, "rationale": { "type": "object", "properties": { "markdown": { "type": "string", "maxLength": 40000 }, "mentions": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "membershipId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "start": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "label": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "membershipId", "start", "end", "label" ], "additionalProperties": false } } }, "required": [ "markdown", "mentions" ], "additionalProperties": false }, "anchor": { "default": { "kind": "document" }, "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "document" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "text" }, "revision": { "type": "string", "minLength": 1, "maxLength": 256 }, "exact": { "type": "string", "minLength": 1, "maxLength": 100000 }, "prefix": { "type": "string", "maxLength": 512 }, "suffix": { "type": "string", "maxLength": 512 }, "start": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "blockPath": { "maxItems": 32, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "required": [ "kind", "revision", "exact", "prefix", "suffix", "start", "end" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "quote" }, "revision": { "type": "string", "minLength": 1, "maxLength": 256 }, "exact": { "type": "string", "minLength": 1, "maxLength": 100000 } }, "required": [ "kind", "revision", "exact" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "visual" }, "anchor": { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "kind": { "type": "string", "enum": [ "point", "region" ] }, "contentHash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }, "screen": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 64 }, "confidence": { "type": "string", "enum": [ "hash", "section", "default" ] } }, "required": [ "id", "confidence" ], "additionalProperties": false }, "selectors": { "minItems": 1, "maxItems": 4, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "PinId" }, "value": { "type": "string", "maxLength": 200 } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "CssSelector" }, "value": { "type": "string", "maxLength": 200 } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "TextQuote" }, "exact": { "type": "string", "maxLength": 200 }, "prefix": { "type": "string", "maxLength": 200 }, "suffix": { "type": "string", "maxLength": 200 } }, "required": [ "type", "exact" ], "additionalProperties": false } ] } }, "offset": { "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 }, "w": { "type": "number", "minimum": 0, "maximum": 1 }, "h": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "x", "y", "w", "h" ], "additionalProperties": false }, "element": { "type": "object", "properties": { "tag": { "type": "string", "maxLength": 32 }, "role": { "type": "string", "maxLength": 32 }, "text": { "type": "string", "maxLength": 120 } }, "required": [ "tag", "text" ], "additionalProperties": false }, "context": { "type": "object", "properties": { "viewport": { "type": "object", "properties": { "w": { "type": "number" }, "h": { "type": "number" } }, "required": [ "w", "h" ], "additionalProperties": false }, "dpr": { "type": "number" } }, "required": [ "viewport", "dpr" ], "additionalProperties": false } }, "required": [ "v", "kind", "contentHash", "screen", "selectors", "offset", "element", "context" ], "additionalProperties": false } }, "required": [ "kind", "anchor" ], "additionalProperties": false } ] }, "predecessorId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "requestId", "discussionPlanId", "proposal", "rationale", "anchor" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "eventId": { "type": "string" }, "suggestionId": { "type": "string" }, "threadId": { "type": "string" }, "version": { "type": "integer" }, "state": { "type": "string" }, "acceptedRevision": { "type": [ "string", "null" ] }, "commitId": { "type": [ "string", "null" ] } }, "required": [ "eventId", "suggestionId", "threadId", "version", "state" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/documents/{documentId}/suggestions/{suggestionId}": { "get": { "operationId": "getV1DocumentsByDocumentIdSuggestionsBySuggestionId", "summary": "Read a suggestion, current source and review capabilities", "tags": [ "Document collaboration" ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The documentId." }, { "name": "suggestionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The suggestionId." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "document": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "target": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "plan-item" }, "itemId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "kind", "itemId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "file" }, "path": { "type": "string", "minLength": 1, "maxLength": 4096 }, "fileId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "planId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "kind", "path" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "context" }, "sourceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "original": { "default": false, "type": "boolean" } }, "required": [ "kind", "sourceId", "original" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "format" }, "format": { "type": "string", "enum": [ "spec", "epic" ] }, "builtin": { "type": "boolean" }, "scope": { "oneOf": [ { "type": "object", "properties": { "scope": { "type": "string", "const": "company" } }, "required": [ "scope" ], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "project" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "scope", "projectId" ], "additionalProperties": false } ] }, "destination": { "default": "effective", "type": "string", "enum": [ "effective", "override" ] } }, "required": [ "kind", "format", "scope", "destination" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "instructions" }, "scope": { "type": "string", "enum": [ "company", "project", "plan", "user" ] }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "planId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "kind", "scope" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "skill" }, "scope": { "oneOf": [ { "type": "object", "properties": { "scope": { "type": "string", "const": "company" } }, "required": [ "scope" ], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "project" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "scope", "projectId" ], "additionalProperties": false } ] }, "slug": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9-]*$" } }, "required": [ "kind", "scope", "slug" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "prototype-template" }, "builtin": { "type": "boolean" }, "scope": { "oneOf": [ { "type": "object", "properties": { "scope": { "type": "string", "const": "company" } }, "required": [ "scope" ], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "project" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "scope", "projectId" ], "additionalProperties": false } ] }, "destination": { "default": "effective", "type": "string", "enum": [ "effective", "override" ] } }, "required": [ "kind", "scope", "destination" ], "additionalProperties": false } ] }, "title": { "type": "string" }, "canonicalUrl": { "type": "string" }, "revision": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "sourceDocumentId": { "type": [ "string", "null" ] }, "sourceRevision": { "type": [ "string", "null" ] }, "applyMode": { "type": "string", "enum": [ "native", "external" ] }, "capabilities": { "type": "object", "properties": { "canComment": { "type": "boolean" }, "canSuggest": { "type": "boolean" }, "canMaintain": { "type": "boolean" }, "canUseAgent": { "type": "boolean" }, "needsDiscussionPlan": { "type": "boolean" } }, "required": [ "canComment", "canSuggest", "canMaintain", "canUseAgent", "needsDiscussionPlan" ] }, "discussionPlanId": { "type": [ "string", "null" ] }, "ownerUserIds": { "type": "array", "items": { "type": "string" } }, "ownerNames": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "kind", "target", "title", "canonicalUrl", "revision", "path", "sourceDocumentId", "sourceRevision", "applyMode", "capabilities", "discussionPlanId", "ownerUserIds", "ownerNames" ] }, "suggestion": { "type": "object", "properties": { "id": { "type": "string" }, "threadId": { "type": "string" }, "documentId": { "type": "string" }, "state": { "type": "string", "enum": [ "PENDING", "ACCEPTED", "REJECTED", "WITHDRAWN", "APPLIED_EXTERNALLY" ] }, "version": { "type": "integer" }, "proposal": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "native" }, "operation": { "type": "string", "enum": [ "insert", "replace", "delete" ] }, "baseRevision": { "type": "string", "minLength": 1, "maxLength": 256 }, "sourceRevision": { "default": null, "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256 }, { "type": "null" } ] }, "destinationRevision": { "type": "string", "minLength": 1, "maxLength": 256 }, "start": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "original": { "type": "string", "maxLength": 1000000 }, "proposed": { "type": "string", "maxLength": 1000000 } }, "required": [ "mode", "operation", "baseRevision", "sourceRevision", "destinationRevision", "start", "end", "original", "proposed" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "external" }, "baseRevision": { "type": "string", "minLength": 1, "maxLength": 256 }, "sourceRevision": { "default": null, "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256 }, { "type": "null" } ] }, "destinationRevision": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": { "type": "string", "minLength": 1, "maxLength": 20000 } }, "required": [ "mode", "baseRevision", "sourceRevision", "destinationRevision", "description" ], "additionalProperties": false } ] }, "authorUserId": { "type": [ "string", "null" ] }, "predecessorId": { "type": [ "string", "null" ] }, "decidedAt": { "type": [ "string", "null" ] }, "decidedBy": { "type": [ "string", "null" ] }, "acceptedRevision": { "type": [ "string", "null" ] }, "freshness": { "type": "string", "enum": [ "current", "document-changed", "passage-changed", "source-unavailable" ] }, "capabilities": { "type": "object", "properties": { "canRevise": { "type": "boolean" }, "canRefresh": { "type": "boolean" }, "canAccept": { "type": "boolean" }, "canReject": { "type": "boolean" }, "canWithdraw": { "type": "boolean" }, "canMarkAppliedExternally": { "type": "boolean" } }, "required": [ "canRevise", "canRefresh", "canAccept", "canReject", "canWithdraw", "canMarkAppliedExternally" ] } }, "required": [ "id", "threadId", "documentId", "state", "version", "proposal", "authorUserId", "predecessorId", "decidedAt", "decidedBy", "acceptedRevision", "freshness", "capabilities" ] }, "sourceText": { "type": [ "string", "null" ] } }, "required": [ "document", "suggestion", "sourceText" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updateV1DocumentsByDocumentIdSuggestionsBySuggestionId", "summary": "Revise or explicitly refresh a pending suggestion", "tags": [ "Document collaboration" ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The documentId." }, { "name": "suggestionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The suggestionId." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "expectedVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "action": { "type": "string", "enum": [ "revise", "confirm-refresh" ] }, "proposal": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "native" }, "operation": { "type": "string", "enum": [ "insert", "replace", "delete" ] }, "baseRevision": { "type": "string", "minLength": 1, "maxLength": 256 }, "sourceRevision": { "default": null, "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256 }, { "type": "null" } ] }, "destinationRevision": { "type": "string", "minLength": 1, "maxLength": 256 }, "start": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "original": { "type": "string", "maxLength": 1000000 }, "proposed": { "type": "string", "maxLength": 1000000 } }, "required": [ "mode", "operation", "baseRevision", "sourceRevision", "destinationRevision", "start", "end", "original", "proposed" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "external" }, "baseRevision": { "type": "string", "minLength": 1, "maxLength": 256 }, "sourceRevision": { "default": null, "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256 }, { "type": "null" } ] }, "destinationRevision": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": { "type": "string", "minLength": 1, "maxLength": 20000 } }, "required": [ "mode", "baseRevision", "sourceRevision", "destinationRevision", "description" ], "additionalProperties": false } ] } }, "required": [ "requestId", "expectedVersion", "action", "proposal" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "eventId": { "type": "string" }, "suggestionId": { "type": "string" }, "threadId": { "type": "string" }, "version": { "type": "integer" }, "state": { "type": "string" }, "acceptedRevision": { "type": [ "string", "null" ] }, "commitId": { "type": [ "string", "null" ] } }, "required": [ "eventId", "suggestionId", "threadId", "version", "state" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createV1DocumentsByDocumentIdSuggestionsBySuggestionId", "summary": "Accept, reject, withdraw or record external application", "tags": [ "Document collaboration" ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The documentId." }, { "name": "suggestionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The suggestionId." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "expectedVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "action": { "type": "string", "enum": [ "accept", "reject", "withdraw", "mark-applied-externally" ] }, "note": { "type": "object", "properties": { "markdown": { "type": "string", "maxLength": 40000 }, "mentions": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "membershipId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "start": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "label": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "membershipId", "start", "end", "label" ], "additionalProperties": false } } }, "required": [ "markdown", "mentions" ], "additionalProperties": false } }, "required": [ "requestId", "expectedVersion", "action" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "eventId": { "type": "string" }, "suggestionId": { "type": "string" }, "threadId": { "type": "string" }, "version": { "type": "integer" }, "state": { "type": "string" }, "acceptedRevision": { "type": [ "string", "null" ] }, "commitId": { "type": [ "string", "null" ] } }, "required": [ "eventId", "suggestionId", "threadId", "version", "state" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/documents/{documentId}/suggestions/{suggestionId}/history": { "get": { "operationId": "getV1DocumentsByDocumentIdSuggestionsBySuggestionIdHistory", "summary": "Read immutable suggestion revisions and decisions", "tags": [ "Document collaboration" ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The documentId." }, { "name": "suggestionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The suggestionId." }, { "name": "beforeVersion", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Read earlier proposal revisions." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "revisions": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "integer" }, "proposal": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "native" }, "operation": { "type": "string", "enum": [ "insert", "replace", "delete" ] }, "baseRevision": { "type": "string", "minLength": 1, "maxLength": 256 }, "sourceRevision": { "default": null, "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256 }, { "type": "null" } ] }, "destinationRevision": { "type": "string", "minLength": 1, "maxLength": 256 }, "start": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "original": { "type": "string", "maxLength": 1000000 }, "proposed": { "type": "string", "maxLength": 1000000 } }, "required": [ "mode", "operation", "baseRevision", "sourceRevision", "destinationRevision", "start", "end", "original", "proposed" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "external" }, "baseRevision": { "type": "string", "minLength": 1, "maxLength": 256 }, "sourceRevision": { "default": null, "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256 }, { "type": "null" } ] }, "destinationRevision": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": { "type": "string", "minLength": 1, "maxLength": 20000 } }, "required": [ "mode", "baseRevision", "sourceRevision", "destinationRevision", "description" ], "additionalProperties": false } ] }, "state": { "type": "string" }, "actor_user_id": { "type": [ "string", "null" ] }, "action": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "version", "proposal", "state", "actor_user_id", "action", "created_at" ] } }, "nextVersion": { "type": [ "integer", "null" ] } }, "required": [ "revisions", "nextVersion" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/documents": { "get": { "operationId": "getV1Documents", "summary": "Resolve a canonical document from its typed target", "tags": [ "Document collaboration" ], "parameters": [ { "name": "target", "in": "query", "required": false, "schema": { "type": "string", "description": "JSON encoded DocumentTarget descriptor." }, "description": "Exact document locator. Identity and permissions are resolved on the server." }, { "name": "discussionPlanId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Plan using this shared context source." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "document": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "target": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "plan-item" }, "itemId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "kind", "itemId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "file" }, "path": { "type": "string", "minLength": 1, "maxLength": 4096 }, "fileId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "planId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "kind", "path" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "context" }, "sourceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "original": { "default": false, "type": "boolean" } }, "required": [ "kind", "sourceId", "original" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "format" }, "format": { "type": "string", "enum": [ "spec", "epic" ] }, "builtin": { "type": "boolean" }, "scope": { "oneOf": [ { "type": "object", "properties": { "scope": { "type": "string", "const": "company" } }, "required": [ "scope" ], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "project" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "scope", "projectId" ], "additionalProperties": false } ] }, "destination": { "default": "effective", "type": "string", "enum": [ "effective", "override" ] } }, "required": [ "kind", "format", "scope", "destination" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "instructions" }, "scope": { "type": "string", "enum": [ "company", "project", "plan", "user" ] }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "planId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "kind", "scope" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "skill" }, "scope": { "oneOf": [ { "type": "object", "properties": { "scope": { "type": "string", "const": "company" } }, "required": [ "scope" ], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "project" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "scope", "projectId" ], "additionalProperties": false } ] }, "slug": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9-]*$" } }, "required": [ "kind", "scope", "slug" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "prototype-template" }, "builtin": { "type": "boolean" }, "scope": { "oneOf": [ { "type": "object", "properties": { "scope": { "type": "string", "const": "company" } }, "required": [ "scope" ], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "project" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "scope", "projectId" ], "additionalProperties": false } ] }, "destination": { "default": "effective", "type": "string", "enum": [ "effective", "override" ] } }, "required": [ "kind", "scope", "destination" ], "additionalProperties": false } ] }, "title": { "type": "string" }, "canonicalUrl": { "type": "string" }, "revision": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "sourceDocumentId": { "type": [ "string", "null" ] }, "sourceRevision": { "type": [ "string", "null" ] }, "applyMode": { "type": "string", "enum": [ "native", "external" ] }, "capabilities": { "type": "object", "properties": { "canComment": { "type": "boolean" }, "canSuggest": { "type": "boolean" }, "canMaintain": { "type": "boolean" }, "canUseAgent": { "type": "boolean" }, "needsDiscussionPlan": { "type": "boolean" } }, "required": [ "canComment", "canSuggest", "canMaintain", "canUseAgent", "needsDiscussionPlan" ] }, "discussionPlanId": { "type": [ "string", "null" ] }, "ownerUserIds": { "type": "array", "items": { "type": "string" } }, "ownerNames": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "kind", "target", "title", "canonicalUrl", "revision", "path", "sourceDocumentId", "sourceRevision", "applyMode", "capabilities", "discussionPlanId", "ownerUserIds", "ownerNames" ] }, "sourceText": { "type": [ "string", "null" ] }, "viewer": { "type": "object", "properties": { "userId": { "type": "string" }, "organizationId": { "type": "string" } }, "required": [ "userId", "organizationId" ] } }, "required": [ "document", "sourceText", "viewer" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/documents/{documentId}/threads": { "get": { "operationId": "getV1DocumentsByDocumentIdThreads", "summary": "List document discussion threads", "tags": [ "Document collaboration" ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The documentId." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor returned by the preceding page." }, { "name": "knownRevisions", "in": "query", "required": false, "schema": { "type": "string" }, "description": "JSON object of up to 500 thread IDs and revision hashes from a prior page. Unchanged threads are omitted from threads; order still lists the complete current page." }, { "name": "discussionPlanId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Required discussion partition for plan/context conversations." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "document": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "target": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "plan-item" }, "itemId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "kind", "itemId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "file" }, "path": { "type": "string", "minLength": 1, "maxLength": 4096 }, "fileId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "planId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "kind", "path" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "context" }, "sourceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "original": { "default": false, "type": "boolean" } }, "required": [ "kind", "sourceId", "original" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "format" }, "format": { "type": "string", "enum": [ "spec", "epic" ] }, "builtin": { "type": "boolean" }, "scope": { "oneOf": [ { "type": "object", "properties": { "scope": { "type": "string", "const": "company" } }, "required": [ "scope" ], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "project" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "scope", "projectId" ], "additionalProperties": false } ] }, "destination": { "default": "effective", "type": "string", "enum": [ "effective", "override" ] } }, "required": [ "kind", "format", "scope", "destination" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "instructions" }, "scope": { "type": "string", "enum": [ "company", "project", "plan", "user" ] }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "planId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "kind", "scope" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "skill" }, "scope": { "oneOf": [ { "type": "object", "properties": { "scope": { "type": "string", "const": "company" } }, "required": [ "scope" ], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "project" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "scope", "projectId" ], "additionalProperties": false } ] }, "slug": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9-]*$" } }, "required": [ "kind", "scope", "slug" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "prototype-template" }, "builtin": { "type": "boolean" }, "scope": { "oneOf": [ { "type": "object", "properties": { "scope": { "type": "string", "const": "company" } }, "required": [ "scope" ], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "project" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "scope", "projectId" ], "additionalProperties": false } ] }, "destination": { "default": "effective", "type": "string", "enum": [ "effective", "override" ] } }, "required": [ "kind", "scope", "destination" ], "additionalProperties": false } ] }, "title": { "type": "string" }, "canonicalUrl": { "type": "string" }, "revision": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "sourceDocumentId": { "type": [ "string", "null" ] }, "sourceRevision": { "type": [ "string", "null" ] }, "applyMode": { "type": "string", "enum": [ "native", "external" ] }, "capabilities": { "type": "object", "properties": { "canComment": { "type": "boolean" }, "canSuggest": { "type": "boolean" }, "canMaintain": { "type": "boolean" }, "canUseAgent": { "type": "boolean" }, "needsDiscussionPlan": { "type": "boolean" } }, "required": [ "canComment", "canSuggest", "canMaintain", "canUseAgent", "needsDiscussionPlan" ] }, "discussionPlanId": { "type": [ "string", "null" ] }, "ownerUserIds": { "type": "array", "items": { "type": "string" } }, "ownerNames": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "kind", "target", "title", "canonicalUrl", "revision", "path", "sourceDocumentId", "sourceRevision", "applyMode", "capabilities", "discussionPlanId", "ownerUserIds", "ownerNames" ] }, "threads": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "documentId": { "type": "string" }, "discussionPlanId": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "state": { "type": "string", "enum": [ "OPEN", "ADDRESSED", "RESOLVED" ] }, "version": { "type": "integer" }, "anchor": { "$schema": "https://json-schema.org/draft/2020-12/schema", "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "document" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "text" }, "revision": { "type": "string", "minLength": 1, "maxLength": 256 }, "exact": { "type": "string", "minLength": 1, "maxLength": 100000 }, "prefix": { "type": "string", "maxLength": 512 }, "suffix": { "type": "string", "maxLength": 512 }, "start": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "blockPath": { "maxItems": 32, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "required": [ "kind", "revision", "exact", "prefix", "suffix", "start", "end" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "quote" }, "revision": { "type": "string", "minLength": 1, "maxLength": 256 }, "exact": { "type": "string", "minLength": 1, "maxLength": 100000 } }, "required": [ "kind", "revision", "exact" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "visual" }, "anchor": { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "kind": { "type": "string", "enum": [ "point", "region" ] }, "contentHash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }, "screen": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 64 }, "confidence": { "type": "string", "enum": [ "hash", "section", "default" ] } }, "required": [ "id", "confidence" ], "additionalProperties": false }, "selectors": { "minItems": 1, "maxItems": 4, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "PinId" }, "value": { "type": "string", "maxLength": 200 } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "CssSelector" }, "value": { "type": "string", "maxLength": 200 } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "TextQuote" }, "exact": { "type": "string", "maxLength": 200 }, "prefix": { "type": "string", "maxLength": 200 }, "suffix": { "type": "string", "maxLength": 200 } }, "required": [ "type", "exact" ], "additionalProperties": false } ] } }, "offset": { "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 }, "w": { "type": "number", "minimum": 0, "maximum": 1 }, "h": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "x", "y", "w", "h" ], "additionalProperties": false }, "element": { "type": "object", "properties": { "tag": { "type": "string", "maxLength": 32 }, "role": { "type": "string", "maxLength": 32 }, "text": { "type": "string", "maxLength": 120 } }, "required": [ "tag", "text" ], "additionalProperties": false }, "context": { "type": "object", "properties": { "viewport": { "type": "object", "properties": { "w": { "type": "number" }, "h": { "type": "number" } }, "required": [ "w", "h" ], "additionalProperties": false }, "dpr": { "type": "number" } }, "required": [ "viewport", "dpr" ], "additionalProperties": false } }, "required": [ "v", "kind", "contentHash", "screen", "selectors", "offset", "element", "context" ], "additionalProperties": false } }, "required": [ "kind", "anchor" ], "additionalProperties": false } ] }, "author": { "type": "object", "properties": { "userId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "member", "guest", "agent" ] } }, "required": [ "userId", "name", "kind" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "resolvedAt": { "type": [ "string", "null" ] }, "resolvedBy": { "type": [ "string", "null" ] }, "addressedAt": { "type": [ "string", "null" ] }, "addressedBy": { "type": [ "string", "null" ] }, "commentCount": { "type": "integer" }, "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "threadId": { "type": "string" }, "author": { "type": "object", "properties": { "userId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "member", "guest", "agent" ] } }, "required": [ "userId", "name", "kind" ] }, "body": { "anyOf": [ { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "markdown": { "type": "string", "maxLength": 40000 }, "mentions": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "membershipId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "start": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "label": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "membershipId", "start", "end", "label" ], "additionalProperties": false } } }, "required": [ "markdown", "mentions" ], "additionalProperties": false }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "PUBLISHED", "DELETED", "MODERATED" ] }, "version": { "type": "integer" }, "createdAt": { "type": "string" }, "editedAt": { "type": [ "string", "null" ] }, "canEdit": { "type": "boolean" }, "canDelete": { "type": "boolean" }, "canModerate": { "type": "boolean" } }, "required": [ "id", "threadId", "author", "body", "state", "version", "createdAt", "editedAt", "canEdit", "canDelete", "canModerate" ] } }, "nextCommentCursor": { "type": [ "string", "null" ] }, "canResolve": { "type": "boolean" }, "canReopen": { "type": "boolean" }, "canReattach": { "type": "boolean" }, "subscription": { "type": "string", "enum": [ "auto", "following", "unfollowed", "muted" ] }, "handoff": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "chatUrl": { "type": "string" }, "sentAt": { "type": "string" }, "needsResolution": { "type": "boolean" } }, "required": [ "id", "chatUrl", "sentAt", "needsResolution" ] }, { "type": "null" } ] } }, "required": [ "id", "documentId", "discussionPlanId", "kind", "state", "version", "anchor", "author", "createdAt", "updatedAt", "resolvedAt", "resolvedBy", "addressedAt", "addressedBy", "commentCount", "comments", "nextCommentCursor", "canResolve", "canReopen", "canReattach", "subscription", "handoff" ] } }, "nextCursor": { "type": [ "string", "null" ] }, "order": { "type": "array", "items": { "type": "string" } }, "revisions": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "document", "threads", "nextCursor", "order", "revisions" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createV1DocumentsByDocumentIdThreads", "summary": "Start a document discussion", "tags": [ "Document collaboration" ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The documentId." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "discussionPlanId": { "default": null, "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "body": { "type": "object", "properties": { "markdown": { "type": "string", "maxLength": 40000 }, "mentions": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "membershipId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "start": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "label": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "membershipId", "start", "end", "label" ], "additionalProperties": false } } }, "required": [ "markdown", "mentions" ], "additionalProperties": false }, "anchor": { "default": { "kind": "document" }, "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "document" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "text" }, "revision": { "type": "string", "minLength": 1, "maxLength": 256 }, "exact": { "type": "string", "minLength": 1, "maxLength": 100000 }, "prefix": { "type": "string", "maxLength": 512 }, "suffix": { "type": "string", "maxLength": 512 }, "start": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "blockPath": { "maxItems": 32, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "required": [ "kind", "revision", "exact", "prefix", "suffix", "start", "end" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "quote" }, "revision": { "type": "string", "minLength": 1, "maxLength": 256 }, "exact": { "type": "string", "minLength": 1, "maxLength": 100000 } }, "required": [ "kind", "revision", "exact" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "visual" }, "anchor": { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "kind": { "type": "string", "enum": [ "point", "region" ] }, "contentHash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }, "screen": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 64 }, "confidence": { "type": "string", "enum": [ "hash", "section", "default" ] } }, "required": [ "id", "confidence" ], "additionalProperties": false }, "selectors": { "minItems": 1, "maxItems": 4, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "PinId" }, "value": { "type": "string", "maxLength": 200 } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "CssSelector" }, "value": { "type": "string", "maxLength": 200 } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "TextQuote" }, "exact": { "type": "string", "maxLength": 200 }, "prefix": { "type": "string", "maxLength": 200 }, "suffix": { "type": "string", "maxLength": 200 } }, "required": [ "type", "exact" ], "additionalProperties": false } ] } }, "offset": { "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 }, "w": { "type": "number", "minimum": 0, "maximum": 1 }, "h": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "x", "y", "w", "h" ], "additionalProperties": false }, "element": { "type": "object", "properties": { "tag": { "type": "string", "maxLength": 32 }, "role": { "type": "string", "maxLength": 32 }, "text": { "type": "string", "maxLength": 120 } }, "required": [ "tag", "text" ], "additionalProperties": false }, "context": { "type": "object", "properties": { "viewport": { "type": "object", "properties": { "w": { "type": "number" }, "h": { "type": "number" } }, "required": [ "w", "h" ], "additionalProperties": false }, "dpr": { "type": "number" } }, "required": [ "viewport", "dpr" ], "additionalProperties": false } }, "required": [ "v", "kind", "contentHash", "screen", "selectors", "offset", "element", "context" ], "additionalProperties": false } }, "required": [ "kind", "anchor" ], "additionalProperties": false } ] } }, "required": [ "requestId", "discussionPlanId", "body", "anchor" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "eventId": { "type": "string" }, "threadId": { "type": "string" }, "commentId": { "type": [ "string", "null" ] }, "version": { "type": "integer" } }, "required": [ "eventId", "threadId", "commentId", "version" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/documents/{documentId}/threads/{threadId}": { "get": { "operationId": "getV1DocumentsByDocumentIdThreadsByThreadId", "summary": "Read a thread and its first page of comments", "tags": [ "Document collaboration" ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The documentId." }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The threadId." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "document": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "target": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "plan-item" }, "itemId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "kind", "itemId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "file" }, "path": { "type": "string", "minLength": 1, "maxLength": 4096 }, "fileId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "planId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "kind", "path" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "context" }, "sourceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "original": { "default": false, "type": "boolean" } }, "required": [ "kind", "sourceId", "original" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "format" }, "format": { "type": "string", "enum": [ "spec", "epic" ] }, "builtin": { "type": "boolean" }, "scope": { "oneOf": [ { "type": "object", "properties": { "scope": { "type": "string", "const": "company" } }, "required": [ "scope" ], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "project" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "scope", "projectId" ], "additionalProperties": false } ] }, "destination": { "default": "effective", "type": "string", "enum": [ "effective", "override" ] } }, "required": [ "kind", "format", "scope", "destination" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "instructions" }, "scope": { "type": "string", "enum": [ "company", "project", "plan", "user" ] }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "planId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "kind", "scope" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "skill" }, "scope": { "oneOf": [ { "type": "object", "properties": { "scope": { "type": "string", "const": "company" } }, "required": [ "scope" ], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "project" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "scope", "projectId" ], "additionalProperties": false } ] }, "slug": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9-]*$" } }, "required": [ "kind", "scope", "slug" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "prototype-template" }, "builtin": { "type": "boolean" }, "scope": { "oneOf": [ { "type": "object", "properties": { "scope": { "type": "string", "const": "company" } }, "required": [ "scope" ], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "project" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "scope", "projectId" ], "additionalProperties": false } ] }, "destination": { "default": "effective", "type": "string", "enum": [ "effective", "override" ] } }, "required": [ "kind", "scope", "destination" ], "additionalProperties": false } ] }, "title": { "type": "string" }, "canonicalUrl": { "type": "string" }, "revision": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "sourceDocumentId": { "type": [ "string", "null" ] }, "sourceRevision": { "type": [ "string", "null" ] }, "applyMode": { "type": "string", "enum": [ "native", "external" ] }, "capabilities": { "type": "object", "properties": { "canComment": { "type": "boolean" }, "canSuggest": { "type": "boolean" }, "canMaintain": { "type": "boolean" }, "canUseAgent": { "type": "boolean" }, "needsDiscussionPlan": { "type": "boolean" } }, "required": [ "canComment", "canSuggest", "canMaintain", "canUseAgent", "needsDiscussionPlan" ] }, "discussionPlanId": { "type": [ "string", "null" ] }, "ownerUserIds": { "type": "array", "items": { "type": "string" } }, "ownerNames": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "kind", "target", "title", "canonicalUrl", "revision", "path", "sourceDocumentId", "sourceRevision", "applyMode", "capabilities", "discussionPlanId", "ownerUserIds", "ownerNames" ] }, "thread": { "type": "object", "properties": { "id": { "type": "string" }, "documentId": { "type": "string" }, "discussionPlanId": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "state": { "type": "string", "enum": [ "OPEN", "ADDRESSED", "RESOLVED" ] }, "version": { "type": "integer" }, "anchor": { "$schema": "https://json-schema.org/draft/2020-12/schema", "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "document" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "text" }, "revision": { "type": "string", "minLength": 1, "maxLength": 256 }, "exact": { "type": "string", "minLength": 1, "maxLength": 100000 }, "prefix": { "type": "string", "maxLength": 512 }, "suffix": { "type": "string", "maxLength": 512 }, "start": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "blockPath": { "maxItems": 32, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "required": [ "kind", "revision", "exact", "prefix", "suffix", "start", "end" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "quote" }, "revision": { "type": "string", "minLength": 1, "maxLength": 256 }, "exact": { "type": "string", "minLength": 1, "maxLength": 100000 } }, "required": [ "kind", "revision", "exact" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "visual" }, "anchor": { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "kind": { "type": "string", "enum": [ "point", "region" ] }, "contentHash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }, "screen": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 64 }, "confidence": { "type": "string", "enum": [ "hash", "section", "default" ] } }, "required": [ "id", "confidence" ], "additionalProperties": false }, "selectors": { "minItems": 1, "maxItems": 4, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "PinId" }, "value": { "type": "string", "maxLength": 200 } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "CssSelector" }, "value": { "type": "string", "maxLength": 200 } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "TextQuote" }, "exact": { "type": "string", "maxLength": 200 }, "prefix": { "type": "string", "maxLength": 200 }, "suffix": { "type": "string", "maxLength": 200 } }, "required": [ "type", "exact" ], "additionalProperties": false } ] } }, "offset": { "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 }, "w": { "type": "number", "minimum": 0, "maximum": 1 }, "h": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "x", "y", "w", "h" ], "additionalProperties": false }, "element": { "type": "object", "properties": { "tag": { "type": "string", "maxLength": 32 }, "role": { "type": "string", "maxLength": 32 }, "text": { "type": "string", "maxLength": 120 } }, "required": [ "tag", "text" ], "additionalProperties": false }, "context": { "type": "object", "properties": { "viewport": { "type": "object", "properties": { "w": { "type": "number" }, "h": { "type": "number" } }, "required": [ "w", "h" ], "additionalProperties": false }, "dpr": { "type": "number" } }, "required": [ "viewport", "dpr" ], "additionalProperties": false } }, "required": [ "v", "kind", "contentHash", "screen", "selectors", "offset", "element", "context" ], "additionalProperties": false } }, "required": [ "kind", "anchor" ], "additionalProperties": false } ] }, "author": { "type": "object", "properties": { "userId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "member", "guest", "agent" ] } }, "required": [ "userId", "name", "kind" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "resolvedAt": { "type": [ "string", "null" ] }, "resolvedBy": { "type": [ "string", "null" ] }, "addressedAt": { "type": [ "string", "null" ] }, "addressedBy": { "type": [ "string", "null" ] }, "commentCount": { "type": "integer" }, "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "threadId": { "type": "string" }, "author": { "type": "object", "properties": { "userId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "member", "guest", "agent" ] } }, "required": [ "userId", "name", "kind" ] }, "body": { "anyOf": [ { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "markdown": { "type": "string", "maxLength": 40000 }, "mentions": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "membershipId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "start": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "label": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "membershipId", "start", "end", "label" ], "additionalProperties": false } } }, "required": [ "markdown", "mentions" ], "additionalProperties": false }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "PUBLISHED", "DELETED", "MODERATED" ] }, "version": { "type": "integer" }, "createdAt": { "type": "string" }, "editedAt": { "type": [ "string", "null" ] }, "canEdit": { "type": "boolean" }, "canDelete": { "type": "boolean" }, "canModerate": { "type": "boolean" } }, "required": [ "id", "threadId", "author", "body", "state", "version", "createdAt", "editedAt", "canEdit", "canDelete", "canModerate" ] } }, "nextCommentCursor": { "type": [ "string", "null" ] }, "canResolve": { "type": "boolean" }, "canReopen": { "type": "boolean" }, "canReattach": { "type": "boolean" }, "subscription": { "type": "string", "enum": [ "auto", "following", "unfollowed", "muted" ] }, "handoff": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "chatUrl": { "type": "string" }, "sentAt": { "type": "string" }, "needsResolution": { "type": "boolean" } }, "required": [ "id", "chatUrl", "sentAt", "needsResolution" ] }, { "type": "null" } ] } }, "required": [ "id", "documentId", "discussionPlanId", "kind", "state", "version", "anchor", "author", "createdAt", "updatedAt", "resolvedAt", "resolvedBy", "addressedAt", "addressedBy", "commentCount", "comments", "nextCommentCursor", "canResolve", "canReopen", "canReattach", "subscription", "handoff" ] } }, "required": [ "document", "thread" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updateV1DocumentsByDocumentIdThreadsByThreadId", "summary": "Resolve, reopen or explicitly reattach a thread", "tags": [ "Document collaboration" ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The documentId." }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The threadId." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "expectedVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "action": { "type": "string", "enum": [ "resolve", "reopen", "reattach" ] }, "anchor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "document" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "text" }, "revision": { "type": "string", "minLength": 1, "maxLength": 256 }, "exact": { "type": "string", "minLength": 1, "maxLength": 100000 }, "prefix": { "type": "string", "maxLength": 512 }, "suffix": { "type": "string", "maxLength": 512 }, "start": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "blockPath": { "maxItems": 32, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "required": [ "kind", "revision", "exact", "prefix", "suffix", "start", "end" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "quote" }, "revision": { "type": "string", "minLength": 1, "maxLength": 256 }, "exact": { "type": "string", "minLength": 1, "maxLength": 100000 } }, "required": [ "kind", "revision", "exact" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "visual" }, "anchor": { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "kind": { "type": "string", "enum": [ "point", "region" ] }, "contentHash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }, "screen": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 64 }, "confidence": { "type": "string", "enum": [ "hash", "section", "default" ] } }, "required": [ "id", "confidence" ], "additionalProperties": false }, "selectors": { "minItems": 1, "maxItems": 4, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "PinId" }, "value": { "type": "string", "maxLength": 200 } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "CssSelector" }, "value": { "type": "string", "maxLength": 200 } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "TextQuote" }, "exact": { "type": "string", "maxLength": 200 }, "prefix": { "type": "string", "maxLength": 200 }, "suffix": { "type": "string", "maxLength": 200 } }, "required": [ "type", "exact" ], "additionalProperties": false } ] } }, "offset": { "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 }, "w": { "type": "number", "minimum": 0, "maximum": 1 }, "h": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "x", "y", "w", "h" ], "additionalProperties": false }, "element": { "type": "object", "properties": { "tag": { "type": "string", "maxLength": 32 }, "role": { "type": "string", "maxLength": 32 }, "text": { "type": "string", "maxLength": 120 } }, "required": [ "tag", "text" ], "additionalProperties": false }, "context": { "type": "object", "properties": { "viewport": { "type": "object", "properties": { "w": { "type": "number" }, "h": { "type": "number" } }, "required": [ "w", "h" ], "additionalProperties": false }, "dpr": { "type": "number" } }, "required": [ "viewport", "dpr" ], "additionalProperties": false } }, "required": [ "v", "kind", "contentHash", "screen", "selectors", "offset", "element", "context" ], "additionalProperties": false } }, "required": [ "kind", "anchor" ], "additionalProperties": false } ] } }, "required": [ "requestId", "expectedVersion", "action" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "eventId": { "type": "string" }, "threadId": { "type": "string" }, "commentId": { "type": [ "string", "null" ] }, "version": { "type": "integer" } }, "required": [ "eventId", "threadId", "commentId", "version" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/documents/{documentId}/threads/{threadId}/comments": { "get": { "operationId": "getV1DocumentsByDocumentIdThreadsByThreadIdComments", "summary": "Read the next page of replies", "tags": [ "Document collaboration" ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The documentId." }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The threadId." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor returned by the preceding page." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "threadId": { "type": "string" }, "author": { "type": "object", "properties": { "userId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "member", "guest", "agent" ] } }, "required": [ "userId", "name", "kind" ] }, "body": { "anyOf": [ { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "markdown": { "type": "string", "maxLength": 40000 }, "mentions": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "membershipId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "start": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "label": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "membershipId", "start", "end", "label" ], "additionalProperties": false } } }, "required": [ "markdown", "mentions" ], "additionalProperties": false }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "PUBLISHED", "DELETED", "MODERATED" ] }, "version": { "type": "integer" }, "createdAt": { "type": "string" }, "editedAt": { "type": [ "string", "null" ] }, "canEdit": { "type": "boolean" }, "canDelete": { "type": "boolean" }, "canModerate": { "type": "boolean" } }, "required": [ "id", "threadId", "author", "body", "state", "version", "createdAt", "editedAt", "canEdit", "canDelete", "canModerate" ] } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "comments", "nextCursor" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createV1DocumentsByDocumentIdThreadsByThreadIdComments", "summary": "Reply without changing the thread resolution", "tags": [ "Document collaboration" ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The documentId." }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The threadId." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "body": { "type": "object", "properties": { "markdown": { "type": "string", "maxLength": 40000 }, "mentions": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "membershipId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "start": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "label": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "membershipId", "start", "end", "label" ], "additionalProperties": false } } }, "required": [ "markdown", "mentions" ], "additionalProperties": false } }, "required": [ "requestId", "body" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "eventId": { "type": "string" }, "threadId": { "type": "string" }, "commentId": { "type": [ "string", "null" ] }, "version": { "type": "integer" }, "state": { "type": "string", "enum": [ "OPEN", "ADDRESSED", "RESOLVED" ] }, "addressed": { "type": "boolean" }, "notAddressed": { "type": [ "string", "null" ], "enum": [ "suggestion", "not_open", "not_saved", null ] } }, "required": [ "eventId", "threadId", "commentId", "version", "state", "addressed", "notAddressed" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/documents/{documentId}/threads/{threadId}/comments/{commentId}": { "patch": { "operationId": "updateV1DocumentsByDocumentIdThreadsByThreadIdCommentsByCommentId", "summary": "Edit, delete or moderate a comment with a version check", "tags": [ "Document collaboration" ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The documentId." }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The threadId." }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Prototype comment id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "expectedVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "action": { "type": "string", "enum": [ "edit", "delete", "moderate" ] }, "body": { "type": "object", "properties": { "markdown": { "type": "string", "maxLength": 40000 }, "mentions": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "membershipId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "start": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "label": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "membershipId", "start", "end", "label" ], "additionalProperties": false } } }, "required": [ "markdown", "mentions" ], "additionalProperties": false }, "reason": { "type": "string", "maxLength": 1000 } }, "required": [ "requestId", "expectedVersion", "action" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "eventId": { "type": "string" }, "threadId": { "type": "string" }, "commentId": { "type": [ "string", "null" ] }, "version": { "type": "integer" } }, "required": [ "eventId", "threadId", "commentId", "version" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/documents/{documentId}/threads/{threadId}/comments/{commentId}/history": { "get": { "operationId": "getV1DocumentsByDocumentIdThreadsByThreadIdCommentsByCommentIdHistory", "summary": "Read immutable comment history subject to current permissions", "tags": [ "Document collaboration" ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The documentId." }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The threadId." }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Prototype comment id." }, { "name": "beforeVersion", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Read versions older than this revision." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "revisions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "integer" }, "body": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "markdown": { "type": "string", "maxLength": 40000 }, "mentions": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "membershipId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "start": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "label": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "membershipId", "start", "end", "label" ], "additionalProperties": false } } }, "required": [ "markdown", "mentions" ], "additionalProperties": false }, "state": { "type": "string" }, "actor_user_id": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "version", "body", "state", "actor_user_id", "reason", "created_at" ] } }, "nextVersion": { "type": [ "integer", "null" ] } }, "required": [ "revisions", "nextVersion" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/documents/{documentId}/threads/{threadId}/subscription": { "put": { "operationId": "setV1DocumentsByDocumentIdThreadsByThreadIdSubscription", "summary": "Follow, unfollow or mute this thread", "tags": [ "Document collaboration" ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The documentId." }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The threadId." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "subscription": { "type": "string", "enum": [ "following", "unfollowed", "muted" ] } }, "required": [ "requestId", "subscription" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "eventId": { "type": "string" }, "threadId": { "type": "string" }, "commentId": { "type": [ "string", "null" ] }, "version": { "type": "integer" } }, "required": [ "eventId", "threadId", "commentId", "version" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/document-collaboration": { "post": { "operationId": "createV1DocumentCollaboration", "summary": "Run a document collaboration command using the shared service contract", "tags": [ "Document collaboration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "operation": { "type": "string", "enum": [ "resolve-document", "get-document", "discussion-plans", "mention-candidates", "prepare-handoff", "resolve-handoff", "list-threads", "get-thread", "list-comments", "comment-history", "subscribe", "create-thread", "reply", "update-thread", "update-comment", "list-suggestions", "get-suggestion", "suggestion-history", "create-suggestion", "revise-suggestion", "decide-suggestion" ] }, "documentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "threadId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "commentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "suggestionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "discussionPlanId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "target": {}, "input": {}, "cursor": { "type": "string", "maxLength": 128 }, "knownRevisions": { "type": "object", "propertyNames": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "additionalProperties": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "beforeVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "query": { "type": "string", "maxLength": 200 } }, "required": [ "operation" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "eventId": { "type": "string" }, "threadId": { "type": "string" }, "commentId": { "type": [ "string", "null" ] }, "version": { "type": "integer" } }, "required": [ "eventId", "threadId", "commentId", "version" ] }, { "type": "object", "properties": { "document": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "target": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "plan-item" }, "itemId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "kind", "itemId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "file" }, "path": { "type": "string", "minLength": 1, "maxLength": 4096 }, "fileId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "planId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "kind", "path" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "context" }, "sourceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "original": { "default": false, "type": "boolean" } }, "required": [ "kind", "sourceId", "original" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "format" }, "format": { "type": "string", "enum": [ "spec", "epic" ] }, "builtin": { "type": "boolean" }, "scope": { "oneOf": [ { "type": "object", "properties": { "scope": { "type": "string", "const": "company" } }, "required": [ "scope" ], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "project" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "scope", "projectId" ], "additionalProperties": false } ] }, "destination": { "default": "effective", "type": "string", "enum": [ "effective", "override" ] } }, "required": [ "kind", "format", "scope", "destination" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "instructions" }, "scope": { "type": "string", "enum": [ "company", "project", "plan", "user" ] }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "planId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "kind", "scope" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "skill" }, "scope": { "oneOf": [ { "type": "object", "properties": { "scope": { "type": "string", "const": "company" } }, "required": [ "scope" ], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "project" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "scope", "projectId" ], "additionalProperties": false } ] }, "slug": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9-]*$" } }, "required": [ "kind", "scope", "slug" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "prototype-template" }, "builtin": { "type": "boolean" }, "scope": { "oneOf": [ { "type": "object", "properties": { "scope": { "type": "string", "const": "company" } }, "required": [ "scope" ], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "project" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "scope", "projectId" ], "additionalProperties": false } ] }, "destination": { "default": "effective", "type": "string", "enum": [ "effective", "override" ] } }, "required": [ "kind", "scope", "destination" ], "additionalProperties": false } ] }, "title": { "type": "string" }, "canonicalUrl": { "type": "string" }, "revision": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "sourceDocumentId": { "type": [ "string", "null" ] }, "sourceRevision": { "type": [ "string", "null" ] }, "applyMode": { "type": "string", "enum": [ "native", "external" ] }, "capabilities": { "type": "object", "properties": { "canComment": { "type": "boolean" }, "canSuggest": { "type": "boolean" }, "canMaintain": { "type": "boolean" }, "canUseAgent": { "type": "boolean" }, "needsDiscussionPlan": { "type": "boolean" } }, "required": [ "canComment", "canSuggest", "canMaintain", "canUseAgent", "needsDiscussionPlan" ] }, "discussionPlanId": { "type": [ "string", "null" ] }, "ownerUserIds": { "type": "array", "items": { "type": "string" } }, "ownerNames": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "kind", "target", "title", "canonicalUrl", "revision", "path", "sourceDocumentId", "sourceRevision", "applyMode", "capabilities", "discussionPlanId", "ownerUserIds", "ownerNames" ] }, "thread": { "type": "object", "properties": { "id": { "type": "string" }, "documentId": { "type": "string" }, "discussionPlanId": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "state": { "type": "string", "enum": [ "OPEN", "ADDRESSED", "RESOLVED" ] }, "version": { "type": "integer" }, "anchor": { "$schema": "https://json-schema.org/draft/2020-12/schema", "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "document" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "text" }, "revision": { "type": "string", "minLength": 1, "maxLength": 256 }, "exact": { "type": "string", "minLength": 1, "maxLength": 100000 }, "prefix": { "type": "string", "maxLength": 512 }, "suffix": { "type": "string", "maxLength": 512 }, "start": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "blockPath": { "maxItems": 32, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "required": [ "kind", "revision", "exact", "prefix", "suffix", "start", "end" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "quote" }, "revision": { "type": "string", "minLength": 1, "maxLength": 256 }, "exact": { "type": "string", "minLength": 1, "maxLength": 100000 } }, "required": [ "kind", "revision", "exact" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "visual" }, "anchor": { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "kind": { "type": "string", "enum": [ "point", "region" ] }, "contentHash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }, "screen": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 64 }, "confidence": { "type": "string", "enum": [ "hash", "section", "default" ] } }, "required": [ "id", "confidence" ], "additionalProperties": false }, "selectors": { "minItems": 1, "maxItems": 4, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "PinId" }, "value": { "type": "string", "maxLength": 200 } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "CssSelector" }, "value": { "type": "string", "maxLength": 200 } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "TextQuote" }, "exact": { "type": "string", "maxLength": 200 }, "prefix": { "type": "string", "maxLength": 200 }, "suffix": { "type": "string", "maxLength": 200 } }, "required": [ "type", "exact" ], "additionalProperties": false } ] } }, "offset": { "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 }, "w": { "type": "number", "minimum": 0, "maximum": 1 }, "h": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "x", "y", "w", "h" ], "additionalProperties": false }, "element": { "type": "object", "properties": { "tag": { "type": "string", "maxLength": 32 }, "role": { "type": "string", "maxLength": 32 }, "text": { "type": "string", "maxLength": 120 } }, "required": [ "tag", "text" ], "additionalProperties": false }, "context": { "type": "object", "properties": { "viewport": { "type": "object", "properties": { "w": { "type": "number" }, "h": { "type": "number" } }, "required": [ "w", "h" ], "additionalProperties": false }, "dpr": { "type": "number" } }, "required": [ "viewport", "dpr" ], "additionalProperties": false } }, "required": [ "v", "kind", "contentHash", "screen", "selectors", "offset", "element", "context" ], "additionalProperties": false } }, "required": [ "kind", "anchor" ], "additionalProperties": false } ] }, "author": { "type": "object", "properties": { "userId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "member", "guest", "agent" ] } }, "required": [ "userId", "name", "kind" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "resolvedAt": { "type": [ "string", "null" ] }, "resolvedBy": { "type": [ "string", "null" ] }, "addressedAt": { "type": [ "string", "null" ] }, "addressedBy": { "type": [ "string", "null" ] }, "commentCount": { "type": "integer" }, "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "threadId": { "type": "string" }, "author": { "type": "object", "properties": { "userId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "member", "guest", "agent" ] } }, "required": [ "userId", "name", "kind" ] }, "body": { "anyOf": [ { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "markdown": { "type": "string", "maxLength": 40000 }, "mentions": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "membershipId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "start": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "label": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "membershipId", "start", "end", "label" ], "additionalProperties": false } } }, "required": [ "markdown", "mentions" ], "additionalProperties": false }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "PUBLISHED", "DELETED", "MODERATED" ] }, "version": { "type": "integer" }, "createdAt": { "type": "string" }, "editedAt": { "type": [ "string", "null" ] }, "canEdit": { "type": "boolean" }, "canDelete": { "type": "boolean" }, "canModerate": { "type": "boolean" } }, "required": [ "id", "threadId", "author", "body", "state", "version", "createdAt", "editedAt", "canEdit", "canDelete", "canModerate" ] } }, "nextCommentCursor": { "type": [ "string", "null" ] }, "canResolve": { "type": "boolean" }, "canReopen": { "type": "boolean" }, "canReattach": { "type": "boolean" }, "subscription": { "type": "string", "enum": [ "auto", "following", "unfollowed", "muted" ] }, "handoff": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "chatUrl": { "type": "string" }, "sentAt": { "type": "string" }, "needsResolution": { "type": "boolean" } }, "required": [ "id", "chatUrl", "sentAt", "needsResolution" ] }, { "type": "null" } ] } }, "required": [ "id", "documentId", "discussionPlanId", "kind", "state", "version", "anchor", "author", "createdAt", "updatedAt", "resolvedAt", "resolvedBy", "addressedAt", "addressedBy", "commentCount", "comments", "nextCommentCursor", "canResolve", "canReopen", "canReattach", "subscription", "handoff" ] } }, "required": [ "document", "thread" ] }, { "type": "object", "properties": { "document": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "target": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "plan-item" }, "itemId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "kind", "itemId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "file" }, "path": { "type": "string", "minLength": 1, "maxLength": 4096 }, "fileId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "planId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "kind", "path" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "context" }, "sourceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "original": { "default": false, "type": "boolean" } }, "required": [ "kind", "sourceId", "original" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "format" }, "format": { "type": "string", "enum": [ "spec", "epic" ] }, "builtin": { "type": "boolean" }, "scope": { "oneOf": [ { "type": "object", "properties": { "scope": { "type": "string", "const": "company" } }, "required": [ "scope" ], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "project" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "scope", "projectId" ], "additionalProperties": false } ] }, "destination": { "default": "effective", "type": "string", "enum": [ "effective", "override" ] } }, "required": [ "kind", "format", "scope", "destination" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "instructions" }, "scope": { "type": "string", "enum": [ "company", "project", "plan", "user" ] }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "planId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "kind", "scope" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "skill" }, "scope": { "oneOf": [ { "type": "object", "properties": { "scope": { "type": "string", "const": "company" } }, "required": [ "scope" ], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "project" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "scope", "projectId" ], "additionalProperties": false } ] }, "slug": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9-]*$" } }, "required": [ "kind", "scope", "slug" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "prototype-template" }, "builtin": { "type": "boolean" }, "scope": { "oneOf": [ { "type": "object", "properties": { "scope": { "type": "string", "const": "company" } }, "required": [ "scope" ], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "project" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "scope", "projectId" ], "additionalProperties": false } ] }, "destination": { "default": "effective", "type": "string", "enum": [ "effective", "override" ] } }, "required": [ "kind", "scope", "destination" ], "additionalProperties": false } ] }, "title": { "type": "string" }, "canonicalUrl": { "type": "string" }, "revision": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "sourceDocumentId": { "type": [ "string", "null" ] }, "sourceRevision": { "type": [ "string", "null" ] }, "applyMode": { "type": "string", "enum": [ "native", "external" ] }, "capabilities": { "type": "object", "properties": { "canComment": { "type": "boolean" }, "canSuggest": { "type": "boolean" }, "canMaintain": { "type": "boolean" }, "canUseAgent": { "type": "boolean" }, "needsDiscussionPlan": { "type": "boolean" } }, "required": [ "canComment", "canSuggest", "canMaintain", "canUseAgent", "needsDiscussionPlan" ] }, "discussionPlanId": { "type": [ "string", "null" ] }, "ownerUserIds": { "type": "array", "items": { "type": "string" } }, "ownerNames": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "kind", "target", "title", "canonicalUrl", "revision", "path", "sourceDocumentId", "sourceRevision", "applyMode", "capabilities", "discussionPlanId", "ownerUserIds", "ownerNames" ] }, "threads": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "documentId": { "type": "string" }, "discussionPlanId": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "state": { "type": "string", "enum": [ "OPEN", "ADDRESSED", "RESOLVED" ] }, "version": { "type": "integer" }, "anchor": { "$schema": "https://json-schema.org/draft/2020-12/schema", "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "document" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "text" }, "revision": { "type": "string", "minLength": 1, "maxLength": 256 }, "exact": { "type": "string", "minLength": 1, "maxLength": 100000 }, "prefix": { "type": "string", "maxLength": 512 }, "suffix": { "type": "string", "maxLength": 512 }, "start": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "blockPath": { "maxItems": 32, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "required": [ "kind", "revision", "exact", "prefix", "suffix", "start", "end" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "quote" }, "revision": { "type": "string", "minLength": 1, "maxLength": 256 }, "exact": { "type": "string", "minLength": 1, "maxLength": 100000 } }, "required": [ "kind", "revision", "exact" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "visual" }, "anchor": { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "kind": { "type": "string", "enum": [ "point", "region" ] }, "contentHash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }, "screen": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 64 }, "confidence": { "type": "string", "enum": [ "hash", "section", "default" ] } }, "required": [ "id", "confidence" ], "additionalProperties": false }, "selectors": { "minItems": 1, "maxItems": 4, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "PinId" }, "value": { "type": "string", "maxLength": 200 } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "CssSelector" }, "value": { "type": "string", "maxLength": 200 } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "TextQuote" }, "exact": { "type": "string", "maxLength": 200 }, "prefix": { "type": "string", "maxLength": 200 }, "suffix": { "type": "string", "maxLength": 200 } }, "required": [ "type", "exact" ], "additionalProperties": false } ] } }, "offset": { "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 }, "w": { "type": "number", "minimum": 0, "maximum": 1 }, "h": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "x", "y", "w", "h" ], "additionalProperties": false }, "element": { "type": "object", "properties": { "tag": { "type": "string", "maxLength": 32 }, "role": { "type": "string", "maxLength": 32 }, "text": { "type": "string", "maxLength": 120 } }, "required": [ "tag", "text" ], "additionalProperties": false }, "context": { "type": "object", "properties": { "viewport": { "type": "object", "properties": { "w": { "type": "number" }, "h": { "type": "number" } }, "required": [ "w", "h" ], "additionalProperties": false }, "dpr": { "type": "number" } }, "required": [ "viewport", "dpr" ], "additionalProperties": false } }, "required": [ "v", "kind", "contentHash", "screen", "selectors", "offset", "element", "context" ], "additionalProperties": false } }, "required": [ "kind", "anchor" ], "additionalProperties": false } ] }, "author": { "type": "object", "properties": { "userId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "member", "guest", "agent" ] } }, "required": [ "userId", "name", "kind" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "resolvedAt": { "type": [ "string", "null" ] }, "resolvedBy": { "type": [ "string", "null" ] }, "addressedAt": { "type": [ "string", "null" ] }, "addressedBy": { "type": [ "string", "null" ] }, "commentCount": { "type": "integer" }, "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "threadId": { "type": "string" }, "author": { "type": "object", "properties": { "userId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "member", "guest", "agent" ] } }, "required": [ "userId", "name", "kind" ] }, "body": { "anyOf": [ { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "markdown": { "type": "string", "maxLength": 40000 }, "mentions": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "membershipId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "start": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "label": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "membershipId", "start", "end", "label" ], "additionalProperties": false } } }, "required": [ "markdown", "mentions" ], "additionalProperties": false }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "PUBLISHED", "DELETED", "MODERATED" ] }, "version": { "type": "integer" }, "createdAt": { "type": "string" }, "editedAt": { "type": [ "string", "null" ] }, "canEdit": { "type": "boolean" }, "canDelete": { "type": "boolean" }, "canModerate": { "type": "boolean" } }, "required": [ "id", "threadId", "author", "body", "state", "version", "createdAt", "editedAt", "canEdit", "canDelete", "canModerate" ] } }, "nextCommentCursor": { "type": [ "string", "null" ] }, "canResolve": { "type": "boolean" }, "canReopen": { "type": "boolean" }, "canReattach": { "type": "boolean" }, "subscription": { "type": "string", "enum": [ "auto", "following", "unfollowed", "muted" ] }, "handoff": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "chatUrl": { "type": "string" }, "sentAt": { "type": "string" }, "needsResolution": { "type": "boolean" } }, "required": [ "id", "chatUrl", "sentAt", "needsResolution" ] }, { "type": "null" } ] } }, "required": [ "id", "documentId", "discussionPlanId", "kind", "state", "version", "anchor", "author", "createdAt", "updatedAt", "resolvedAt", "resolvedBy", "addressedAt", "addressedBy", "commentCount", "comments", "nextCommentCursor", "canResolve", "canReopen", "canReattach", "subscription", "handoff" ] } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "document", "threads", "nextCursor" ] }, { "type": "object", "properties": { "document": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "target": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "plan-item" }, "itemId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "kind", "itemId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "file" }, "path": { "type": "string", "minLength": 1, "maxLength": 4096 }, "fileId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "planId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "kind", "path" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "context" }, "sourceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "original": { "default": false, "type": "boolean" } }, "required": [ "kind", "sourceId", "original" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "format" }, "format": { "type": "string", "enum": [ "spec", "epic" ] }, "builtin": { "type": "boolean" }, "scope": { "oneOf": [ { "type": "object", "properties": { "scope": { "type": "string", "const": "company" } }, "required": [ "scope" ], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "project" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "scope", "projectId" ], "additionalProperties": false } ] }, "destination": { "default": "effective", "type": "string", "enum": [ "effective", "override" ] } }, "required": [ "kind", "format", "scope", "destination" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "instructions" }, "scope": { "type": "string", "enum": [ "company", "project", "plan", "user" ] }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "planId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "kind", "scope" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "skill" }, "scope": { "oneOf": [ { "type": "object", "properties": { "scope": { "type": "string", "const": "company" } }, "required": [ "scope" ], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "project" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "scope", "projectId" ], "additionalProperties": false } ] }, "slug": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9-]*$" } }, "required": [ "kind", "scope", "slug" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "prototype-template" }, "builtin": { "type": "boolean" }, "scope": { "oneOf": [ { "type": "object", "properties": { "scope": { "type": "string", "const": "company" } }, "required": [ "scope" ], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "project" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "scope", "projectId" ], "additionalProperties": false } ] }, "destination": { "default": "effective", "type": "string", "enum": [ "effective", "override" ] } }, "required": [ "kind", "scope", "destination" ], "additionalProperties": false } ] }, "title": { "type": "string" }, "canonicalUrl": { "type": "string" }, "revision": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "sourceDocumentId": { "type": [ "string", "null" ] }, "sourceRevision": { "type": [ "string", "null" ] }, "applyMode": { "type": "string", "enum": [ "native", "external" ] }, "capabilities": { "type": "object", "properties": { "canComment": { "type": "boolean" }, "canSuggest": { "type": "boolean" }, "canMaintain": { "type": "boolean" }, "canUseAgent": { "type": "boolean" }, "needsDiscussionPlan": { "type": "boolean" } }, "required": [ "canComment", "canSuggest", "canMaintain", "canUseAgent", "needsDiscussionPlan" ] }, "discussionPlanId": { "type": [ "string", "null" ] }, "ownerUserIds": { "type": "array", "items": { "type": "string" } }, "ownerNames": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "kind", "target", "title", "canonicalUrl", "revision", "path", "sourceDocumentId", "sourceRevision", "applyMode", "capabilities", "discussionPlanId", "ownerUserIds", "ownerNames" ] }, "sourceText": { "type": [ "string", "null" ] }, "viewer": { "type": "object", "properties": { "userId": { "type": "string" }, "organizationId": { "type": "string" } }, "required": [ "userId", "organizationId" ] } }, "required": [ "document", "sourceText", "viewer" ] }, { "type": "object", "properties": { "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "threadId": { "type": "string" }, "author": { "type": "object", "properties": { "userId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "member", "guest", "agent" ] } }, "required": [ "userId", "name", "kind" ] }, "body": { "anyOf": [ { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "markdown": { "type": "string", "maxLength": 40000 }, "mentions": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "membershipId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "start": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "label": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "membershipId", "start", "end", "label" ], "additionalProperties": false } } }, "required": [ "markdown", "mentions" ], "additionalProperties": false }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "PUBLISHED", "DELETED", "MODERATED" ] }, "version": { "type": "integer" }, "createdAt": { "type": "string" }, "editedAt": { "type": [ "string", "null" ] }, "canEdit": { "type": "boolean" }, "canDelete": { "type": "boolean" }, "canModerate": { "type": "boolean" } }, "required": [ "id", "threadId", "author", "body", "state", "version", "createdAt", "editedAt", "canEdit", "canDelete", "canModerate" ] } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "comments", "nextCursor" ] } ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1": { "get": { "operationId": "getV1", "summary": "API index, plus the identity of the calling credential when one is sent", "tags": [ "Identity" ], "security": [ {}, { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "description": { "type": "string" }, "workspace": { "$ref": "#/components/schemas/Workspace" }, "scope": { "type": "string", "enum": [ "read", "write" ] }, "credential": { "type": "string", "enum": [ "api_key", "oauth" ] }, "authentication": { "type": "object", "description": "How to obtain a credential. Present on the anonymous response only.", "additionalProperties": true }, "links": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "name", "version", "links" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/api-keys": { "get": { "operationId": "getV1ApiKeys", "summary": "List your API keys in this workspace", "tags": [ "Credentials" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } }, "required": [ "keys" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createV1ApiKeys", "summary": "Mint an API key (the secret is returned once)", "tags": [ "Credentials" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 80 }, "scope": { "type": "string", "enum": [ "read", "write" ] } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/ApiKey" }, "secret": { "type": "string", "description": "Returned once, at creation, and never again." }, "message": { "type": "string" } }, "required": [ "key", "secret" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/api-keys/{keyId}": { "delete": { "operationId": "deleteV1ApiKeysByKeyId", "summary": "Revoke one of your API keys", "tags": [ "Credentials" ], "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "API key id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/ApiKey" } }, "required": [ "key" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/connectors": { "get": { "operationId": "getV1Connectors", "summary": "The connector catalog, with this workspace’s connection status", "tags": [ "Connectors" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connectors": { "type": "array", "items": { "$ref": "#/components/schemas/Connector" } } }, "required": [ "connectors" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/connectors/{connectorId}/connect": { "post": { "operationId": "createV1ConnectorsByConnectorIdConnect", "summary": "Connect a tracker or MCP connector", "tags": [ "Connectors" ], "parameters": [ { "name": "connectorId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connector id, e.g. `linear`. Custom servers use the `x_` prefix." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKey": { "type": "string" }, "returnTo": { "type": "string", "description": "A local path; anything else is refused." } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "workspace_key", "api_key", "already_connected", "oauth" ] }, "connected": { "type": "boolean" }, "connector": { "type": "string" }, "authorizeUrl": { "type": "string", "description": "Present when `mode` is `oauth`." }, "remainingGrants": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "mode", "connected", "connector" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteV1ConnectorsByConnectorIdConnect", "summary": "Disconnect a connector", "tags": [ "Connectors" ], "parameters": [ { "name": "connectorId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connector id, e.g. `linear`. Custom servers use the `x_` prefix." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "disconnected": { "type": "boolean" }, "connector": { "type": "string" } }, "required": [ "disconnected", "connector" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/connectors/{connectorId}/toolsets": { "get": { "operationId": "getV1ConnectorsByConnectorIdToolsets", "summary": "The connector’s MCP toolset", "tags": [ "Connectors" ], "parameters": [ { "name": "connectorId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connector id, e.g. `linear`. Custom servers use the `x_` prefix." }, { "name": "projectSlug", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Read the project override instead." }, { "name": "refresh", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pass `true` to re-probe the server." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connectorId": { "type": "string" }, "label": { "type": "string" }, "enabled": { "$ref": "#/components/schemas/PolicyState" }, "toolset": { "type": "object", "properties": { "count": { "type": "integer" }, "discoveredAt": { "type": [ "string", "null" ] }, "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "access": { "type": "string", "enum": [ "read", "write" ] }, "description": { "type": "string" } } } } }, "required": [ "count", "tools" ] } }, "required": [ "connectorId", "label", "enabled", "toolset" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updateV1ConnectorsByConnectorIdToolsets", "summary": "Enable or disable a connector’s MCP tools", "tags": [ "Connectors" ], "parameters": [ { "name": "connectorId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connector id, e.g. `linear`. Custom servers use the `x_` prefix." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "projectSlug": { "type": "string", "description": "Present writes a project override; absent writes the workspace value." } }, "required": [ "enabled" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connectorId": { "type": "string" }, "enabled": { "$ref": "#/components/schemas/PolicyState" } }, "required": [ "connectorId", "enabled" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/context": { "get": { "operationId": "getV1Context", "summary": "List the Context sources for the workspace", "tags": [ "Context" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sources": { "type": "array", "items": { "$ref": "#/components/schemas/ContextSource" } } }, "required": [ "sources" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createV1Context", "summary": "Attach a Context source to the workspace", "tags": [ "Context" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sourceKind": { "type": "string", "enum": [ "PASTED", "URL" ] }, "title": { "type": "string" }, "kind": { "type": "string", "description": "Defaults to `prd`." }, "description": { "type": [ "string", "null" ] }, "text": { "type": "string", "description": "Required when `sourceKind` is `PASTED`." }, "url": { "type": "string", "description": "Required when `sourceKind` is `URL`." } }, "required": [ "sourceKind", "title" ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/ContextSource" } }, "required": [ "source" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/context/upload": { "post": { "operationId": "createV1ContextUpload", "summary": "Upload a file as a Context source (on_conflict: keep_both | replace | skip)", "tags": [ "Context" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The document to upload. Accepts pdf, docx, doc, xlsx, pptx, csv, md, txt, html, svg, yaml, json, xml, xsd, xsl, png, jpg, gif, webp, mp4, mov, webm. Up to 4 MB in THIS request body; past that, mint an upload URL and send `storage_ref` instead." }, "storage_ref": { "type": "string", "description": "The reference returned by `POST …/context/upload-url`, after the bytes have been PUT to its signed URL. Send this INSTEAD of `file` for anything over 4 MB. Requires `filename`." }, "filename": { "type": "string", "description": "The original file name. Required with `storage_ref`; ignored with `file`." }, "title": { "type": "string", "description": "Defaults to the file name." }, "kind": { "type": "string" }, "description": { "type": "string" }, "folderPath": { "type": "string" }, "onConflict": { "type": "string", "enum": [ "keep_both", "replace", "skip" ], "description": "Defaults to `keep_both`. `on_conflict` is accepted as an alias." }, "expectedSourceId": { "type": "string", "format": "uuid" }, "replaceSourceId": { "type": "string", "format": "uuid", "description": "Replace THIS uploaded document with the file, whatever the file is called: its id, scope and folder are kept, its file and text are new. It must be at the scope of this route (404 otherwise, including an id from another workspace). With `onConflict=replace` and no id, the document with the same title in the folder is replaced; a 409 lists the ids when two share it." } } } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/ContextSource" } }, "required": [ "source" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "With `onConflict=replace`, more than one document in the folder has this title; the message lists their ids. Send the one to replace as `replaceSourceId`. (A `replaceSourceId` that is not an uploaded document at this scope is a 404.)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/context/upload-url": { "post": { "operationId": "createV1ContextUploadUrl", "summary": "Mint a signed upload URL for a large file, then post its storage_ref", "tags": [ "Context" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string", "description": "The original file name. Decides the type when none is sent." }, "content_type": { "type": "string", "description": "Optional. `application/octet-stream` (what curl and most SDKs send) is ignored in favour of the extension." }, "size": { "type": "integer", "description": "Bytes. Refused up front past the cap for this kind: 25 MB for a document, 2 GB for a recording." }, "duration_seconds": { "type": "number", "description": "Optional, recordings only. Refused past 2 hours before the upload starts. Re-checked against the container once the bytes land." } }, "required": [ "filename", "size" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storage_ref": { "type": "string", "description": "Post this back as `storage_ref` on the upload form once the PUT succeeds." }, "url": { "type": "string", "description": "A one-shot signed URL. PUT the raw bytes to it, with no auth header." }, "token": { "type": "string", "description": "For a client using supabase-js `uploadToSignedUrl`, which takes path + token rather than a URL." } }, "required": [ "storage_ref", "url", "token" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/context/download": { "get": { "operationId": "getV1ContextDownload", "summary": "Download the workspace's Context as a zip archive", "tags": [ "Context" ], "parameters": [ { "name": "folder", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only this folder and everything under it, e.g. `research/interviews`. An unknown folder is a 400." }, { "name": "only", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only these entries: comma-separated ids from the context list (documents) or the manifest (agent files). An id this scope does not own is a 400 that names it, never skipped." } ], "responses": { "200": { "description": "Success.", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/context/{sourceId}": { "get": { "operationId": "getV1ContextBySourceId", "summary": "Get a Context source", "tags": [ "Context" ], "parameters": [ { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Context source id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/ContextSourceDetail" } }, "required": [ "source" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteV1ContextBySourceId", "summary": "Remove a Context source", "tags": [ "Context" ], "parameters": [ { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Context source id." }, { "name": "expectedUpdatedAt", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Compare-and-set: a mismatch answers 409 rather than overwriting a newer edit." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/context/{sourceId}/refresh": { "post": { "operationId": "createV1ContextBySourceIdRefresh", "summary": "Re-fetch a URL-backed Context source", "tags": [ "Context" ], "parameters": [ { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Context source id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/ContextSourceDetail" } }, "required": [ "source" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/context/{sourceId}/file": { "get": { "operationId": "getV1ContextBySourceIdFile", "summary": "Download a Context source’s original file, byte for byte", "tags": [ "Context" ], "parameters": [ { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Context source id." } ], "responses": { "200": { "description": "Success.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/formats/{kind}": { "get": { "operationId": "getV1FormatsByKind", "summary": "The resolved Spec or Epic format, with its source tier", "tags": [ "Formats" ], "parameters": [ { "name": "kind", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Either `spec` or `epic`." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "$ref": "#/components/schemas/Format" } }, "required": [ "format" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "setV1FormatsByKind", "summary": "Set the workspace’s Spec or Epic format (owner only)", "tags": [ "Formats" ], "parameters": [ { "name": "kind", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Either `spec` or `epic`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "markdown": { "type": "string" }, "expectedRevision": { "type": [ "string", "null" ], "description": "Destination overrideRevision from GET. Null requires absence. Omission preserves legacy unconditional writes. New clients should always supply this; stale writes return 409." } }, "required": [ "markdown" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "$ref": "#/components/schemas/Format" } }, "required": [ "format" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "This format changed. Read it again before saving.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteV1FormatsByKind", "summary": "Reset the workspace format to the built-in", "tags": [ "Formats" ], "parameters": [ { "name": "kind", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Either `spec` or `epic`." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedRevision": { "type": [ "string", "null" ], "description": "Destination overrideRevision from GET. Null requires absence. Omission preserves legacy unconditional writes. New clients should always supply this; stale writes return 409." } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "boolean" }, "format": { "$ref": "#/components/schemas/Format" } }, "required": [ "removed", "format" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "This format changed. Read it again before saving.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/prototype-template": { "get": { "operationId": "getV1PrototypeTemplate", "summary": "The prototype template in force for the workspace, with its source tier", "tags": [ "Prototype template" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "template": { "$ref": "#/components/schemas/PrototypeTemplate" } }, "required": [ "template" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "setV1PrototypeTemplate", "summary": "Set the workspace’s prototype template (owner only); validated before it is stored", "tags": [ "Prototype template" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "html": { "type": "string", "description": "The whole template document. Validated before it is stored: no scripts, frames, forms or handlers, no assets beyond the pinned font and icons, `.ps-*` styles only, and one empty `` per required slot. A refusal is a validation error whose `details.findings` name each rule broken." } }, "required": [ "html" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "template": { "$ref": "#/components/schemas/PrototypeTemplate" } }, "required": [ "template" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteV1PrototypeTemplate", "summary": "Remove the workspace prototype template, back to the built-in", "tags": [ "Prototype template" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "boolean" }, "template": { "$ref": "#/components/schemas/PrototypeTemplate" } }, "required": [ "removed", "template" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/instructions": { "get": { "operationId": "getV1Instructions", "summary": "The workspace-wide instructions the agent is given every turn", "tags": [ "Instructions" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "instructions": { "$ref": "#/components/schemas/Instructions" } }, "required": [ "instructions" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "setV1Instructions", "summary": "Replace the workspace-wide instructions (owner only)", "tags": [ "Instructions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "markdown": { "type": "string", "description": "Trimmed before saving. Empty removes the instructions entirely." } }, "required": [ "markdown" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "instructions": { "$ref": "#/components/schemas/Instructions" } }, "required": [ "instructions" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteV1Instructions", "summary": "Remove the workspace-wide instructions (owner only)", "tags": [ "Instructions" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "boolean" }, "instructions": { "$ref": "#/components/schemas/Instructions" } }, "required": [ "removed", "instructions" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/instructions/me": { "get": { "operationId": "getV1InstructionsMe", "summary": "Your own instructions (the id comes from the credential, never the URL)", "tags": [ "Instructions" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "instructions": { "$ref": "#/components/schemas/Instructions" } }, "required": [ "instructions" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "setV1InstructionsMe", "summary": "Replace your own instructions", "tags": [ "Instructions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "markdown": { "type": "string", "description": "Trimmed before saving. Empty removes the instructions entirely." } }, "required": [ "markdown" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "instructions": { "$ref": "#/components/schemas/Instructions" } }, "required": [ "instructions" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteV1InstructionsMe", "summary": "Remove your own instructions", "tags": [ "Instructions" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "boolean" }, "instructions": { "$ref": "#/components/schemas/Instructions" } }, "required": [ "removed", "instructions" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/instructions": { "get": { "operationId": "getV1ProjectsByProjectSlugInstructions", "summary": "This project’s instructions, given to the agent in every plan here", "tags": [ "Projects" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "instructions": { "$ref": "#/components/schemas/Instructions" } }, "required": [ "instructions" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "setV1ProjectsByProjectSlugInstructions", "summary": "Replace this project’s instructions", "tags": [ "Projects" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "markdown": { "type": "string", "description": "Trimmed before saving. Empty removes the instructions entirely." } }, "required": [ "markdown" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "instructions": { "$ref": "#/components/schemas/Instructions" } }, "required": [ "instructions" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteV1ProjectsByProjectSlugInstructions", "summary": "Remove this project’s instructions", "tags": [ "Projects" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "boolean" }, "instructions": { "$ref": "#/components/schemas/Instructions" } }, "required": [ "removed", "instructions" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}/instructions": { "get": { "operationId": "getV1ProjectsByProjectSlugPlansByPlanShortIdInstructions", "summary": "This plan’s own instructions", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "instructions": { "$ref": "#/components/schemas/Instructions" } }, "required": [ "instructions" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "setV1ProjectsByProjectSlugPlansByPlanShortIdInstructions", "summary": "Replace this plan’s instructions", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "markdown": { "type": "string", "description": "Trimmed before saving. Empty removes the instructions entirely." } }, "required": [ "markdown" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "instructions": { "$ref": "#/components/schemas/Instructions" } }, "required": [ "instructions" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "That plan is archived. Restore it before changing it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteV1ProjectsByProjectSlugPlansByPlanShortIdInstructions", "summary": "Remove this plan’s instructions", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "boolean" }, "instructions": { "$ref": "#/components/schemas/Instructions" } }, "required": [ "removed", "instructions" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "That plan is archived. Restore it before changing it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/instructions/versions": { "get": { "operationId": "getV1InstructionsVersions", "summary": "Every version of the workspace-wide instructions, newest first", "tags": [ "Instructions" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Versions per page, 1–200. Defaults to 50; values outside the range clamp." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "A `seq` from a previous page’s `nextBefore`. Returns versions older than it, so a client can walk the whole ledger without repeats." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "company", "project", "plan", "user" ] }, "versions": { "type": "array", "items": { "type": "object", "properties": { "seq": { "type": "integer", "description": "The ledger handle a restore names. Org-wide monotonic, NOT a per-document count — a document’s first version can carry a large seq, so never show this to a person." }, "version": { "type": "integer", "description": "The ordinal a person sees, counting up from the oldest version." }, "actor": { "type": "string" }, "message": { "type": "string", "nullable": true }, "op": { "type": "string", "description": "`write`, or `delete` for a version where the document was cleared." }, "createdAt": { "type": "string", "format": "date-time" }, "characters": { "type": "integer", "nullable": true, "description": "0 for a CLEARED version, which genuinely held nothing. `null` when the version exists but its body could not be read as text — deliberately distinct from 0, so a storage fault is never reported as an empty document." } }, "required": [ "seq", "version", "actor", "op", "createdAt", "characters" ] } }, "nextBefore": { "type": "integer", "nullable": true, "description": "Pass as `before` for the next page; null when this is the last one." } }, "required": [ "scope", "versions", "nextBefore" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/instructions/versions/{seq}/restore": { "post": { "operationId": "createV1InstructionsVersionsBySeqRestore", "summary": "Restore an earlier version of the workspace-wide instructions (owner only)", "tags": [ "Instructions" ], "parameters": [ { "name": "seq", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The seq." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedCurrentSeq": { "type": "integer", "description": "REQUIRED. The seq of the version you are replacing, from `GET …/versions`. If the document moved since you read it the restore is refused with 409 rather than silently overwriting the change — omitting this would make every restore a blind overwrite." } }, "required": [ "expectedCurrentSeq" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "instructions": { "$ref": "#/components/schemas/InstructionsRestored" } }, "required": [ "instructions" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "These instructions changed since you read them. `details.currentSeq` carries the version that is current now, so retry with that instead of re-reading the whole ledger.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/instructions/me/versions": { "get": { "operationId": "getV1InstructionsMeVersions", "summary": "Every version of your own instructions", "tags": [ "Instructions" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Versions per page, 1–200. Defaults to 50; values outside the range clamp." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "A `seq` from a previous page’s `nextBefore`. Returns versions older than it, so a client can walk the whole ledger without repeats." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "company", "project", "plan", "user" ] }, "versions": { "type": "array", "items": { "type": "object", "properties": { "seq": { "type": "integer", "description": "The ledger handle a restore names. Org-wide monotonic, NOT a per-document count — a document’s first version can carry a large seq, so never show this to a person." }, "version": { "type": "integer", "description": "The ordinal a person sees, counting up from the oldest version." }, "actor": { "type": "string" }, "message": { "type": "string", "nullable": true }, "op": { "type": "string", "description": "`write`, or `delete` for a version where the document was cleared." }, "createdAt": { "type": "string", "format": "date-time" }, "characters": { "type": "integer", "nullable": true, "description": "0 for a CLEARED version, which genuinely held nothing. `null` when the version exists but its body could not be read as text — deliberately distinct from 0, so a storage fault is never reported as an empty document." } }, "required": [ "seq", "version", "actor", "op", "createdAt", "characters" ] } }, "nextBefore": { "type": "integer", "nullable": true, "description": "Pass as `before` for the next page; null when this is the last one." } }, "required": [ "scope", "versions", "nextBefore" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/instructions/me/versions/{seq}/restore": { "post": { "operationId": "createV1InstructionsMeVersionsBySeqRestore", "summary": "Restore an earlier version of your own instructions", "tags": [ "Instructions" ], "parameters": [ { "name": "seq", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The seq." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedCurrentSeq": { "type": "integer", "description": "REQUIRED. The seq of the version you are replacing, from `GET …/versions`. If the document moved since you read it the restore is refused with 409 rather than silently overwriting the change — omitting this would make every restore a blind overwrite." } }, "required": [ "expectedCurrentSeq" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "instructions": { "$ref": "#/components/schemas/InstructionsRestored" } }, "required": [ "instructions" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "These instructions changed since you read them. `details.currentSeq` carries the version that is current now, so retry with that instead of re-reading the whole ledger.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/instructions/versions": { "get": { "operationId": "getV1ProjectsByProjectSlugInstructionsVersions", "summary": "Every version of this project’s instructions", "tags": [ "Projects" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Versions per page, 1–200. Defaults to 50; values outside the range clamp." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "A `seq` from a previous page’s `nextBefore`. Returns versions older than it, so a client can walk the whole ledger without repeats." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "company", "project", "plan", "user" ] }, "versions": { "type": "array", "items": { "type": "object", "properties": { "seq": { "type": "integer", "description": "The ledger handle a restore names. Org-wide monotonic, NOT a per-document count — a document’s first version can carry a large seq, so never show this to a person." }, "version": { "type": "integer", "description": "The ordinal a person sees, counting up from the oldest version." }, "actor": { "type": "string" }, "message": { "type": "string", "nullable": true }, "op": { "type": "string", "description": "`write`, or `delete` for a version where the document was cleared." }, "createdAt": { "type": "string", "format": "date-time" }, "characters": { "type": "integer", "nullable": true, "description": "0 for a CLEARED version, which genuinely held nothing. `null` when the version exists but its body could not be read as text — deliberately distinct from 0, so a storage fault is never reported as an empty document." } }, "required": [ "seq", "version", "actor", "op", "createdAt", "characters" ] } }, "nextBefore": { "type": "integer", "nullable": true, "description": "Pass as `before` for the next page; null when this is the last one." } }, "required": [ "scope", "versions", "nextBefore" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/instructions/versions/{seq}/restore": { "post": { "operationId": "createV1ProjectsByProjectSlugInstructionsVersionsBySeqRestore", "summary": "Restore an earlier version of this project’s instructions", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "seq", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The seq." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedCurrentSeq": { "type": "integer", "description": "REQUIRED. The seq of the version you are replacing, from `GET …/versions`. If the document moved since you read it the restore is refused with 409 rather than silently overwriting the change — omitting this would make every restore a blind overwrite." } }, "required": [ "expectedCurrentSeq" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "instructions": { "$ref": "#/components/schemas/InstructionsRestored" } }, "required": [ "instructions" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "These instructions changed since you read them. `details.currentSeq` carries the version that is current now, so retry with that instead of re-reading the whole ledger.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}/instructions/versions": { "get": { "operationId": "getV1ProjectsByProjectSlugPlansByPlanShortIdInstructionsVersions", "summary": "Every version of this plan’s instructions", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Versions per page, 1–200. Defaults to 50; values outside the range clamp." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "A `seq` from a previous page’s `nextBefore`. Returns versions older than it, so a client can walk the whole ledger without repeats." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "company", "project", "plan", "user" ] }, "versions": { "type": "array", "items": { "type": "object", "properties": { "seq": { "type": "integer", "description": "The ledger handle a restore names. Org-wide monotonic, NOT a per-document count — a document’s first version can carry a large seq, so never show this to a person." }, "version": { "type": "integer", "description": "The ordinal a person sees, counting up from the oldest version." }, "actor": { "type": "string" }, "message": { "type": "string", "nullable": true }, "op": { "type": "string", "description": "`write`, or `delete` for a version where the document was cleared." }, "createdAt": { "type": "string", "format": "date-time" }, "characters": { "type": "integer", "nullable": true, "description": "0 for a CLEARED version, which genuinely held nothing. `null` when the version exists but its body could not be read as text — deliberately distinct from 0, so a storage fault is never reported as an empty document." } }, "required": [ "seq", "version", "actor", "op", "createdAt", "characters" ] } }, "nextBefore": { "type": "integer", "nullable": true, "description": "Pass as `before` for the next page; null when this is the last one." } }, "required": [ "scope", "versions", "nextBefore" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}/instructions/versions/{seq}/restore": { "post": { "operationId": "createV1ProjectsByProjectSlugPlansByPlanShortIdInstructionsVersionsBySeqRestore", "summary": "Restore an earlier version of this plan’s instructions", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." }, { "name": "seq", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The seq." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedCurrentSeq": { "type": "integer", "description": "REQUIRED. The seq of the version you are replacing, from `GET …/versions`. If the document moved since you read it the restore is refused with 409 rather than silently overwriting the change — omitting this would make every restore a blind overwrite." } }, "required": [ "expectedCurrentSeq" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "instructions": { "$ref": "#/components/schemas/InstructionsRestored" } }, "required": [ "instructions" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Either these instructions changed since you read them (retry with `details.currentSeq`), or the plan is archived — restore the plan before changing it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/invites": { "get": { "operationId": "getV1Invites", "summary": "List pending invites", "tags": [ "Workspace" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invites": { "type": "array", "items": { "$ref": "#/components/schemas/Invite" } } }, "required": [ "invites" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createV1Invites", "summary": "Invite someone to the workspace", "tags": [ "Workspace" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "role": { "type": "string", "enum": [ "MEMBER", "VIEWER" ] } }, "required": [ "email" ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invite": { "$ref": "#/components/schemas/Invite" } }, "required": [ "invite" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/invites/{inviteId}": { "delete": { "operationId": "deleteV1InvitesByInviteId", "summary": "Revoke a pending invite", "tags": [ "Workspace" ], "parameters": [ { "name": "inviteId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Invite id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean" } }, "required": [ "revoked" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/mcp-servers": { "get": { "operationId": "getV1McpServers", "summary": "List this workspace’s own MCP servers", "tags": [ "Connectors" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "servers": { "type": "array", "items": { "$ref": "#/components/schemas/McpServer" } }, "limit": { "type": "integer" } }, "required": [ "servers", "limit" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createV1McpServers", "summary": "Register an MCP server by URL", "tags": [ "Connectors" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" }, "apiKey": { "type": [ "string", "null" ] }, "description": { "type": "string" } }, "required": [ "label", "url" ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "server": { "$ref": "#/components/schemas/McpServer" }, "probe": { "type": "object", "properties": { "toolsDiscovered": { "type": "integer" }, "toolsDropped": { "type": "array", "items": { "type": "string" } } } }, "message": { "type": "string" } }, "required": [ "server" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/mcp-servers/{slug}": { "get": { "operationId": "getV1McpServersBySlug", "summary": "Get a registered MCP server", "tags": [ "Connectors" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Slug of the skill or MCP server." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "server": { "$ref": "#/components/schemas/McpServer" }, "toolset": { "type": "object", "properties": { "count": { "type": "integer" }, "discoveredAt": { "type": [ "string", "null" ] } }, "required": [ "count" ] } }, "required": [ "server", "toolset" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updateV1McpServersBySlug", "summary": "Update a registered MCP server", "tags": [ "Connectors" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Slug of the skill or MCP server." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string" }, "apiKey": { "type": [ "string", "null" ], "description": "Omit to leave it alone; null clears it." }, "tools": { "type": "object", "additionalProperties": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "access": { "type": "string", "enum": [ "read", "write" ] } } } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "server": { "$ref": "#/components/schemas/McpServer" }, "probe": { "type": "object", "properties": { "toolsDiscovered": { "type": "integer" }, "toolsDropped": { "type": "array", "items": { "type": "string" } } } } }, "required": [ "server" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteV1McpServersBySlug", "summary": "Remove a registered MCP server", "tags": [ "Connectors" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Slug of the skill or MCP server." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "boolean" }, "connectorId": { "type": "string" } }, "required": [ "removed", "connectorId" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/me": { "get": { "operationId": "getV1Me", "summary": "Who this credential is, and what it can do", "tags": [ "Identity" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id" ] }, "workspace": { "$ref": "#/components/schemas/Workspace" }, "role": { "type": [ "string", "null" ], "enum": [ "OWNER", "MEMBER", "VIEWER", null ] }, "scope": { "type": "string", "enum": [ "read", "write" ] }, "credential": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "api_key", "oauth" ] }, "id": { "type": "string" } }, "required": [ "kind", "id" ] } }, "required": [ "user", "workspace", "scope", "credential" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/members": { "get": { "operationId": "getV1Members", "summary": "List the members of this workspace", "tags": [ "Workspace" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "members": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } } }, "required": [ "members" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/members/{userId}": { "patch": { "operationId": "updateV1MembersByUserId", "summary": "Change a member’s role", "tags": [ "Workspace" ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "User id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "OWNER", "MEMBER", "VIEWER" ] } }, "required": [ "role" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "member": { "type": "object", "properties": { "userId": { "type": "string" }, "role": { "type": "string", "enum": [ "OWNER", "MEMBER", "VIEWER" ] } }, "required": [ "userId", "role" ] } }, "required": [ "member" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteV1MembersByUserId", "summary": "Remove a member (name a successor if they own plans)", "tags": [ "Workspace" ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "User id." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "successorUserId": { "type": "string", "description": "Required when the member owns plans; the removal 409s without one." } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "boolean" } }, "required": [ "removed" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/oauth-connections": { "get": { "operationId": "getV1OauthConnections", "summary": "List the apps you have connected", "tags": [ "Credentials" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connections": { "type": "array", "items": { "$ref": "#/components/schemas/OAuthConnection" } } }, "required": [ "connections" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/oauth-connections/{grantId}": { "delete": { "operationId": "deleteV1OauthConnectionsByGrantId", "summary": "Disconnect an app and kill its tokens", "tags": [ "Credentials" ], "parameters": [ { "name": "grantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "OAuth connection id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "disconnected": { "type": "boolean" } }, "required": [ "disconnected" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/openapi.json": { "get": { "operationId": "getV1OpenapiJson", "summary": "This document, describing every endpoint", "tags": [ "Spec" ], "security": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "This document." } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/usage": { "get": { "operationId": "getV1Usage", "summary": "Usage by person, role-filtered (owners see everyone)", "tags": [ "Usage" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "OWNER", "MEMBER", "VIEWER" ] }, "resetsAt": { "type": [ "string", "null" ] }, "users": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "balanceMicrocredits": { "type": "string" }, "capacityMicrocredits": { "type": "string" }, "transferableMicrocredits": { "type": "string" }, "pctUsed": { "type": "number" }, "usedDollars": { "type": [ "string", "null" ], "description": "PSM-2317 — this period's consumption as a FORMATTED en-US currency string (`$23.34`), for display only. `null` when the seat has no total (`capacityMicrocredits` is 0). Derived server-side from the microcredit fields at the same rate as `orgPool.transferableDollars`; do arithmetic on the microcredit fields instead." }, "capacityDollars": { "type": [ "string", "null" ], "description": "PSM-2317 — this period's total as a formatted currency string (`$200`, or `$100` after half was moved away). `null` alongside `usedDollars`." }, "resetsAt": { "type": [ "string", "null" ] } }, "required": [ "balanceMicrocredits", "capacityMicrocredits", "transferableMicrocredits", "pctUsed" ] } }, "orgPool": { "type": [ "object", "null" ], "properties": { "balanceMicrocredits": { "type": "string" }, "transferableMicrocredits": { "type": "string" }, "transferableDollars": { "type": "string", "description": "The movable pool as a FORMATTED en-US currency string (`$48`, `$1,234.50`), for display only — the pool is the one account with no capacity to be a share of. Do arithmetic on `transferableMicrocredits` instead; this field is derived from it server-side so the two cannot disagree about the rate." }, "nextExpiry": { "type": [ "string", "null" ] } } } }, "required": [ "role", "users" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/usage/transfer/quote": { "post": { "operationId": "createV1UsageTransferQuote", "summary": "What moving usage would do, to both people", "tags": [ "Usage" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fromUserId": { "type": [ "string", "null" ], "description": "null moves from the shared pool." }, "toUserId": { "type": [ "string", "null" ], "description": "null moves into the shared pool." }, "amountMicrocredits": { "type": "string", "description": "A positive integer, as a string. Send exactly one of this, `amountCents` or `percentOfTransferable`." }, "amountCents": { "type": "integer", "description": "PSM-2318 — a DOLLAR amount in whole usage cents (`8833` is $88.33), converted server-side at the same rate every dollar figure uses, so the caller never carries one. Send exactly one of this, `amountMicrocredits` or `percentOfTransferable`. It is a fixed amount: replaying a key with a different value is a 409." }, "percentOfTransferable": { "type": "number", "description": "A share of what the source can currently move, above 0 and up to 100, with at most one decimal. It is resolved server-side against the same figure `GET /v1/usage` reports, so the caller never re-derives it; below 100 it resolves DOWN to whole cents. Send exactly one of this, `amountCents` or `amountMicrocredits`. Quote first and commit the quote's `amountMicrocredits`: a percentage re-resolves after a partial success." }, "reason": { "type": "string", "description": "Required; it lands in the audit log." }, "operationKey": { "type": "string", "description": "Caller-supplied and stable across retries, so a lost response cannot move the usage twice. The two amount shapes replay differently, on purpose: replaying with a different `amountMicrocredits` is a 409, because a different number is a different transfer. Replaying with `percentOfTransferable` returns the transfer that key already committed (`replay: true`), because a percentage re-resolves against a balance the first attempt may already have moved — that is idempotency by INTENT rather than by value. It still requires the same two parties and the same reason; anything else is a 409." } }, "required": [ "reason", "operationKey" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "quotedAt": { "type": "string" }, "amountMicrocredits": { "type": "string", "description": "What the move resolves to, with the percentage already applied. Commit this figure, not the percentage." }, "amountCents": { "type": "integer", "description": "PSM-2318 — the same amount in whole usage cents, floored." }, "amountDollars": { "type": "string", "description": "PSM-2318 — the same amount as a formatted currency string (`$88.33`). Display only." }, "maxMicrocredits": { "type": "string", "description": "PSM-2318 — the most this source can move to THIS destination right now: it excludes usage a running plan reserved and, toward the shared pool, monthly usage. An amount above it comes back as a refusal naming it in dollars." }, "maxDollars": { "type": "string", "description": "PSM-2318 — the same ceiling, formatted (`$176.66`)." }, "from": { "type": "object", "properties": { "userId": { "type": [ "string", "null" ] }, "pctUsedBefore": { "type": "number" }, "pctUsedAfter": { "type": "number" }, "balanceBeforeMicrocredits": { "type": "string" }, "balanceAfterMicrocredits": { "type": "string" }, "capacityBeforeMicrocredits": { "type": "string" }, "capacityAfterMicrocredits": { "type": "string" }, "transferableMicrocredits": { "type": "string" }, "leftDollarsBefore": { "type": "string", "description": "PSM-2318 — what this side has left before the move, as a formatted currency string with two decimals (`$176.66`). Display only; a shortfall reads `$0.00`." }, "leftDollarsAfter": { "type": "string", "description": "PSM-2318 — …and after it (`$88.33`)." } }, "required": [ "pctUsedBefore", "pctUsedAfter" ] }, "to": { "type": "object", "properties": { "userId": { "type": [ "string", "null" ] }, "pctUsedBefore": { "type": "number" }, "pctUsedAfter": { "type": "number" }, "balanceBeforeMicrocredits": { "type": "string" }, "balanceAfterMicrocredits": { "type": "string" }, "capacityBeforeMicrocredits": { "type": "string" }, "capacityAfterMicrocredits": { "type": "string" }, "transferableMicrocredits": { "type": "string" }, "leftDollarsBefore": { "type": "string", "description": "PSM-2318 — what this side has left before the move, as a formatted currency string with two decimals (`$176.66`). Display only; a shortfall reads `$0.00`." }, "leftDollarsAfter": { "type": "string", "description": "PSM-2318 — …and after it (`$88.33`)." } }, "required": [ "pctUsedBefore", "pctUsedAfter" ] }, "moving": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "MONTHLY_GRANT", "PACK", "ADJUSTMENT", "PROMO" ] }, "microcredits": { "type": "string" }, "expiresAt": { "type": [ "string", "null" ], "description": "Inherited from the lot; null never expires." } }, "required": [ "kind", "microcredits" ] } }, "debtRepaidMicrocredits": { "type": "string" }, "refusal": { "type": [ "object", "null" ], "description": "Present when the move would be refused. A quote answers \"what would happen\", so a refusal is a 200 here and a 4xx only on the transfer itself.", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } }, "required": [ "quotedAt", "amountMicrocredits", "from", "to", "moving" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/usage/transfer": { "post": { "operationId": "createV1UsageTransfer", "summary": "Move usage between people, or to and from the shared pool", "tags": [ "Usage" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fromUserId": { "type": [ "string", "null" ], "description": "null moves from the shared pool." }, "toUserId": { "type": [ "string", "null" ], "description": "null moves into the shared pool." }, "amountMicrocredits": { "type": "string", "description": "A positive integer, as a string. Send exactly one of this, `amountCents` or `percentOfTransferable`." }, "amountCents": { "type": "integer", "description": "PSM-2318 — a DOLLAR amount in whole usage cents (`8833` is $88.33), converted server-side at the same rate every dollar figure uses, so the caller never carries one. Send exactly one of this, `amountMicrocredits` or `percentOfTransferable`. It is a fixed amount: replaying a key with a different value is a 409." }, "percentOfTransferable": { "type": "number", "description": "A share of what the source can currently move, above 0 and up to 100, with at most one decimal. It is resolved server-side against the same figure `GET /v1/usage` reports, so the caller never re-derives it; below 100 it resolves DOWN to whole cents. Send exactly one of this, `amountCents` or `amountMicrocredits`. Quote first and commit the quote's `amountMicrocredits`: a percentage re-resolves after a partial success." }, "reason": { "type": "string", "description": "Required; it lands in the audit log." }, "operationKey": { "type": "string", "description": "Caller-supplied and stable across retries, so a lost response cannot move the usage twice. The two amount shapes replay differently, on purpose: replaying with a different `amountMicrocredits` is a 409, because a different number is a different transfer. Replaying with `percentOfTransferable` returns the transfer that key already committed (`replay: true`), because a percentage re-resolves against a balance the first attempt may already have moved — that is idempotency by INTENT rather than by value. It still requires the same two parties and the same reason; anything else is a 409." } }, "required": [ "reason", "operationKey" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "transferId": { "type": "string" }, "movedMicrocredits": { "type": "string" }, "debtRepaidMicrocredits": { "type": "string" }, "replay": { "type": "boolean", "description": "True when this operationKey had already moved the usage." } }, "required": [ "transferId", "movedMicrocredits", "replay" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Not enough transferable usage to move, or this `operationKey` already committed a different transfer. `error.details.reason` tells them apart (`INSUFFICIENT_TRANSFERABLE`, which also carries `transferableMicrocredits`, vs `OPERATION_KEY_CONFLICT`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects": { "get": { "operationId": "getV1Projects", "summary": "List projects", "tags": [ "Projects" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "projects": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } } }, "required": [ "projects" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createV1Projects", "summary": "Create a project", "tags": [ "Projects" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "$ref": "#/components/schemas/Project" } }, "required": [ "project" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}": { "get": { "operationId": "getV1ProjectsByProjectSlug", "summary": "Get a project", "tags": [ "Projects" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "$ref": "#/components/schemas/Project" } }, "required": [ "project" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updateV1ProjectsByProjectSlug", "summary": "Rename a project", "tags": [ "Projects" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "$ref": "#/components/schemas/Project" } }, "required": [ "project" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/context": { "get": { "operationId": "getV1ProjectsByProjectSlugContext", "summary": "List the Context sources for a project", "tags": [ "Projects" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sources": { "type": "array", "items": { "$ref": "#/components/schemas/ContextSource" } } }, "required": [ "sources" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createV1ProjectsByProjectSlugContext", "summary": "Attach a Context source to a project", "tags": [ "Projects" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sourceKind": { "type": "string", "enum": [ "PASTED", "URL" ] }, "title": { "type": "string" }, "kind": { "type": "string", "description": "Defaults to `prd`." }, "description": { "type": [ "string", "null" ] }, "text": { "type": "string", "description": "Required when `sourceKind` is `PASTED`." }, "url": { "type": "string", "description": "Required when `sourceKind` is `URL`." } }, "required": [ "sourceKind", "title" ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/ContextSource" } }, "required": [ "source" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/context/upload": { "post": { "operationId": "createV1ProjectsByProjectSlugContextUpload", "summary": "Upload a file as a Context source (on_conflict: keep_both | replace | skip)", "tags": [ "Projects" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The document to upload. Accepts pdf, docx, doc, xlsx, pptx, csv, md, txt, html, svg, yaml, json, xml, xsd, xsl, png, jpg, gif, webp, mp4, mov, webm. Up to 4 MB in THIS request body; past that, mint an upload URL and send `storage_ref` instead." }, "storage_ref": { "type": "string", "description": "The reference returned by `POST …/context/upload-url`, after the bytes have been PUT to its signed URL. Send this INSTEAD of `file` for anything over 4 MB. Requires `filename`." }, "filename": { "type": "string", "description": "The original file name. Required with `storage_ref`; ignored with `file`." }, "title": { "type": "string", "description": "Defaults to the file name." }, "kind": { "type": "string" }, "description": { "type": "string" }, "folderPath": { "type": "string" }, "onConflict": { "type": "string", "enum": [ "keep_both", "replace", "skip" ], "description": "Defaults to `keep_both`. `on_conflict` is accepted as an alias." }, "expectedSourceId": { "type": "string", "format": "uuid" }, "replaceSourceId": { "type": "string", "format": "uuid", "description": "Replace THIS uploaded document with the file, whatever the file is called: its id, scope and folder are kept, its file and text are new. It must be at the scope of this route (404 otherwise, including an id from another workspace). With `onConflict=replace` and no id, the document with the same title in the folder is replaced; a 409 lists the ids when two share it." } } } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/ContextSource" } }, "required": [ "source" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "With `onConflict=replace`, more than one document in the folder has this title; the message lists their ids. Send the one to replace as `replaceSourceId`. (A `replaceSourceId` that is not an uploaded document at this scope is a 404.)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/context/upload-url": { "post": { "operationId": "createV1ProjectsByProjectSlugContextUploadUrl", "summary": "Mint a signed upload URL for a large file, then post its storage_ref", "tags": [ "Projects" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string", "description": "The original file name. Decides the type when none is sent." }, "content_type": { "type": "string", "description": "Optional. `application/octet-stream` (what curl and most SDKs send) is ignored in favour of the extension." }, "size": { "type": "integer", "description": "Bytes. Refused up front past the cap for this kind: 25 MB for a document, 2 GB for a recording." }, "duration_seconds": { "type": "number", "description": "Optional, recordings only. Refused past 2 hours before the upload starts. Re-checked against the container once the bytes land." } }, "required": [ "filename", "size" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storage_ref": { "type": "string", "description": "Post this back as `storage_ref` on the upload form once the PUT succeeds." }, "url": { "type": "string", "description": "A one-shot signed URL. PUT the raw bytes to it, with no auth header." }, "token": { "type": "string", "description": "For a client using supabase-js `uploadToSignedUrl`, which takes path + token rather than a URL." } }, "required": [ "storage_ref", "url", "token" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/context/download": { "get": { "operationId": "getV1ProjectsByProjectSlugContextDownload", "summary": "Download a project's Context as a zip archive", "tags": [ "Projects" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "folder", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only this folder and everything under it, e.g. `research/interviews`. An unknown folder is a 400." }, { "name": "only", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only these entries: comma-separated ids from the context list (documents) or the manifest (agent files). An id this scope does not own is a 400 that names it, never skipped." } ], "responses": { "200": { "description": "Success.", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/context/{sourceId}": { "get": { "operationId": "getV1ProjectsByProjectSlugContextBySourceId", "summary": "Get a Context source", "tags": [ "Projects" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Context source id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/ContextSourceDetail" } }, "required": [ "source" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteV1ProjectsByProjectSlugContextBySourceId", "summary": "Remove a Context source", "tags": [ "Projects" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Context source id." }, { "name": "expectedUpdatedAt", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Compare-and-set: a mismatch answers 409 rather than overwriting a newer edit." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/context/{sourceId}/refresh": { "post": { "operationId": "createV1ProjectsByProjectSlugContextBySourceIdRefresh", "summary": "Re-fetch a URL-backed Context source", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Context source id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/ContextSourceDetail" } }, "required": [ "source" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/context/{sourceId}/file": { "get": { "operationId": "getV1ProjectsByProjectSlugContextBySourceIdFile", "summary": "Download a Context source’s original file, byte for byte", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Context source id." } ], "responses": { "200": { "description": "Success.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/prototype-template": { "get": { "operationId": "getV1ProjectsByProjectSlugPrototypeTemplate", "summary": "The prototype template in force for this project: its own, the company’s, or the built-in", "tags": [ "Prototype template" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "template": { "$ref": "#/components/schemas/PrototypeTemplate" } }, "required": [ "template" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "setV1ProjectsByProjectSlugPrototypeTemplate", "summary": "Set this project’s prototype template; validated before it is stored", "tags": [ "Prototype template" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "html": { "type": "string", "description": "The whole template document. Validated before it is stored: no scripts, frames, forms or handlers, no assets beyond the pinned font and icons, `.ps-*` styles only, and one empty `` per required slot. A refusal is a validation error whose `details.findings` name each rule broken." } }, "required": [ "html" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "template": { "$ref": "#/components/schemas/PrototypeTemplate" } }, "required": [ "template" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteV1ProjectsByProjectSlugPrototypeTemplate", "summary": "Remove this project’s prototype template, back to the company’s or the built-in", "tags": [ "Prototype template" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "boolean" }, "template": { "$ref": "#/components/schemas/PrototypeTemplate" } }, "required": [ "removed", "template" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/formats/{kind}": { "get": { "operationId": "getV1ProjectsByProjectSlugFormatsByKind", "summary": "The format resolved for this project", "tags": [ "Projects" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "kind", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Either `spec` or `epic`." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "$ref": "#/components/schemas/Format" } }, "required": [ "format" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "setV1ProjectsByProjectSlugFormatsByKind", "summary": "Set this project’s format (owner only)", "tags": [ "Projects" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "kind", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Either `spec` or `epic`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "markdown": { "type": "string" }, "expectedRevision": { "type": [ "string", "null" ], "description": "Destination overrideRevision from GET. Null requires absence. Omission preserves legacy unconditional writes. New clients should always supply this; stale writes return 409." } }, "required": [ "markdown" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "$ref": "#/components/schemas/Format" } }, "required": [ "format" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "This format changed. Read it again before saving.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteV1ProjectsByProjectSlugFormatsByKind", "summary": "Reset this project’s format (owner only)", "tags": [ "Projects" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "kind", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Either `spec` or `epic`." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedRevision": { "type": [ "string", "null" ], "description": "Destination overrideRevision from GET. Null requires absence. Omission preserves legacy unconditional writes. New clients should always supply this; stale writes return 409." } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "boolean" }, "format": { "$ref": "#/components/schemas/Format" } }, "required": [ "removed", "format" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "This format changed. Read it again before saving.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans": { "get": { "operationId": "getV1ProjectsByProjectSlugPlans", "summary": "List the plans you can see in a project", "tags": [ "Projects" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Exact match on the lifecycle status." }, { "name": "roots", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pass `true` for top-level plans only." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "plans": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } } }, "required": [ "plans" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createV1ProjectsByProjectSlugPlans", "summary": "Create a plan, or a sub-plan under an existing one", "tags": [ "Projects" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "parent": { "type": [ "string", "null" ], "description": "A `PLAN-n` handle or a uuid; creates a sub-plan." }, "idea": { "type": "string", "description": "The business requirement to plan from." } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "$ref": "#/components/schemas/Plan" } }, "required": [ "plan" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}": { "get": { "operationId": "getV1ProjectsByProjectSlugPlansByPlanShortId", "summary": "Get a plan and its epic", "tags": [ "Projects" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "$ref": "#/components/schemas/Plan" }, "epic": { "type": "object", "properties": { "own": { "type": [ "string", "null" ] } } } }, "required": [ "plan", "epic" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updateV1ProjectsByProjectSlugPlansByPlanShortId", "summary": "Rename, re-parent, or move a plan through its lifecycle", "tags": [ "Projects" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string", "enum": [ "PLANNING", "READY", "PUSHED", "BUILDING", "DONE" ] }, "parent": { "type": [ "string", "null" ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "$ref": "#/components/schemas/Plan" } }, "required": [ "plan" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteV1ProjectsByProjectSlugPlansByPlanShortId", "summary": "Delete a plan", "tags": [ "Projects" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "shortId": { "type": [ "string", "null" ] } }, "required": [ "deleted" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}/context": { "get": { "operationId": "getV1ProjectsByProjectSlugPlansByPlanShortIdContext", "summary": "List the Context sources for a plan", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sources": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/ContextSource" }, { "type": "object", "properties": { "active": { "type": "boolean", "description": "Whether this source is in play for the plan." } } } ] } } }, "required": [ "sources" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createV1ProjectsByProjectSlugPlansByPlanShortIdContext", "summary": "Attach a Context source to a plan", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sourceKind": { "type": "string", "enum": [ "PASTED", "URL" ] }, "title": { "type": "string" }, "kind": { "type": "string", "description": "Defaults to `prd`." }, "description": { "type": [ "string", "null" ] }, "text": { "type": "string", "description": "Required when `sourceKind` is `PASTED`." }, "url": { "type": "string", "description": "Required when `sourceKind` is `URL`." } }, "required": [ "sourceKind", "title" ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/ContextSource" } }, "required": [ "source" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}/context/upload": { "post": { "operationId": "createV1ProjectsByProjectSlugPlansByPlanShortIdContextUpload", "summary": "Upload a file as a Context source (on_conflict: keep_both | replace | skip)", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The document to upload. Accepts pdf, docx, doc, xlsx, pptx, csv, md, txt, html, svg, yaml, json, xml, xsd, xsl, png, jpg, gif, webp, mp4, mov, webm. Up to 4 MB in THIS request body; past that, mint an upload URL and send `storage_ref` instead." }, "storage_ref": { "type": "string", "description": "The reference returned by `POST …/context/upload-url`, after the bytes have been PUT to its signed URL. Send this INSTEAD of `file` for anything over 4 MB. Requires `filename`." }, "filename": { "type": "string", "description": "The original file name. Required with `storage_ref`; ignored with `file`." }, "title": { "type": "string", "description": "Defaults to the file name." }, "kind": { "type": "string" }, "description": { "type": "string" }, "folderPath": { "type": "string" }, "onConflict": { "type": "string", "enum": [ "keep_both", "replace", "skip" ], "description": "Defaults to `keep_both`. `on_conflict` is accepted as an alias." }, "expectedSourceId": { "type": "string", "format": "uuid" }, "replaceSourceId": { "type": "string", "format": "uuid", "description": "Replace THIS uploaded document with the file, whatever the file is called: its id, scope and folder are kept, its file and text are new. It must be at the scope of this route (404 otherwise, including an id from another workspace). With `onConflict=replace` and no id, the document with the same title in the folder is replaced; a 409 lists the ids when two share it." } } } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/ContextSource" } }, "required": [ "source" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "With `onConflict=replace`, more than one document in the folder has this title; the message lists their ids. Send the one to replace as `replaceSourceId`. (A `replaceSourceId` that is not an uploaded document at this scope is a 404.)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}/context/upload-url": { "post": { "operationId": "createV1ProjectsByProjectSlugPlansByPlanShortIdContextUploadUrl", "summary": "Mint a signed upload URL for a large file, then post its storage_ref", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string", "description": "The original file name. Decides the type when none is sent." }, "content_type": { "type": "string", "description": "Optional. `application/octet-stream` (what curl and most SDKs send) is ignored in favour of the extension." }, "size": { "type": "integer", "description": "Bytes. Refused up front past the cap for this kind: 25 MB for a document, 2 GB for a recording." }, "duration_seconds": { "type": "number", "description": "Optional, recordings only. Refused past 2 hours before the upload starts. Re-checked against the container once the bytes land." } }, "required": [ "filename", "size" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storage_ref": { "type": "string", "description": "Post this back as `storage_ref` on the upload form once the PUT succeeds." }, "url": { "type": "string", "description": "A one-shot signed URL. PUT the raw bytes to it, with no auth header." }, "token": { "type": "string", "description": "For a client using supabase-js `uploadToSignedUrl`, which takes path + token rather than a URL." } }, "required": [ "storage_ref", "url", "token" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}/context/copy": { "post": { "operationId": "createV1ProjectsByProjectSlugPlansByPlanShortIdContextCopy", "summary": "Copy another plan's own Context onto this plan", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "description": "The plan to copy from — a handle like `PLAN-1`, or its id. Same project." }, "dryRun": { "type": "boolean", "description": "Report what would be copied and write nothing. Defaults to false." } }, "required": [ "from" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "copied": { "type": "integer", "description": "Documents copied. Always 0 on a dry run." }, "wouldCopy": { "type": "integer", "description": "Dry run only: the documents a real run would copy." }, "skipped": { "type": "integer", "description": "Documents already present on the destination." }, "files": { "type": "integer", "description": "Workspace files copied — both the plan’s `context/` tree and the images and documents imported under `attachments/`. Always 0 on a dry run." }, "wouldCopyFiles": { "type": "integer", "description": "Dry run only: the workspace files a real run would copy." }, "fileFolders": { "type": "integer", "description": "Folders holding those files, empty ones included." }, "skippedFiles": { "type": "integer", "description": "Workspace files already byte-identical on the destination." }, "failed": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "error": { "type": "string" } }, "required": [ "title", "error" ] }, "description": "Entries that could not be copied — a document title, or a workspace file’s path relative to the plan root (prefixed `context/` or `attachments/`). The rest still were. On a dry run, entries a real run would refuse." }, "folders": { "type": "integer", "description": "Folders holding the copied documents." }, "bytes": { "type": "integer", "description": "Total extracted-text length of what was copied." }, "dryRun": { "type": "boolean" } }, "required": [ "copied", "files", "fileFolders", "skipped", "skippedFiles", "failed", "folders", "dryRun" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}/context/download": { "get": { "operationId": "getV1ProjectsByProjectSlugPlansByPlanShortIdContextDownload", "summary": "Download a plan's Context as a zip archive", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." }, { "name": "folder", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only this folder and everything under it, e.g. `research/interviews`. An unknown folder is a 400." }, { "name": "only", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only these entries: comma-separated ids from the context list (documents) or the manifest (agent files). An id this scope does not own is a 400 that names it, never skipped." } ], "responses": { "200": { "description": "Success.", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}/context/{sourceId}": { "get": { "operationId": "getV1ProjectsByProjectSlugPlansByPlanShortIdContextBySourceId", "summary": "Get a Context source", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." }, { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Context source id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/ContextSourceDetail" } }, "required": [ "source" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteV1ProjectsByProjectSlugPlansByPlanShortIdContextBySourceId", "summary": "Remove a Context source", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." }, { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Context source id." }, { "name": "expectedUpdatedAt", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Compare-and-set: a mismatch answers 409 rather than overwriting a newer edit." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}/context/{sourceId}/refresh": { "post": { "operationId": "createV1ProjectsByProjectSlugPlansByPlanShortIdContextBySourceIdRefresh", "summary": "Re-fetch a URL-backed Context source", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." }, { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Context source id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/ContextSourceDetail" } }, "required": [ "source" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}/context/{sourceId}/file": { "get": { "operationId": "getV1ProjectsByProjectSlugPlansByPlanShortIdContextBySourceIdFile", "summary": "Download a Context source’s original file, byte for byte", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." }, { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Context source id." } ], "responses": { "200": { "description": "Success.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}/dependencies": { "post": { "operationId": "createV1ProjectsByProjectSlugPlansByPlanShortIdDependencies", "summary": "Add a needs-first edge between plans", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "description": "A `SPEC-n` handle, or a linked spec’s tracker key (`SIT-123`). Defaults to the plan itself." }, "needsFirst": { "type": "string", "description": "`PLAN-3`, `PLAN-3/SPEC-2`, or a linked spec’s tracker key (`SIT-123`)." } }, "required": [ "needsFirst" ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dependency": { "$ref": "#/components/schemas/Dependency" } }, "required": [ "dependency" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}/dependencies/{edgeId}": { "delete": { "operationId": "deleteV1ProjectsByProjectSlugPlansByPlanShortIdDependenciesByEdgeId", "summary": "Remove a needs-first edge", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." }, { "name": "edgeId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Dependency edge id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "id": { "type": "string" } }, "required": [ "deleted", "id" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}/epic": { "get": { "operationId": "getV1ProjectsByProjectSlugPlansByPlanShortIdEpic", "summary": "Read a plan’s epic", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "epic": { "type": [ "string", "null" ] }, "revision": { "type": [ "string", "null" ], "description": "A hash of the epic’s body: the same value the pull index carries for it. Send it back as `expectedRevision` on a PUT or an image append. Null when the plan has no epic." } } } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "setV1ProjectsByProjectSlugPlansByPlanShortIdEpic", "summary": "Replace a plan’s epic", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string" }, "expectedRevision": { "type": "string", "description": "The `revision` from your last read. The write lands only if the epic is unchanged since; otherwise 409 `SPEC_SAVE_CONFLICT`. An `updatedAt` timestamp from an older client is still accepted." } }, "required": [ "content" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "epic": { "type": "string" }, "bytes": { "type": "integer" }, "revision": { "type": [ "string", "null" ], "description": "The epic’s new revision: send it as `expectedRevision` on your next write." } }, "required": [ "epic", "bytes", "revision" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The epic changed since the `expectedRevision` you sent, and nothing was written (`details.code` `SPEC_SAVE_CONFLICT`). Read it again and apply your edit to the new version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}/images": { "post": { "operationId": "createV1ProjectsByProjectSlugPlansByPlanShortIdImages", "summary": "Add an image to a plan, optionally appended to a spec or the epic", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "A PNG, JPEG, GIF or WebP image, up to 4 MB in THIS request body; past that, mint an upload URL and send `storage_ref` instead (images go to 10 MB)." }, "storage_ref": { "type": "string", "description": "The reference returned by `POST …/images/upload-url`, after the bytes have been PUT to its signed URL. Send `filename` and `content_type` with it." }, "filename": { "type": "string", "description": "With `storage_ref`: the file name, used for the alt text and, when `content_type` is absent, the image type. Defaults to `image`." }, "content_type": { "type": "string", "description": "With `storage_ref`: the image type you declared when minting the upload URL. The bytes are checked either way." }, "url": { "type": "string", "description": "A public https image URL, fetched by the server (no redirects, 8 MB max, private addresses refused)." }, "attachmentId": { "type": "string", "format": "uuid", "description": "An image already on this plan: the retry after a 409, so the image is not uploaded twice." }, "alt": { "type": "string", "description": "Alt text. Defaults to the file name." }, "spec": { "type": "string", "description": "A `SPEC-n` handle: append the image to the end of this spec." }, "epic": { "type": "boolean", "description": "Append the image to the end of the plan’s epic." }, "expectedRevision": { "type": "string", "description": "With `spec` or `epic`: the `revision` from your last read of that spec or epic. The append always compares against the revision it read; this lets you pin yours. An `updatedAt` timestamp from an older client is still accepted." } } } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "attachmentId": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "markdown": { "type": "string", "description": "The `![alt](url)` to place in any document of this plan." }, "appendedTo": { "type": [ "string", "null" ], "description": "`SPEC-n`, `epic`, or null when nothing was appended." }, "revision": { "type": [ "string", "null" ], "description": "The document’s new revision after an append, the value a read now returns: send it as `expectedRevision` on your next write." } }, "required": [ "attachmentId", "url", "markdown", "appendedTo", "revision" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The spec or epic changed since you read it, and nothing was appended (`details.code` `SPEC_SAVE_CONFLICT`). The image IS stored: retry with `attachmentId` from `details` and the `details.currentRevision`, so it is not uploaded twice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The image is over 10 MB (8 MB for a fetched `url`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Not a PNG, JPEG, GIF or WebP image (the bytes are checked, whatever the name or type says), or the `url` could not be fetched.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}/images/upload-url": { "post": { "operationId": "createV1ProjectsByProjectSlugPlansByPlanShortIdImagesUploadUrl", "summary": "Mint a signed upload URL for an image over 4 MB, then post its storage_ref", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string" }, "contentType": { "type": "string", "description": "`content_type` is accepted as an alias." }, "size": { "type": "integer", "description": "Bytes. Refused above 10 MB before any upload." } }, "required": [ "filename", "size" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "PUT the bytes here (raw body, `content-type` set)." }, "storageRef": { "type": "string", "description": "Post this to `…/images` as `storage_ref`." }, "storage_ref": { "type": "string", "description": "The same value as `storageRef`." } }, "required": [ "url", "storageRef", "storage_ref" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The declared `size` is over 10 MB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The declared type is not a PNG, JPEG, GIF or WebP image.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}/export": { "get": { "operationId": "getV1ProjectsByProjectSlugPlansByPlanShortIdExport", "summary": "Export a plan as markdown, CSV, JSON, or the pull index", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "md", "markdown", "csv", "json", "index" ] }, "description": "Defaults to `md`. Markdown and CSV come back as a file download. `index` is what `plansmith plan pull` saves: every spec with its content, a `revision` hash of what it writes, its acceptance criteria as data (`id`, `text`, `checked`, and `body`, the lines under the criterion) and its heading `outline`; plus the epic and a plan `revision`. `format` in the answer names the shape (`plansmith.plan-pull/1`)." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "specs": { "type": "array", "items": { "$ref": "#/components/schemas/Spec" } } }, "required": [ "name", "specs" ] }, { "$ref": "#/components/schemas/PlanPullIndex" } ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}/prototype": { "get": { "operationId": "getV1ProjectsByProjectSlugPlansByPlanShortIdPrototype", "summary": "Get the plan’s clickable prototype", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." }, { "name": "html", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pass `1` to download the rendered HTML instead." }, { "name": "standalone", "in": "query", "required": false, "schema": { "type": "string" }, "description": "With `html=1`, pass `1` for a page that is safe to open on its own: the prototype runs inside the same sandbox the app uses. Without `html=1` it is a 400." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prototype": { "type": [ "object", "null" ], "properties": { "status": { "type": "string" }, "specsFingerprint": { "type": [ "string", "null" ] }, "stale": { "type": "boolean" }, "htmlBytes": { "type": "integer" }, "tooLarge": { "type": "boolean" }, "path": { "type": "string" }, "updatedAt": { "type": "string" } } } } } } } }, "400": { "description": "`standalone=1` was sent without `html=1`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The prototype is larger than the preview limit, so `html=1` will not serve it. The metadata answer (no `html` parameter) still reports its size. With `standalone=1` the page around the prototype counts too, so a document just under the limit can be refused there.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}/prototype/reassemble": { "post": { "operationId": "createV1ProjectsByProjectSlugPlansByPlanShortIdPrototypeReassemble", "summary": "Rebuild the prototype from its screen sources with the template now in force", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prototype": { "type": "object", "properties": { "status": { "type": "string" }, "specsFingerprint": { "type": [ "string", "null" ] }, "path": { "type": "string" }, "htmlBytes": { "type": "integer" }, "screens": { "type": "integer" }, "templateTier": { "type": "string", "enum": [ "built-in", "company", "project" ] }, "updatedAt": { "type": "string" } }, "required": [ "status", "path", "htmlBytes", "screens", "templateTier" ] } }, "required": [ "prototype" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Either the prototype was built before screen sources existed and cannot be rebuilt (details.code `no_sources`; ask the agent to regenerate it), it changed while being rebuilt because a save landed (details.code `prototype_changed`; refresh and retry), or the planning agent is working on the plan (details.code `agent_working`; retry when its turn finishes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}/prototype/comments": { "get": { "operationId": "getV1ProjectsByProjectSlugPlansByPlanShortIdPrototypeComments", "summary": "List prototype comments", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Scope to one prototype file." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "author_name": { "type": "string" }, "body": { "type": "string" }, "created_at": { "type": "string" }, "anchor": { "type": "object", "description": "Omitted when the comment is unanchored." }, "resolved_at": { "type": "string", "description": "Omitted while the comment is open." }, "resolved_by": { "type": "string" }, "author_email": { "type": "string" } }, "required": [ "id", "author_name", "body", "created_at" ] } }, "contentHash": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ] } }, "required": [ "comments" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createV1ProjectsByProjectSlugPlansByPlanShortIdPrototypeComments", "summary": "Add a prototype comment", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string" }, "path": { "type": "string" } }, "required": [ "body" ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "object", "properties": { "id": { "type": "string" }, "author_name": { "type": "string" }, "body": { "type": "string" }, "created_at": { "type": "string" }, "anchor": { "type": "object", "description": "Omitted when the comment is unanchored." }, "resolved_at": { "type": "string", "description": "Omitted while the comment is open." }, "resolved_by": { "type": "string" }, "author_email": { "type": "string" } }, "required": [ "id", "author_name", "body", "created_at" ] } }, "required": [ "comment" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}/prototype/comments/{commentId}": { "patch": { "operationId": "updateV1ProjectsByProjectSlugPlansByPlanShortIdPrototypeCommentsByCommentId", "summary": "Resolve or reopen a comment", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Prototype comment id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "resolved": { "type": "boolean" } }, "required": [ "resolved" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "object", "properties": { "id": { "type": "string" }, "author_name": { "type": "string" }, "body": { "type": "string" }, "created_at": { "type": "string" }, "anchor": { "type": "object", "description": "Omitted when the comment is unanchored." }, "resolved_at": { "type": "string", "description": "Omitted while the comment is open." }, "resolved_by": { "type": "string" }, "author_email": { "type": "string" } }, "required": [ "id", "author_name", "body", "created_at" ] } }, "required": [ "comment" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteV1ProjectsByProjectSlugPlansByPlanShortIdPrototypeCommentsByCommentId", "summary": "Delete a comment", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Prototype comment id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "commentId": { "type": "string" } }, "required": [ "deleted", "commentId" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}/prototype/shares": { "get": { "operationId": "getV1ProjectsByProjectSlugPlansByPlanShortIdPrototypeShares", "summary": "List live public links for this prototype", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "shares": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": [ "string", "null" ] }, "token": { "type": [ "string", "null" ], "description": "Null unless you own the plan and the link is live." }, "url": { "type": [ "string", "null" ] }, "expiresAt": { "type": [ "string", "null" ] }, "revoked": { "type": "boolean" }, "live": { "type": "boolean" } }, "required": [ "revoked", "live" ] } } }, "required": [ "shares" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createV1ProjectsByProjectSlugPlansByPlanShortIdPrototypeShares", "summary": "Mint or rotate a public link (owner only)", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": [ "string", "null" ], "description": "An `.html` under the plan’s specs root." }, "expiresAt": { "type": [ "string", "null" ] } } } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "share": { "type": "object", "properties": { "path": { "type": [ "string", "null" ] }, "token": { "type": [ "string", "null" ], "description": "Null unless you own the plan and the link is live." }, "url": { "type": [ "string", "null" ] }, "expiresAt": { "type": [ "string", "null" ] }, "revoked": { "type": "boolean" }, "live": { "type": "boolean" } }, "required": [ "revoked", "live" ] } }, "required": [ "share" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteV1ProjectsByProjectSlugPlansByPlanShortIdPrototypeShares", "summary": "Revoke every public link for this plan", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "integer", "description": "How many links were killed." } }, "required": [ "revoked" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}/push": { "post": { "operationId": "createV1ProjectsByProjectSlugPlansByPlanShortIdPush", "summary": "Push a plan and its Specs to the connected tracker", "description": "The response carries `push.belowReady`: every spec in the plan that is still below Ready, with its readiness label and why. It is `[]` for a plan where everything is Ready, and `push.belowReadyUnavailable` is true when the check could not run (which `[]` alone cannot tell you). Long plans list the first 10 and report the rest as `push.belowReadyOmitted`. Pushing is never blocked by any of it.", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "linear", "jira", "radial" ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "push": { "type": "object", "properties": { "status": { "type": "string", "const": "pushed" }, "provider": { "type": "string", "enum": [ "linear", "jira", "radial" ] }, "planShortId": { "type": [ "string", "null" ] }, "planName": { "type": "string" }, "projectExternalId": { "type": "string" }, "pushedItemCount": { "type": "integer" }, "dependencyCount": { "type": "integer" }, "containerCount": { "type": "integer" }, "planEdgeCount": { "type": "integer" }, "ancestorNames": { "type": "array", "items": { "type": "string" } }, "caveats": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "belowReady": { "type": "array", "items": { "type": "object", "properties": { "specShortId": { "type": "string" }, "title": { "type": "string" }, "readinessLabel": { "type": "string", "enum": [ "Rough", "Shaping", "Ready" ] }, "reasons": { "type": "array", "items": { "type": "string" } }, "held": { "type": "boolean" } }, "required": [ "specShortId", "readinessLabel", "reasons" ] } }, "belowReadyOmitted": { "type": "integer" }, "belowReadyUnavailable": { "type": "boolean" } }, "required": [ "status", "provider", "planName", "pushedItemCount", "belowReady" ] } }, "required": [ "push" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Nothing was pushed. Either an issue changed in the tracker since the last push (`check_in_drift`, with `details.conflicts`), or the check could not run (`check_in_scan_failed`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}/push/status": { "get": { "operationId": "getV1ProjectsByProjectSlugPlansByPlanShortIdPushStatus", "summary": "What has been pushed, and what changed since", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." }, { "name": "spec", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Narrow to one `SPEC-n`, or the tracker key of a linked spec (`SIT-123`)." }, { "name": "provider", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Ask about one destination." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/PushStatus" } }, "required": [ "status" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}/sharing": { "get": { "operationId": "getV1ProjectsByProjectSlugPlansByPlanShortIdSharing", "summary": "Who this plan is shared with (owner only)", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sharing": { "type": "object", "properties": { "rootPlanId": { "type": "string" }, "planName": { "type": "string" }, "rootPlanName": { "type": "string" }, "rootPlanShortId": { "type": [ "string", "null" ], "description": "The root’s `PLAN-n`, when it has one. Null on a root plan." }, "isSubPlan": { "type": "boolean", "description": "Resolved on the server. ! Do not re-derive it: `rootPlanId` is a UUID, so comparing it to a `PLAN-n` handle reports every plan as a sub-plan." }, "subPlanCount": { "type": [ "integer", "null" ], "description": "ACTIVE descendants, root excluded. Null when the read failed — never 0, which would claim a size." }, "scopeNote": { "type": "string", "description": "Which plan this change lands on. Absent only when the post-mutation read failed." }, "visibility": { "type": "string", "enum": [ "PRIVATE", "TEAM" ] }, "capability": { "type": "string", "enum": [ "READ", "EDIT", "OWN" ] }, "canManage": { "type": "boolean" }, "owner": { "type": "object", "properties": { "userId": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } } }, "collaborators": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "role": { "type": "string", "enum": [ "VIEWER", "EDITOR" ] }, "orgRole": { "type": [ "string", "null" ] }, "isPlatformAdmin": { "type": "boolean" } }, "required": [ "userId", "role", "isPlatformAdmin" ] } }, "publicLinkCount": { "oneOf": [ { "type": "integer" }, { "type": "string", "const": "unknown" } ], "description": "A failed read reports `\"unknown\"`, never 0 — 0 would claim exclusivity it cannot prove." } }, "required": [ "rootPlanId", "planName", "rootPlanName", "isSubPlan", "visibility", "capability", "canManage", "collaborators" ] } }, "required": [ "sharing" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}/sharing/collaborators": { "get": { "operationId": "getV1ProjectsByProjectSlugPlansByPlanShortIdSharingCollaborators", "summary": "List collaborators (owner only)", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rootPlanId": { "type": "string" }, "owner": { "type": "object", "properties": { "userId": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } } }, "collaborators": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "role": { "type": "string", "enum": [ "VIEWER", "EDITOR" ] }, "orgRole": { "type": [ "string", "null" ] }, "isPlatformAdmin": { "type": "boolean" } }, "required": [ "userId", "role", "isPlatformAdmin" ] } } }, "required": [ "rootPlanId", "collaborators" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createV1ProjectsByProjectSlugPlansByPlanShortIdSharingCollaborators", "summary": "Share a plan with a workspace member", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "VIEWER", "EDITOR" ] } }, "required": [ "role" ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "collaborator": { "type": "object", "properties": { "userId": { "type": "string" }, "role": { "type": "string", "enum": [ "VIEWER", "EDITOR" ] } }, "required": [ "userId", "role" ] }, "rootPlanId": { "type": "string" }, "scopeNote": { "type": "string", "description": "Which plan this change lands on. Absent only when the post-mutation read failed." } }, "required": [ "collaborator", "rootPlanId" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}/sharing/collaborators/{userId}": { "patch": { "operationId": "updateV1ProjectsByProjectSlugPlansByPlanShortIdSharingCollaboratorsByUserId", "summary": "Change a collaborator’s role", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "User id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "VIEWER", "EDITOR" ] } }, "required": [ "role" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "collaborator": { "type": "object", "properties": { "userId": { "type": "string" }, "role": { "type": "string", "enum": [ "VIEWER", "EDITOR" ] } }, "required": [ "userId", "role" ] }, "rootPlanId": { "type": "string" }, "scopeNote": { "type": "string", "description": "Which plan this change lands on. Absent only when the post-mutation read failed." } }, "required": [ "collaborator", "rootPlanId" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteV1ProjectsByProjectSlugPlansByPlanShortIdSharingCollaboratorsByUserId", "summary": "Remove a collaborator", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "User id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "boolean" }, "userId": { "type": "string" }, "rootPlanId": { "type": "string" }, "scopeNote": { "type": "string", "description": "Which plan this change lands on. Absent only when the post-mutation read failed." } }, "required": [ "removed", "userId" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}/sharing/visibility": { "put": { "operationId": "setV1ProjectsByProjectSlugPlansByPlanShortIdSharingVisibility", "summary": "Make a plan private or visible to the whole workspace", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "PRIVATE", "TEAM" ] } }, "required": [ "visibility" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "type": "object", "properties": { "id": { "type": "string" }, "shortId": { "type": [ "string", "null" ] }, "visibility": { "type": "string", "enum": [ "PRIVATE", "TEAM" ] } }, "required": [ "id", "visibility" ] }, "rootPlanId": { "type": "string" }, "publicLinkCount": { "oneOf": [ { "type": "integer" }, { "type": "string", "const": "unknown" } ], "description": "A failed read reports `\"unknown\"`, never 0 — 0 would claim exclusivity it cannot prove." }, "publicLinkWarning": { "type": [ "string", "null" ], "description": "Set when live prototype links survive a switch to PRIVATE." }, "scopeNote": { "type": "string", "description": "Which plan this change lands on. Absent only when the post-mutation read failed." } }, "required": [ "plan", "rootPlanId" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}/specs": { "post": { "operationId": "createV1ProjectsByProjectSlugPlansByPlanShortIdSpecs", "summary": "Add a Spec to a plan", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 200 }, "content": { "type": "string" }, "effort": { "type": "integer", "minimum": 1, "maximum": 5 }, "readiness": { "type": "integer", "minimum": 1, "maximum": 5 }, "parent": { "type": [ "string", "null" ], "description": "A `SPEC-n` handle, a uuid, or a linked spec’s tracker key (`SIT-123`)." }, "needsFirst": { "type": "array", "items": { "type": "string" }, "description": "`SPEC-n` handles in this plan, or the tracker keys of linked specs in it. A key naming two specs is refused rather than guessed." } }, "required": [ "title" ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "spec": { "$ref": "#/components/schemas/Spec" } }, "required": [ "spec" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The Spec content does not match this workspace’s customized Spec format, and nothing was written. `details` carries `missingSections` (sections the chosen shape lists and the body does not have), `unknownHeadings` (headings at SECTION depth the format never lists; a sub-heading inside a listed section is that section’s structure and is kept), `shape` (the shape the body was read as, or null), `violations` (one sentence per finding, plus the shape menu) and `format` (`tier` and `path` of the copy enforced). A workspace using the Plansmith standard format is never refused: enforcement begins when a format is customized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}/specs/{specShortId}": { "get": { "operationId": "getV1ProjectsByProjectSlugPlansByPlanShortIdSpecsBySpecShortId", "summary": "Get a spec, including its numbered acceptance criteria, or one section of it", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." }, { "name": "specShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Spec handle within the plan, e.g. `SPEC-3` — or the tracker key of a linked spec, e.g. `SIT-123`." }, { "name": "section", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return one block instead of the whole spec: a handle (`OQ7`, `AC12`, or a heading’s leading id such as `RF06`), an exact heading, `lines: a-b`, or the `next` value of a previous page. Empty means the whole spec. An unknown or ambiguous section is 422 with `details.candidates`; a `next` from before the spec changed is 409." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "spec": { "$ref": "#/components/schemas/SpecWithCriteria" }, "planShortId": { "type": [ "string", "null" ] } }, "required": [ "spec" ] }, { "type": "object", "properties": { "revision": { "type": "string" }, "section": { "type": "object", "properties": { "heading": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } }, "line": { "type": "integer" }, "endLine": { "type": "integer" }, "content": { "type": "string" }, "next": { "type": [ "string", "null" ], "description": "Pass back as `section` for the next page; null on the last page." } }, "required": [ "heading", "path", "line", "endLine", "content", "next" ] } }, "required": [ "revision", "section" ] } ] } } } }, "400": { "description": "The `section` is malformed (a `lines: a-b` range outside the spec, or a `next` cursor for another spec); `details.code` `INVALID_SECTION`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The `section` cursor is from before the spec changed (`details.code` `STALE_SECTION_CURSOR`). Read the section again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "No heading or handle matches `section` (`details.code` `UNKNOWN_SECTION`), or it matches more than one (`AMBIGUOUS_SECTION`); `details.candidates` lists refs you can send instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updateV1ProjectsByProjectSlugPlansByPlanShortIdSpecsBySpecShortId", "summary": "Update a Spec", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." }, { "name": "specShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Spec handle within the plan, e.g. `SPEC-3` — or the tracker key of a linked spec, e.g. `SIT-123`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "content": { "type": "string" }, "effort": { "type": "integer", "minimum": 1, "maximum": 5 }, "readiness": { "type": "integer", "minimum": 1, "maximum": 5 }, "needsFirst": { "type": "array", "items": { "type": "string" }, "description": "`SPEC-n` handles in this plan, or the tracker keys of linked specs in it. A key naming two specs is refused rather than guessed." }, "parent": { "type": [ "string", "null" ], "description": "A `SPEC-n` handle, a uuid, or a linked spec’s tracker key (`SIT-123`)." }, "expectedRevision": { "type": "string", "description": "The spec’s `revision` from your last read (a list, the tree, this spec, or the pull index: they carry the same value). The change lands only if the spec is unchanged since; otherwise 409 `SPEC_SAVE_CONFLICT` with `details.currentRevision`, and nothing is written. An `updatedAt` timestamp from an older client is still accepted and pins the body change only." } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "spec": { "$ref": "#/components/schemas/SpecWithCriteria" }, "review_updated": { "$ref": "#/components/schemas/ReviewUpdate", "description": "Present only when this edit answered an open question or applied a finding on a spec that has a readiness review. The review file moved with the spec and the spec was re-scored (`product`), or could not be updated automatically and the reason says why (`skipped`)." } }, "required": [ "spec" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The spec changed since the `expectedRevision` you sent, and nothing was written (`details.code` `SPEC_SAVE_CONFLICT`). Read it again and apply your edit to the new version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The Spec content does not match this workspace’s customized Spec format, and nothing was written. `details` carries `missingSections` (sections the chosen shape lists and the body does not have), `unknownHeadings` (headings at SECTION depth the format never lists; a sub-heading inside a listed section is that section’s structure and is kept), `shape` (the shape the body was read as, or null), `violations` (one sentence per finding, plus the shape menu) and `format` (`tier` and `path` of the copy enforced). A workspace using the Plansmith standard format is never refused: enforcement begins when a format is customized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteV1ProjectsByProjectSlugPlansByPlanShortIdSpecsBySpecShortId", "summary": "Delete a Spec", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." }, { "name": "specShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Spec handle within the plan, e.g. `SPEC-3` — or the tracker key of a linked spec, e.g. `SIT-123`." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "shortId": { "type": "string" } }, "required": [ "deleted", "shortId" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}/specs/{specShortId}/outline": { "get": { "operationId": "getV1ProjectsByProjectSlugPlansByPlanShortIdSpecsBySpecShortIdOutline", "summary": "Get a spec’s outline: headings, open questions and criteria with their lines", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." }, { "name": "specShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Spec handle within the plan, e.g. `SPEC-3` — or the tracker key of a linked spec, e.g. `SIT-123`." }, { "name": "section", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Not accepted here: ask for the outline or for one section (`GET …/specs/{specShortId}?section=`), not both. Sending it is a 400 with `details.code` `BOTH_READ_MODES`." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "revision": { "type": "string" }, "lines": { "type": "integer" }, "headings": { "type": "array", "items": { "type": "object", "properties": { "level": { "type": "integer" }, "text": { "type": "string" }, "line": { "type": "integer" }, "endLine": { "type": "integer" }, "chars": { "type": "integer" } }, "required": [ "level", "text", "line", "endLine", "chars" ] } }, "openQuestions": { "type": "object", "properties": { "live": { "type": "array", "items": { "type": "object", "properties": { "handle": { "type": "string" }, "line": { "type": "integer" }, "text": { "type": "string" } }, "required": [ "handle", "line", "text" ] } }, "decided": { "type": "integer" } }, "required": [ "live", "decided" ] }, "acceptanceCriteria": { "type": "object", "properties": { "count": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "line": { "type": "integer" } }, "required": [ "id", "line" ] } } }, "required": [ "count", "items" ] }, "omitted": { "type": "array", "items": { "type": "string" }, "description": "Present only on an outline over its size budget: each entry names what was left out and how to read it (criterion ids first, then question wording, then headings below `##`)." } }, "required": [ "revision", "lines", "headings", "openQuestions", "acceptanceCriteria" ] } } } }, "400": { "description": "`section` was sent: ask for the outline or for one section, not both (`details.code` `BOTH_READ_MODES`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}/specs/{specShortId}/promote": { "post": { "operationId": "createV1ProjectsByProjectSlugPlansByPlanShortIdSpecsBySpecShortIdPromote", "summary": "Promote a Spec subtree into its own sub-plan", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." }, { "name": "specShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Spec handle within the plan, e.g. `SPEC-3` — or the tracker key of a linked spec, e.g. `SIT-123`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "contextSourceIds": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "$ref": "#/components/schemas/Plan" }, "specs": { "type": "array", "items": { "$ref": "#/components/schemas/Spec" } }, "shortIdMap": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Old handle to new handle, for every Spec that moved." }, "conversions": { "type": "array", "items": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "outbound", "inbound" ] }, "movedSpecShortId": { "type": "string" }, "otherSpecShortId": { "type": "string" } } } }, "detachedParent": { "type": [ "object", "null" ], "properties": { "itemId": { "type": "string" }, "formerParentItemId": { "type": "string" } } }, "movedContextSourceIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "plan", "specs", "shortIdMap" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/plans/{planShortId}/tree": { "get": { "operationId": "getV1ProjectsByProjectSlugPlansByPlanShortIdTree", "summary": "Get a plan with every Spec, sub-plan and dependency in one call", "tags": [ "Plans" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "planShortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan handle within the project, e.g. `PLAN-12`." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "$ref": "#/components/schemas/Plan" }, "specs": { "type": "array", "items": { "$ref": "#/components/schemas/Spec" } }, "subPlans": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } }, "dependencies": { "type": "array", "items": { "$ref": "#/components/schemas/Dependency" } } }, "required": [ "plan", "specs", "subPlans", "dependencies" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/skills": { "get": { "operationId": "getV1ProjectsByProjectSlugSkills", "summary": "List a project’s skills", "tags": [ "Projects" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "skills": { "type": "array", "items": { "$ref": "#/components/schemas/Skill" } } }, "required": [ "skills" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/skills/{slug}": { "get": { "operationId": "getV1ProjectsByProjectSlugSkillsBySlug", "summary": "Read a project skill", "tags": [ "Projects" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Slug of the skill or MCP server." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "skill": { "$ref": "#/components/schemas/Skill" } }, "required": [ "skill" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "setV1ProjectsByProjectSlugSkillsBySlug", "summary": "Write a project skill", "tags": [ "Projects" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Slug of the skill or MCP server." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string" }, "body": { "type": "string" }, "name": { "type": "string" }, "extends": { "type": [ "string", "null" ], "description": "Omit to keep what is stored. Send null to unwrap the skill. See the Skill schema for which built-ins can be extended." } }, "required": [ "body" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "skill": { "$ref": "#/components/schemas/Skill" } }, "required": [ "skill" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteV1ProjectsByProjectSlugSkillsBySlug", "summary": "Delete a project skill", "tags": [ "Projects" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug, e.g. `recipe-box`." }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Slug of the skill or MCP server." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "boolean" } }, "required": [ "removed" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/skills": { "get": { "operationId": "getV1Skills", "summary": "List skills (built-in and workspace)", "tags": [ "Skills" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "skills": { "type": "array", "items": { "$ref": "#/components/schemas/Skill" } } }, "required": [ "skills" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/skills/{slug}": { "get": { "operationId": "getV1SkillsBySlug", "summary": "Read a workspace skill", "tags": [ "Skills" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Slug of the skill or MCP server." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "skill": { "$ref": "#/components/schemas/Skill" } }, "required": [ "skill" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "setV1SkillsBySlug", "summary": "Write a workspace skill (owner only)", "tags": [ "Skills" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Slug of the skill or MCP server." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string" }, "body": { "type": "string" }, "name": { "type": "string" }, "extends": { "type": [ "string", "null" ], "description": "Omit to keep what is stored. Send null to unwrap the skill. See the Skill schema for which built-ins can be extended." } }, "required": [ "body" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "skill": { "$ref": "#/components/schemas/Skill" } }, "required": [ "skill" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteV1SkillsBySlug", "summary": "Delete a workspace skill (owner only)", "tags": [ "Skills" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Slug of the skill or MCP server." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "boolean" } }, "required": [ "removed" ] } } } }, "401": { "description": "An error, in the API's standard envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. A plan you do not have access to answers 404, exactly like a plan that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `Retry-After` names the seconds to wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }