{ "openapi": "3.1.0", "info": { "title": "Flare API", "version": "1", "summary": "Projects, tickets, meetings, and knowledge base — the same graph Flare agents (Arlo, Miro, Kiro) read and write.", "description": "REST API for flares.in. Every write an agent can make through MCP is also reachable here.\n\nAuthentication: `Authorization: Bearer flr_pat_...` (personal access token) or `flr_oat_...` (MCP OAuth access token). Create a PAT from Settings in the app.\n\nScopes: tokens are scoped; each operation below lists its required scope under `x-required-scope`. Full catalog:\n- `tickets:read`: List, search, and read tickets, SDK apps, members, and labels\n- `tickets:write`: Create and update tickets, link PRs, and manage labels\n- `comments:write`: Add internal or public comments on tickets\n- `evidence:read`: Download ticket evidence via signed URLs\n- `planning:read`: Read delivery projects, work items, audit logs, planning runs, clarifications, and Flare agent tasks\n- `planning:write`: Create delivery projects, plan from PRDs, manage work items (including bulk, reorder, delete), risks, decisions, and agent tasks\n- `planning:publish`: Publish reviewed delivery project plans\n- `meetings:read`: Read meetings, transcripts, artifacts, and outcomes\n- `meetings:write`: Create and update meetings, lifecycle, and proposed outcomes\n- `meetings:transcript`: Import meeting transcript text\n- `meetings:process`: Generate meeting artifacts from transcript evidence\n- `meetings:publish`: Publish meetings and materialize approved outcomes onto projects\n- `vault:read`: Search and read knowledge vault articles, health, insights, and handoffs\n- `vault:write`: Create and update vault articles, sync sources, insights, and handoffs\n- `kiro:read`: Read Kiro behavior, org profile, vault apps, and configuration\n- `kiro:write`: Update Kiro behavior, intent taxonomy, connectors, and setup\n\nPagination: list endpoints are cursor-paginated with `cursor` and `limit` query params; responses include `next_cursor` (and often `has_more`).\n\nIdempotency: send an `Idempotency-Key` header on POST/PATCH/PUT/DELETE writes to safely retry — replays return the cached response with `X-Flare-Idempotent-Replay: true`.\n\nErrors: every error is `{ error: { code, message, field_errors?, details? }, request_id }` — see the Error schema.\n\nFull docs: https://flares.in/developers · Machine-readable site summary: https://flares.in/llms.txt", "contact": { "name": "Flare", "url": "https://flares.in/developers", "email": "hello@flares.in" } }, "servers": [ { "url": "https://flares.in/api/v1", "description": "Production" } ], "tags": [ { "name": "Tickets", "description": "Customer-reported issues, from Kiro or the API." }, { "name": "Comments", "description": "Internal or public notes on a ticket." }, { "name": "Labels", "description": "Ticket labels." }, { "name": "Me", "description": "Caller identity." }, { "name": "Members", "description": "Organization membership." }, { "name": "Agents", "description": "Flare's built-in agents (Arlo, Miro-outcomes)." }, { "name": "Agent Tasks", "description": "Async agent runs — propose/execute/cancel." }, { "name": "Delivery Projects", "description": "Arlo's managed projects: specs, updates, risks, decisions." }, { "name": "Work Items", "description": "Epics, stories, tasks, and milestones inside a delivery project." }, { "name": "Planning Runs", "description": "Async PRD-to-plan generation." }, { "name": "Meetings", "description": "Miro's meetings: lifecycle, transcripts, outcomes, artifacts." }, { "name": "Meeting Agents", "description": "Per-user auto-join bot (Miro) settings." }, { "name": "Admin", "description": "Org-wide admin views. Requires an admin/owner membership role." }, { "name": "Knowledge Vault", "description": "Kiro's knowledge base: articles, search, CS insights and handoffs." }, { "name": "Kiro", "description": "Kiro behavior, connectors, and org knowledge profile." } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "flr_pat_... or flr_oat_...", "description": "Personal access token or MCP OAuth access token. See x-required-scope on each operation." } }, "schemas": { "Error": { "type": "object", "required": [ "error", "request_id" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "MISSING_TOKEN", "INVALID_TOKEN", "REVOKED", "EXPIRED", "RATE_LIMITED", "FORBIDDEN", "NOT_FOUND", "VALIDATION", "CONFLICT", "INTERNAL" ] }, "message": { "type": "string" }, "field_errors": { "type": "object", "additionalProperties": { "type": "string" } }, "details": { "type": "object", "additionalProperties": true } } }, "request_id": { "type": "string" } } } } }, "security": [ { "bearerAuth": [] } ], "paths": { "/tickets": { "get": { "summary": "List tickets", "description": "", "operationId": "listTickets", "tags": [ "Tickets" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "tickets:read", "parameters": [ { "name": "status", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "triage", "in_progress", "blocked", "resolved", "closed" ] } } }, { "name": "priority", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] } } }, { "name": "severity", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "trivial", "minor", "major", "critical", "blocker" ] } } }, { "name": "project_slug", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 } }, { "name": "assignee_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "q", "in": "query", "required": false, "description": "Free-text search over title/description.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor from a previous response.", "schema": { "type": "string", "maxLength": 500 } }, { "name": "limit", "in": "query", "required": false, "description": "Max rows to return. Default 25, max 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Page of tickets.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "triage", "in_progress", "blocked", "resolved", "closed" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "severity": { "type": "string", "enum": [ "trivial", "minor", "major", "critical", "blocker" ] }, "source": { "type": "string" }, "assignee_id": { "type": "string", "format": "uuid", "nullable": true }, "reporter_id": { "type": "string", "format": "uuid", "nullable": true }, "created_by": { "type": "string", "format": "uuid", "nullable": true }, "resolved_at": { "type": "string", "format": "date-time", "nullable": true }, "closed_at": { "type": "string", "format": "date-time", "nullable": true }, "metadata": { "type": "object", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" }, "total": { "type": "integer", "nullable": true } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a ticket", "description": "", "operationId": "createTicket", "tags": [ "Tickets" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "tickets:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Opaque client-generated key (1-200 chars). Replaying the same key for this token within 24h returns the cached response instead of re-executing the write, and sets X-Flare-Idempotent-Replay: true on the response.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "description": "Exactly one of project_id or project_slug is required.", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 10000 }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "severity": { "type": "string", "enum": [ "trivial", "minor", "major", "critical", "blocker" ] }, "type": { "type": "string", "enum": [ "bug", "feedback", "performance", "other" ] }, "project_id": { "type": "string", "format": "uuid" }, "project_slug": { "type": "string", "minLength": 1, "maxLength": 100 } } } } } }, "responses": { "201": { "description": "Created ticket.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "triage", "in_progress", "blocked", "resolved", "closed" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "severity": { "type": "string", "enum": [ "trivial", "minor", "major", "critical", "blocker" ] }, "source": { "type": "string" }, "assignee_id": { "type": "string", "format": "uuid", "nullable": true }, "reporter_id": { "type": "string", "format": "uuid", "nullable": true }, "created_by": { "type": "string", "format": "uuid", "nullable": true }, "resolved_at": { "type": "string", "format": "date-time", "nullable": true }, "closed_at": { "type": "string", "format": "date-time", "nullable": true }, "metadata": { "type": "object", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tickets/{number}": { "get": { "summary": "Get a ticket", "description": "Includes project, assignee, reporter, labels, and up to the 50 most recent comments.", "operationId": "getTicket", "tags": [ "Tickets" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "tickets:read", "parameters": [ { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Ticket with expanded relations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "triage", "in_progress", "blocked", "resolved", "closed" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "severity": { "type": "string", "enum": [ "trivial", "minor", "major", "critical", "blocker" ] }, "source": { "type": "string" }, "assignee_id": { "type": "string", "format": "uuid", "nullable": true }, "reporter_id": { "type": "string", "format": "uuid", "nullable": true }, "created_by": { "type": "string", "format": "uuid", "nullable": true }, "resolved_at": { "type": "string", "format": "date-time", "nullable": true }, "closed_at": { "type": "string", "format": "date-time", "nullable": true }, "metadata": { "type": "object", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } }, { "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "assignee": { "type": "object", "nullable": true, "additionalProperties": true }, "reporter": { "type": "object", "nullable": true, "additionalProperties": true }, "labels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string", "enum": [ "gray", "sky", "coral", "amber", "lavender", "sage", "mint", "rose" ] }, "created_at": { "type": "string", "format": "date-time" } } } }, "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "body": { "type": "string" }, "is_internal": { "type": "boolean" }, "author_id": { "type": "string", "format": "uuid", "nullable": true }, "author_type": { "type": "string", "enum": [ "member", "system", "external" ] }, "external_author_email": { "type": "string", "nullable": true }, "external_author_name": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } }, "comments_truncated_at": { "type": "integer" } } } ] } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update a ticket", "description": "", "operationId": "updateTicket", "tags": [ "Tickets" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "tickets:write", "parameters": [ { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Opaque client-generated key (1-200 chars). Replaying the same key for this token within 24h returns the cached response instead of re-executing the write, and sets X-Flare-Idempotent-Replay: true on the response.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "At least one field is required.", "properties": { "status": { "type": "string", "enum": [ "triage", "in_progress", "blocked", "resolved", "closed" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "severity": { "type": "string", "enum": [ "trivial", "minor", "major", "critical", "blocker" ] }, "assignee_id": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "string", "enum": [ "unassigned" ] }, { "type": "null" } ] }, "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 10000 }, "public_status_note": { "type": "string", "maxLength": 2000 } } } } } }, "responses": { "200": { "description": "Updated ticket.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "triage", "in_progress", "blocked", "resolved", "closed" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "severity": { "type": "string", "enum": [ "trivial", "minor", "major", "critical", "blocker" ] }, "source": { "type": "string" }, "assignee_id": { "type": "string", "format": "uuid", "nullable": true }, "reporter_id": { "type": "string", "format": "uuid", "nullable": true }, "created_by": { "type": "string", "format": "uuid", "nullable": true }, "resolved_at": { "type": "string", "format": "date-time", "nullable": true }, "closed_at": { "type": "string", "format": "date-time", "nullable": true }, "metadata": { "type": "object", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } }, { "type": "object", "properties": { "changed": { "type": "array", "items": { "type": "string" } } } } ] } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tickets/{number}/comments": { "get": { "summary": "List ticket comments", "description": "", "operationId": "listTicketComments", "tags": [ "Comments" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "tickets:read", "parameters": [ { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Max rows to return. Default 50, max 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Comments oldest-first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "body": { "type": "string" }, "is_internal": { "type": "boolean" }, "author_id": { "type": "string", "format": "uuid", "nullable": true }, "author_type": { "type": "string", "enum": [ "member", "system", "external" ] }, "external_author_email": { "type": "string", "nullable": true }, "external_author_name": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Add a ticket comment", "description": "", "operationId": "addTicketComment", "tags": [ "Comments" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "comments:write", "parameters": [ { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Opaque client-generated key (1-200 chars). Replaying the same key for this token within 24h returns the cached response instead of re-executing the write, and sets X-Flare-Idempotent-Replay: true on the response.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 10000 }, "is_internal": { "type": "boolean", "default": true } } } } } }, "responses": { "201": { "description": "Created comment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "body": { "type": "string" }, "is_internal": { "type": "boolean" }, "author_id": { "type": "string", "format": "uuid", "nullable": true }, "author_type": { "type": "string", "enum": [ "member", "system", "external" ] }, "external_author_email": { "type": "string", "nullable": true }, "external_author_name": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tickets/{number}/evidence": { "get": { "summary": "Get ticket evidence", "description": "Signed URLs (15 min TTL) for screenshots, recordings, and attachments captured with the report, plus inline console/network samples.", "operationId": "getTicketEvidence", "tags": [ "Tickets" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "evidence:read", "parameters": [ { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Evidence bundle.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ticket": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "integer" } } }, "report_id": { "type": "string", "nullable": true }, "url_at_capture": { "type": "string", "nullable": true }, "route_at_capture": { "type": "string", "nullable": true }, "user_agent": { "type": "string", "nullable": true }, "device": { "type": "object", "nullable": true, "additionalProperties": true }, "custom_metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "media": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "content_type": { "type": "string", "nullable": true }, "size_bytes": { "type": "integer", "nullable": true }, "url": { "type": "string", "format": "uri" }, "expires_in_seconds": { "type": "integer" } } } }, "console_logs": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "network_failures": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "signed_url_ttl_seconds": { "type": "integer" } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tickets/{number}/labels": { "put": { "summary": "Set ticket labels", "description": "Replaces the full label set on the ticket.", "operationId": "setTicketLabels", "tags": [ "Tickets" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "tickets:write", "parameters": [ { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Opaque client-generated key (1-200 chars). Replaying the same key for this token within 24h returns the cached response instead of re-executing the write, and sets X-Flare-Idempotent-Replay: true on the response.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "label_ids" ], "properties": { "label_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 50 } } } } } }, "responses": { "200": { "description": "Applied label set.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "number": { "type": "integer" }, "label_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tickets/{number}/link-pr": { "post": { "summary": "Link a pull request to a ticket", "description": "Closes the agentic loop: an agent that opened a PR fixing a ticket calls this to attach it and post a system comment. pr_url must be an https URL on github.com, gitlab.com, bitbucket.org, dev.azure.com, or codeberg.org.", "operationId": "linkTicketPr", "tags": [ "Tickets" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "tickets:write", "parameters": [ { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Opaque client-generated key (1-200 chars). Replaying the same key for this token within 24h returns the cached response instead of re-executing the write, and sets X-Flare-Idempotent-Replay: true on the response.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pr_url" ], "properties": { "pr_url": { "type": "string", "format": "uri", "maxLength": 2048 }, "commit_sha": { "type": "string", "minLength": 7, "maxLength": 64, "pattern": "^[0-9a-fA-F]+$" }, "summary": { "type": "string", "maxLength": 2000 } } } } } }, "responses": { "200": { "description": "Linked PR.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ticket": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "url": { "type": "string", "format": "uri" } } }, "linked_pr": { "type": "object", "properties": { "url": { "type": "string" }, "commit_sha": { "type": "string", "nullable": true }, "summary": { "type": "string", "nullable": true }, "linked_at": { "type": "string", "format": "date-time" }, "linked_by_token_id": { "type": "string" } } }, "comment_id": { "type": "string", "nullable": true } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/labels": { "get": { "summary": "List labels", "description": "", "operationId": "listLabels", "tags": [ "Labels" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "tickets:read", "responses": { "200": { "description": "Org's ticket labels.", "content": { "application/json": { "schema": { "type": "object", "properties": { "labels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string", "enum": [ "gray", "sky", "coral", "amber", "lavender", "sage", "mint", "rose" ] }, "created_at": { "type": "string", "format": "date-time" } } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a label", "description": "", "operationId": "createLabel", "tags": [ "Labels" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "tickets:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Opaque client-generated key (1-200 chars). Replaying the same key for this token within 24h returns the cached response instead of re-executing the write, and sets X-Flare-Idempotent-Replay: true on the response.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50 }, "color": { "type": "string", "enum": [ "gray", "sky", "coral", "amber", "lavender", "sage", "mint", "rose" ], "default": "gray" } } } } } }, "responses": { "201": { "description": "Created label. CONFLICT if the name is already used.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "label": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string", "enum": [ "gray", "sky", "coral", "amber", "lavender", "sage", "mint", "rose" ] }, "created_at": { "type": "string", "format": "date-time" } } } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/labels/{id}": { "delete": { "summary": "Delete a label", "description": "", "operationId": "deleteLabel", "tags": [ "Labels" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "tickets:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Opaque client-generated key (1-200 chars). Replaying the same key for this token within 24h returns the cached response instead of re-executing the write, and sets X-Flare-Idempotent-Replay: true on the response.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "label_id": { "type": "string", "format": "uuid" } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/me": { "get": { "summary": "Get the calling token, org, and workspace", "description": "", "operationId": "getMe", "tags": [ "Me" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": null, "responses": { "200": { "description": "Caller identity.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "token": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "scopes": { "type": "array", "items": { "type": "string" } }, "rate_limit_per_minute": { "type": "integer" } } }, "organization": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "workspace": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "user_id": { "type": "string", "format": "uuid" }, "server": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "flare" ] }, "api_version": { "type": "string", "enum": [ "v1" ] } } } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/members": { "get": { "summary": "List organization members", "description": "Useful for picking a valid assignee_id when updating a ticket.", "operationId": "listMembers", "tags": [ "Members" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "tickets:read", "responses": { "200": { "description": "Members.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "role": { "type": "string" }, "full_name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true } } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agents": { "get": { "summary": "List Flare's built-in agents", "description": "", "operationId": "listFlareAgents", "tags": [ "Agents" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "planning:read", "responses": { "200": { "description": "Agent catalog.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "project-planning-agent", "meeting-outcomes-agent" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "integer" }, "task_types": { "type": "array", "items": { "type": "string" } }, "inherited_project_capabilities": { "type": "array", "items": { "type": "string" } }, "write_ops": { "type": "array", "items": { "type": "string" } }, "required_read_scope": { "type": "string" }, "required_write_scope": { "type": "string" }, "safety": { "type": "object", "properties": { "default_execution_mode": { "type": "string", "enum": [ "propose" ] }, "publish_requires_explicit_permission": { "type": "boolean" }, "tenant_scoped": { "type": "boolean" } } } } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agents/{key}": { "get": { "summary": "Get a Flare agent definition", "description": "", "operationId": "getFlareAgent", "tags": [ "Agents" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "planning:read", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "project-planning-agent", "meeting-outcomes-agent" ] } } ], "responses": { "200": { "description": "Agent definition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "project-planning-agent", "meeting-outcomes-agent" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "integer" }, "task_types": { "type": "array", "items": { "type": "string" } }, "inherited_project_capabilities": { "type": "array", "items": { "type": "string" } }, "write_ops": { "type": "array", "items": { "type": "string" } }, "required_read_scope": { "type": "string" }, "required_write_scope": { "type": "string" }, "safety": { "type": "object", "properties": { "default_execution_mode": { "type": "string", "enum": [ "propose" ] }, "publish_requires_explicit_permission": { "type": "boolean" }, "tenant_scoped": { "type": "boolean" } } } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent-tasks": { "get": { "summary": "List agent tasks", "description": "", "operationId": "listAgentTasks", "tags": [ "Agent Tasks" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "planning:read", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Max rows to return. Default 25, max 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Recent tasks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "delivery_project_id": { "type": "string", "format": "uuid", "nullable": true }, "planning_run_id": { "type": "string", "format": "uuid", "nullable": true }, "agent_key": { "type": "string", "enum": [ "project-planning-agent", "meeting-outcomes-agent" ] }, "task_type": { "type": "string", "enum": [ "plan_project", "manage_project", "extract_meeting_outcomes" ] }, "execution_mode": { "type": "string", "enum": [ "propose", "execute" ] }, "project_key": { "type": "string", "nullable": true }, "command": { "type": "string" }, "allow_publish": { "type": "boolean" }, "status": { "type": "string", "enum": [ "queued", "running", "waiting", "ready_for_review", "completed", "failed", "cancelled" ] }, "progress": { "type": "number" }, "current_stage": { "type": "string", "nullable": true }, "stage_log": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "proposed_operations": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "nullable": true }, "result": { "type": "object", "additionalProperties": true, "nullable": true }, "error_message": { "type": "string", "nullable": true }, "workflow_run_id": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "status_url": { "type": "string", "format": "uri" }, "agent": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "project-planning-agent", "meeting-outcomes-agent" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "integer" }, "task_types": { "type": "array", "items": { "type": "string" } }, "inherited_project_capabilities": { "type": "array", "items": { "type": "string" } }, "write_ops": { "type": "array", "items": { "type": "string" } }, "required_read_scope": { "type": "string" }, "required_write_scope": { "type": "string" }, "safety": { "type": "object", "properties": { "default_execution_mode": { "type": "string", "enum": [ "propose" ] }, "publish_requires_explicit_permission": { "type": "boolean" }, "tenant_scoped": { "type": "boolean" } } } } } } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Assign an agent task", "description": "Queues an async run of a Flare agent (project-planning-agent or meeting-outcomes-agent). task_type 'plan_project' is rejected — use POST /planning/projects or POST /planning/runs with a prd instead. Defaults to execution_mode=propose, which stops before any writes for human/agent review via POST /agent-tasks/{id}.", "operationId": "assignAgentTask", "tags": [ "Agent Tasks" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "planning:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agent_key", "task_type", "command" ], "properties": { "agent_key": { "type": "string", "enum": [ "project-planning-agent", "meeting-outcomes-agent" ] }, "task_type": { "type": "string", "enum": [ "manage_project", "extract_meeting_outcomes" ] }, "command": { "type": "string", "minLength": 1, "maxLength": 10000 }, "project_key": { "type": "string", "description": "Required for every task_type used here." }, "execution_mode": { "type": "string", "enum": [ "propose", "execute" ], "default": "propose" }, "allow_publish": { "type": "boolean", "default": false, "description": "Only valid with execution_mode=execute, and requires the planning:publish scope." }, "name": { "type": "string", "maxLength": 120 }, "objective": { "type": "string", "maxLength": 2000 }, "prd": { "type": "string", "minLength": 40, "maxLength": 200000 }, "source_text": { "type": "string", "minLength": 20, "maxLength": 200000, "description": "Required when task_type='extract_meeting_outcomes'." }, "idempotency_key": { "type": "string", "maxLength": 160 } } } } } }, "responses": { "202": { "description": "Queued task.", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "delivery_project_id": { "type": "string", "format": "uuid", "nullable": true }, "planning_run_id": { "type": "string", "format": "uuid", "nullable": true }, "agent_key": { "type": "string", "enum": [ "project-planning-agent", "meeting-outcomes-agent" ] }, "task_type": { "type": "string", "enum": [ "plan_project", "manage_project", "extract_meeting_outcomes" ] }, "execution_mode": { "type": "string", "enum": [ "propose", "execute" ] }, "project_key": { "type": "string", "nullable": true }, "command": { "type": "string" }, "allow_publish": { "type": "boolean" }, "status": { "type": "string", "enum": [ "queued", "running", "waiting", "ready_for_review", "completed", "failed", "cancelled" ] }, "progress": { "type": "number" }, "current_stage": { "type": "string", "nullable": true }, "stage_log": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "proposed_operations": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "nullable": true }, "result": { "type": "object", "additionalProperties": true, "nullable": true }, "error_message": { "type": "string", "nullable": true }, "workflow_run_id": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "status_url": { "type": "string", "format": "uri" }, "agent": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "project-planning-agent", "meeting-outcomes-agent" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "integer" }, "task_types": { "type": "array", "items": { "type": "string" } }, "inherited_project_capabilities": { "type": "array", "items": { "type": "string" } }, "write_ops": { "type": "array", "items": { "type": "string" } }, "required_read_scope": { "type": "string" }, "required_write_scope": { "type": "string" }, "safety": { "type": "object", "properties": { "default_execution_mode": { "type": "string", "enum": [ "propose" ] }, "publish_requires_explicit_permission": { "type": "boolean" }, "tenant_scoped": { "type": "boolean" } } } } } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent-tasks/{id}": { "get": { "summary": "Get an agent task", "description": "", "operationId": "getAgentTask", "tags": [ "Agent Tasks" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "planning:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Task detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "delivery_project_id": { "type": "string", "format": "uuid", "nullable": true }, "planning_run_id": { "type": "string", "format": "uuid", "nullable": true }, "agent_key": { "type": "string", "enum": [ "project-planning-agent", "meeting-outcomes-agent" ] }, "task_type": { "type": "string", "enum": [ "plan_project", "manage_project", "extract_meeting_outcomes" ] }, "execution_mode": { "type": "string", "enum": [ "propose", "execute" ] }, "project_key": { "type": "string", "nullable": true }, "command": { "type": "string" }, "allow_publish": { "type": "boolean" }, "status": { "type": "string", "enum": [ "queued", "running", "waiting", "ready_for_review", "completed", "failed", "cancelled" ] }, "progress": { "type": "number" }, "current_stage": { "type": "string", "nullable": true }, "stage_log": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "proposed_operations": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "nullable": true }, "result": { "type": "object", "additionalProperties": true, "nullable": true }, "error_message": { "type": "string", "nullable": true }, "workflow_run_id": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "status_url": { "type": "string", "format": "uri" }, "agent": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "project-planning-agent", "meeting-outcomes-agent" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "integer" }, "task_types": { "type": "array", "items": { "type": "string" } }, "inherited_project_capabilities": { "type": "array", "items": { "type": "string" } }, "write_ops": { "type": "array", "items": { "type": "string" } }, "required_read_scope": { "type": "string" }, "required_write_scope": { "type": "string" }, "safety": { "type": "object", "properties": { "default_execution_mode": { "type": "string", "enum": [ "propose" ] }, "publish_requires_explicit_permission": { "type": "boolean" }, "tenant_scoped": { "type": "boolean" } } } } } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Act on an agent task", "description": "'execute' approves a ready_for_review task's proposed operations and runs them (FORBIDDEN if the plan publishes and allow_publish isn't set); 'cancel' cancels a non-terminal task.", "operationId": "actOnAgentTask", "tags": [ "Agent Tasks" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "planning:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "execute" ] }, "allow_publish": { "type": "boolean", "default": false } } }, { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "cancel" ] } } } ] } } } }, "responses": { "202": { "description": "Updated task.", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "delivery_project_id": { "type": "string", "format": "uuid", "nullable": true }, "planning_run_id": { "type": "string", "format": "uuid", "nullable": true }, "agent_key": { "type": "string", "enum": [ "project-planning-agent", "meeting-outcomes-agent" ] }, "task_type": { "type": "string", "enum": [ "plan_project", "manage_project", "extract_meeting_outcomes" ] }, "execution_mode": { "type": "string", "enum": [ "propose", "execute" ] }, "project_key": { "type": "string", "nullable": true }, "command": { "type": "string" }, "allow_publish": { "type": "boolean" }, "status": { "type": "string", "enum": [ "queued", "running", "waiting", "ready_for_review", "completed", "failed", "cancelled" ] }, "progress": { "type": "number" }, "current_stage": { "type": "string", "nullable": true }, "stage_log": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "proposed_operations": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "nullable": true }, "result": { "type": "object", "additionalProperties": true, "nullable": true }, "error_message": { "type": "string", "nullable": true }, "workflow_run_id": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "status_url": { "type": "string", "format": "uri" }, "agent": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "project-planning-agent", "meeting-outcomes-agent" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "integer" }, "task_types": { "type": "array", "items": { "type": "string" } }, "inherited_project_capabilities": { "type": "array", "items": { "type": "string" } }, "write_ops": { "type": "array", "items": { "type": "string" } }, "required_read_scope": { "type": "string" }, "required_write_scope": { "type": "string" }, "safety": { "type": "object", "properties": { "default_execution_mode": { "type": "string", "enum": [ "propose" ] }, "publish_requires_explicit_permission": { "type": "boolean" }, "tenant_scoped": { "type": "boolean" } } } } } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/planning/projects": { "get": { "summary": "List delivery projects", "description": "", "operationId": "listDeliveryProjects", "tags": [ "Delivery Projects" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "planning:read", "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor from a previous response.", "schema": { "type": "string", "maxLength": 500 } }, { "name": "limit", "in": "query", "required": false, "description": "Max rows to return. Default 25, max 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Page of projects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "project_key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "objective": { "type": "string" }, "status": { "type": "string" }, "health": { "type": "string", "nullable": true }, "priority": { "type": "string", "nullable": true }, "owner_id": { "type": "string", "format": "uuid", "nullable": true }, "start_date": { "type": "string", "format": "date", "nullable": true }, "target_date": { "type": "string", "format": "date", "nullable": true }, "published_at": { "type": "string", "format": "date-time", "nullable": true }, "version": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a delivery project", "description": "If prd is supplied, also starts a full PRD planning run (epics, stories, tasks, acceptance criteria, and tests) against the new project.", "operationId": "createDeliveryProject", "tags": [ "Delivery Projects" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "planning:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "project_key" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "project_key": { "type": "string", "minLength": 2, "maxLength": 10, "pattern": "^[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*$" }, "objective": { "type": "string", "maxLength": 2000, "default": "" }, "target_date": { "type": "string", "format": "date" }, "prd": { "type": "string", "minLength": 40, "maxLength": 200000 }, "dry_run": { "type": "boolean", "default": false }, "webhook_url": { "type": "string", "format": "uri", "maxLength": 2000 } } } } } }, "responses": { "201": { "description": "Created project, and a planning run if prd was given. CONFLICT if project_key is already in use.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "project_key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "objective": { "type": "string" }, "status": { "type": "string" }, "health": { "type": "string", "nullable": true }, "priority": { "type": "string", "nullable": true }, "owner_id": { "type": "string", "format": "uuid", "nullable": true }, "start_date": { "type": "string", "format": "date", "nullable": true }, "target_date": { "type": "string", "format": "date", "nullable": true }, "published_at": { "type": "string", "format": "date-time", "nullable": true }, "version": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } }, "planning": { "type": "object", "nullable": true, "properties": { "planning_run_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "current_stage": { "type": "string", "nullable": true }, "progress": { "type": "number" }, "status_url": { "type": "string", "format": "uri" }, "review_url": { "type": "string", "format": "uri" } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/planning/projects/{project_key}": { "get": { "summary": "Get a delivery project (full detail)", "description": "Project plus every related sub-resource: specs, requirements, work items, acceptance criteria, test cases, comments, dependencies, ticket links, followers, updates, risks, and decisions.", "operationId": "getDeliveryProject", "tags": [ "Delivery Projects" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "planning:read", "parameters": [ { "name": "project_key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Full project detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "project_key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "objective": { "type": "string" }, "status": { "type": "string" }, "health": { "type": "string", "nullable": true }, "priority": { "type": "string", "nullable": true }, "owner_id": { "type": "string", "format": "uuid", "nullable": true }, "start_date": { "type": "string", "format": "date", "nullable": true }, "target_date": { "type": "string", "format": "date", "nullable": true }, "published_at": { "type": "string", "format": "date-time", "nullable": true }, "version": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } }, "specs": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "requirements": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "work_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "item_type": { "type": "string", "enum": [ "epic", "story", "task", "milestone" ] }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "backlog", "ready", "in_progress", "in_review", "blocked", "done", "cancelled" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "estimate_points": { "type": "number", "nullable": true }, "owner_id": { "type": "string", "format": "uuid", "nullable": true }, "start_date": { "type": "string", "format": "date", "nullable": true }, "due_date": { "type": "string", "format": "date", "nullable": true }, "cycle_id": { "type": "string", "format": "uuid", "nullable": true }, "rank": { "type": "string", "nullable": true }, "publication_state": { "type": "string", "nullable": true }, "origin": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "acceptance_criteria": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "test_cases": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "comments": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "requirement_links": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "dependencies": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "ticket_links": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "followers": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "project_updates": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "project_followers": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "risks": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "decisions": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a delivery project", "description": "Permanently deletes the project and cascades to its work items, specs, etc.", "operationId": "deleteDeliveryProject", "tags": [ "Delivery Projects" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "planning:write", "parameters": [ { "name": "project_key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "project_key": { "type": "string" } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/planning/projects/{project_key}/audit": { "get": { "summary": "List project audit log entries", "description": "", "operationId": "listProjectAuditLog", "tags": [ "Delivery Projects" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "planning:read", "parameters": [ { "name": "project_key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor from a previous response.", "schema": { "type": "string", "maxLength": 500 } }, { "name": "limit", "in": "query", "required": false, "description": "Max rows to return. Default 25, max 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Audit entries.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "actor_user_id": { "type": "string", "nullable": true }, "actor_type": { "type": "string" }, "action": { "type": "string" }, "resource_type": { "type": "string" }, "resource_id": { "type": "string", "nullable": true }, "metadata": { "type": "object", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" } } } }, "project_key": { "type": "string" }, "project_url": { "type": "string", "format": "uri" }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/planning/projects/{project_key}/decisions": { "post": { "summary": "Record a project decision", "description": "", "operationId": "createProjectDecision", "tags": [ "Delivery Projects" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "planning:write", "parameters": [ { "name": "project_key", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "decision" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "context": { "type": "string", "maxLength": 20000, "default": "" }, "decision": { "type": "string", "minLength": 1, "maxLength": 30000 }, "status": { "type": "string", "enum": [ "proposed", "accepted" ], "default": "accepted" } } } } } }, "responses": { "201": { "description": "Recorded decision.", "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "object", "additionalProperties": true }, "project_url": { "type": "string", "format": "uri" } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/planning/projects/{project_key}/dependencies": { "post": { "summary": "Add a work item dependency", "description": "", "operationId": "addWorkItemDependency", "tags": [ "Work Items" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "planning:write", "parameters": [ { "name": "project_key", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "blocker_number", "blocked_number" ], "properties": { "blocker_number": { "type": "integer", "minimum": 1 }, "blocked_number": { "type": "integer", "minimum": 1 }, "relationship": { "type": "string", "enum": [ "blocks", "relates_to", "duplicates" ], "default": "blocks" } } } } } }, "responses": { "201": { "description": "Created dependency. CONFLICT if it already exists, VALIDATION if it would create a cycle.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dependency": { "type": "object", "additionalProperties": true } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/planning/projects/{project_key}/publish": { "post": { "summary": "Publish a reviewed project plan", "description": "Re-scores plan quality against live state and blocks (VALIDATION) if not publication_eligible.", "operationId": "publishDeliveryProject", "tags": [ "Delivery Projects" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "planning:publish", "parameters": [ { "name": "project_key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Published project.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "type": "object", "additionalProperties": true } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/planning/projects/{project_key}/quality": { "get": { "summary": "Get live plan-quality and publish-readiness diagnostics", "description": "", "operationId": "getProjectPlanQuality", "tags": [ "Delivery Projects" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "planning:read", "parameters": [ { "name": "project_key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Quality score computed from current work items.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project_key": { "type": "string" }, "computed_from": { "type": "string", "enum": [ "live_project_state" ] }, "has_planning_run": { "type": "boolean" }, "planning_run_id": { "type": "string", "nullable": true }, "planning_run_status": { "type": "string", "nullable": true }, "quality_score": { "type": "object", "properties": { "overall": { "type": "number" }, "requirement_quality": { "type": "number" }, "criteria_quality": { "type": "number" }, "test_quality": { "type": "number" }, "structure_quality": { "type": "number" }, "findings": { "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "string" }, "severity": { "type": "string", "enum": [ "error", "warning" ] }, "message": { "type": "string" }, "key": { "type": "string" } } } }, "publication_eligible": { "type": "boolean" } } }, "publication_eligible": { "type": "boolean" } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/planning/projects/{project_key}/risks": { "post": { "summary": "Create a project risk", "description": "", "operationId": "createProjectRisk", "tags": [ "Delivery Projects" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "planning:write", "parameters": [ { "name": "project_key", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 20000, "default": "" }, "severity": { "type": "string", "enum": [ "low", "medium", "high", "critical" ], "default": "medium" }, "probability": { "type": "string", "enum": [ "low", "medium", "high" ], "default": "medium" }, "mitigation": { "type": "string", "maxLength": 20000, "default": "" }, "owner_id": { "type": "string", "format": "uuid", "nullable": true }, "due_date": { "type": "string", "format": "date", "nullable": true } } } } } }, "responses": { "201": { "description": "Created risk.", "content": { "application/json": { "schema": { "type": "object", "properties": { "risk": { "type": "object", "additionalProperties": true }, "project_url": { "type": "string", "format": "uri" } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/planning/projects/{project_key}/risks/{id}": { "patch": { "summary": "Update a project risk", "description": "", "operationId": "updateProjectRisk", "tags": [ "Delivery Projects" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "planning:write", "parameters": [ { "name": "project_key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "At least one field is required.", "properties": { "status": { "type": "string", "enum": [ "open", "mitigating", "accepted", "resolved" ] }, "mitigation": { "type": "string", "maxLength": 20000, "nullable": true }, "severity": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "probability": { "type": "string", "enum": [ "low", "medium", "high" ] }, "owner_id": { "type": "string", "format": "uuid", "nullable": true }, "due_date": { "type": "string", "format": "date", "nullable": true } } } } } }, "responses": { "200": { "description": "Updated risk.", "content": { "application/json": { "schema": { "type": "object", "properties": { "risk": { "type": "object", "additionalProperties": true }, "project_url": { "type": "string", "format": "uri" } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/planning/projects/{project_key}/updates": { "post": { "summary": "Post a project status update", "description": "", "operationId": "createProjectUpdate", "tags": [ "Delivery Projects" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "planning:write", "parameters": [ { "name": "project_key", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "body" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "body": { "type": "string", "minLength": 1, "maxLength": 20000 }, "health": { "type": "string", "enum": [ "on_track", "at_risk", "off_track" ], "nullable": true } } } } } }, "responses": { "201": { "description": "Created update.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project_update": { "type": "object", "additionalProperties": true }, "project_url": { "type": "string", "format": "uri" } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/planning/projects/{project_key}/work-items": { "get": { "summary": "List work items", "description": "", "operationId": "listWorkItems", "tags": [ "Work Items" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "planning:read", "parameters": [ { "name": "project_key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "backlog", "ready", "in_progress", "in_review", "blocked", "done", "cancelled" ] } } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor from a previous response.", "schema": { "type": "string", "maxLength": 500 } }, { "name": "limit", "in": "query", "required": false, "description": "Max rows to return. Default 25, max 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Page of work items.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "item_type": { "type": "string", "enum": [ "epic", "story", "task", "milestone" ] }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "backlog", "ready", "in_progress", "in_review", "blocked", "done", "cancelled" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "estimate_points": { "type": "number", "nullable": true }, "owner_id": { "type": "string", "format": "uuid", "nullable": true }, "start_date": { "type": "string", "format": "date", "nullable": true }, "due_date": { "type": "string", "format": "date", "nullable": true }, "cycle_id": { "type": "string", "format": "uuid", "nullable": true }, "rank": { "type": "string", "nullable": true }, "publication_state": { "type": "string", "nullable": true }, "origin": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "project_key": { "type": "string" }, "project_url": { "type": "string", "format": "uri" }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a work item", "description": "item_type epic has no parent; story requires parent_number of an epic; task requires parent_number of a story. acceptance_criteria/test_cases/requirement_keys only apply to stories.", "operationId": "createWorkItem", "tags": [ "Work Items" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "planning:write", "parameters": [ { "name": "project_key", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "item_type", "title" ], "properties": { "parent_number": { "type": "integer", "minimum": 1, "nullable": true }, "item_type": { "type": "string", "enum": [ "epic", "story", "task", "milestone" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 240 }, "description": { "type": "string", "maxLength": 30000, "default": "" }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ], "default": "medium" }, "estimate_points": { "type": "number", "minimum": 0, "maximum": 100, "nullable": true }, "owner_id": { "type": "string", "format": "uuid", "nullable": true }, "start_date": { "type": "string", "format": "date", "nullable": true }, "due_date": { "type": "string", "format": "date", "nullable": true }, "cycle_id": { "type": "string", "format": "uuid", "nullable": true }, "requirement_keys": { "type": "array", "items": { "type": "string", "pattern": "^REQ-\\d{3,}$" }, "maxItems": 30, "default": [] }, "acceptance_criteria": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 5000 }, "maxItems": 30, "default": [] }, "test_cases": { "type": "array", "items": { "type": "object", "required": [ "title", "expected_result" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 240 }, "test_type": { "type": "string", "enum": [ "unit", "integration", "e2e", "manual", "accessibility", "performance", "security" ] }, "preconditions": { "type": "string", "maxLength": 5000 }, "steps": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minItems": 1, "maxItems": 30 }, "expected_result": { "type": "string", "minLength": 1, "maxLength": 10000 }, "automation_status": { "type": "string", "enum": [ "none", "planned", "automated" ] } } }, "maxItems": 30, "default": [] } } } } } }, "responses": { "201": { "description": "Created work item.", "content": { "application/json": { "schema": { "type": "object", "properties": { "work_item": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "item_type": { "type": "string", "enum": [ "epic", "story", "task", "milestone" ] }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "backlog", "ready", "in_progress", "in_review", "blocked", "done", "cancelled" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "estimate_points": { "type": "number", "nullable": true }, "owner_id": { "type": "string", "format": "uuid", "nullable": true }, "start_date": { "type": "string", "format": "date", "nullable": true }, "due_date": { "type": "string", "format": "date", "nullable": true }, "cycle_id": { "type": "string", "format": "uuid", "nullable": true }, "rank": { "type": "string", "nullable": true }, "publication_state": { "type": "string", "nullable": true }, "origin": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "project_url": { "type": "string", "format": "uri" } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/planning/projects/{project_key}/work-items/bulk": { "patch": { "summary": "Bulk-update work items", "description": "", "operationId": "bulkUpdateWorkItems", "tags": [ "Work Items" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "planning:write", "parameters": [ { "name": "project_key", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "work_item_numbers", "changes" ], "properties": { "work_item_numbers": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "minItems": 1, "maxItems": 100 }, "changes": { "type": "object", "description": "Same shape as PATCH .../work-items/{number}; at least one field required.", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 240 }, "description": { "type": "string", "maxLength": 30000, "nullable": true }, "status": { "type": "string", "enum": [ "backlog", "ready", "in_progress", "in_review", "blocked", "done", "cancelled" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "owner_id": { "type": "string", "format": "uuid", "nullable": true }, "start_date": { "type": "string", "format": "date", "nullable": true }, "due_date": { "type": "string", "format": "date", "nullable": true }, "estimate_points": { "type": "number", "minimum": 0, "maximum": 10000, "nullable": true }, "cycle_id": { "type": "string", "format": "uuid", "nullable": true } } } } } } } }, "responses": { "200": { "description": "Updated work items.", "content": { "application/json": { "schema": { "type": "object", "properties": { "work_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "item_type": { "type": "string", "enum": [ "epic", "story", "task", "milestone" ] }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "backlog", "ready", "in_progress", "in_review", "blocked", "done", "cancelled" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "estimate_points": { "type": "number", "nullable": true }, "owner_id": { "type": "string", "format": "uuid", "nullable": true }, "start_date": { "type": "string", "format": "date", "nullable": true }, "due_date": { "type": "string", "format": "date", "nullable": true }, "cycle_id": { "type": "string", "format": "uuid", "nullable": true }, "rank": { "type": "string", "nullable": true }, "publication_state": { "type": "string", "nullable": true }, "origin": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "project_url": { "type": "string", "format": "uri" } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/planning/projects/{project_key}/work-items/{number}": { "patch": { "summary": "Update a work item", "description": "acceptance_criteria/test_cases/requirement_keys use replace-the-full-set semantics and only apply to stories.", "operationId": "updateWorkItem", "tags": [ "Work Items" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "planning:write", "parameters": [ { "name": "project_key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "At least one field is required.", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 240 }, "description": { "type": "string", "maxLength": 30000, "nullable": true }, "status": { "type": "string", "enum": [ "backlog", "ready", "in_progress", "in_review", "blocked", "done", "cancelled" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "owner_id": { "type": "string", "format": "uuid", "nullable": true }, "start_date": { "type": "string", "format": "date", "nullable": true }, "due_date": { "type": "string", "format": "date", "nullable": true }, "estimate_points": { "type": "number", "minimum": 0, "maximum": 10000, "nullable": true }, "cycle_id": { "type": "string", "format": "uuid", "nullable": true }, "acceptance_criteria": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 5000 }, "maxItems": 30 }, "test_cases": { "type": "array", "items": { "type": "object", "required": [ "title", "expected_result" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 240 }, "test_type": { "type": "string", "enum": [ "unit", "integration", "e2e", "manual", "accessibility", "performance", "security" ] }, "preconditions": { "type": "string", "maxLength": 5000 }, "steps": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minItems": 1, "maxItems": 30 }, "expected_result": { "type": "string", "minLength": 1, "maxLength": 10000 }, "automation_status": { "type": "string", "enum": [ "none", "planned", "automated" ] } } }, "maxItems": 30 }, "requirement_keys": { "type": "array", "items": { "type": "string", "pattern": "^REQ-\\d{3,}$" }, "maxItems": 30 } } } } } }, "responses": { "200": { "description": "Updated work item.", "content": { "application/json": { "schema": { "type": "object", "properties": { "work_item": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "item_type": { "type": "string", "enum": [ "epic", "story", "task", "milestone" ] }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "backlog", "ready", "in_progress", "in_review", "blocked", "done", "cancelled" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "estimate_points": { "type": "number", "nullable": true }, "owner_id": { "type": "string", "format": "uuid", "nullable": true }, "start_date": { "type": "string", "format": "date", "nullable": true }, "due_date": { "type": "string", "format": "date", "nullable": true }, "cycle_id": { "type": "string", "format": "uuid", "nullable": true }, "rank": { "type": "string", "nullable": true }, "publication_state": { "type": "string", "nullable": true }, "origin": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "project_url": { "type": "string", "format": "uri" } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a work item", "description": "Blocks with VALIDATION if the item has children unless cascade=true.", "operationId": "deleteWorkItem", "tags": [ "Work Items" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "planning:write", "parameters": [ { "name": "project_key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "cascade", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "number": { "type": "integer" }, "project_key": { "type": "string" }, "cascaded_children": { "type": "integer" }, "project_url": { "type": "string", "format": "uri" } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/planning/projects/{project_key}/work-items/{number}/comments": { "post": { "summary": "Comment on a work item", "description": "Notifies the owner and followers.", "operationId": "addWorkItemComment", "tags": [ "Work Items" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "planning:write", "parameters": [ { "name": "project_key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 20000 } } } } } }, "responses": { "201": { "description": "Created comment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "object", "additionalProperties": true } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/planning/projects/{project_key}/work-items/{number}/move": { "post": { "summary": "Reorder / restatus a work item", "description": "Sets status and recomputes rank between before_number/after_number neighbors (midpoint ranking).", "operationId": "moveWorkItem", "tags": [ "Work Items" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "planning:write", "parameters": [ { "name": "project_key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "number", "status" ], "description": "number must equal the path {number}.", "properties": { "number": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "backlog", "ready", "in_progress", "in_review", "blocked", "done", "cancelled" ] }, "before_number": { "type": "integer", "minimum": 1, "nullable": true }, "after_number": { "type": "integer", "minimum": 1, "nullable": true } } } } } }, "responses": { "200": { "description": "Repositioned work item.", "content": { "application/json": { "schema": { "type": "object", "properties": { "work_item": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "status": { "type": "string" }, "rank": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "project_url": { "type": "string", "format": "uri" } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/planning/projects/{project_key}/work-items/{number}/requirements": { "post": { "summary": "Link a requirement to a work item", "description": "Only stories can have requirements linked.", "operationId": "linkWorkItemRequirement", "tags": [ "Work Items" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "planning:write", "parameters": [ { "name": "project_key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "requirement_key" ], "properties": { "requirement_key": { "type": "string", "pattern": "^REQ-\\d{3,}$" }, "relationship": { "type": "string", "enum": [ "implements", "verifies", "informs" ], "default": "implements" } } } } } }, "responses": { "201": { "description": "Linked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "linked": { "type": "boolean" }, "project_key": { "type": "string" }, "number": { "type": "integer" }, "requirement_key": { "type": "string" }, "relationship": { "type": "string" }, "project_url": { "type": "string", "format": "uri" } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/planning/runs": { "post": { "summary": "Start a PRD planning run", "description": "Turns a PRD into epics, stories, tasks, acceptance criteria, and tests via an async workflow.", "operationId": "startPlanningRun", "tags": [ "Planning Runs" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "planning:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "project_key", "prd" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "project_key": { "type": "string", "minLength": 2, "maxLength": 10, "pattern": "^[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*$" }, "objective": { "type": "string", "maxLength": 2000, "default": "" }, "prd": { "type": "string", "minLength": 40, "maxLength": 200000 }, "app_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20, "default": [] }, "dry_run": { "type": "boolean", "default": false }, "webhook_url": { "type": "string", "format": "uri", "maxLength": 2000, "nullable": true } } } } } }, "responses": { "202": { "description": "Started run. CONFLICT if project_key is in use or already has an active run.", "content": { "application/json": { "schema": { "type": "object", "properties": { "planning_run_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "current_stage": { "type": "string", "nullable": true }, "progress": { "type": "number" }, "status_url": { "type": "string", "format": "uri" }, "review_url": { "type": "string", "format": "uri" } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/planning/runs/{id}": { "get": { "summary": "Get planning run status", "description": "", "operationId": "getPlanningRun", "tags": [ "Planning Runs" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "planning:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Run status/progress/result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "delivery_project_id": { "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "project_key": { "type": "string" }, "status": { "type": "string" }, "current_stage": { "type": "string", "nullable": true }, "progress": { "type": "number" }, "stage_log": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "result_summary": { "type": "object", "nullable": true, "additionalProperties": true }, "quality_score": { "type": "object", "nullable": true, "additionalProperties": true }, "degradation_flags": { "type": "object", "additionalProperties": true }, "stage_diagnostics": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "error_message": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "review_url": { "type": "string", "format": "uri" }, "project_url": { "type": "string", "format": "uri", "nullable": true } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/planning/runs/{id}/cancel": { "post": { "summary": "Cancel a planning run", "description": "", "operationId": "cancelPlanningRun", "tags": [ "Planning Runs" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "planning:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Cancelled. CONFLICT if the run is already terminal.", "content": { "application/json": { "schema": { "type": "object", "properties": { "planning_run_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "cancelled" ] } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/planning/runs/{id}/questions": { "get": { "summary": "List clarification questions for a planning run", "description": "", "operationId": "listPlanningRunQuestions", "tags": [ "Planning Runs" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "planning:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Questions and current answer state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "planning_run": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "current_stage": { "type": "string", "nullable": true }, "progress": { "type": "number" } } }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "category": { "type": "string" }, "question": { "type": "string" }, "rationale": { "type": "string", "nullable": true }, "suggested_answers": { "type": "array", "items": { "type": "string" } }, "is_blocking": { "type": "boolean" }, "answer": { "type": "string", "nullable": true }, "resolution": { "type": "string", "nullable": true }, "answered_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Answer planning run clarification questions", "description": "Submits answers to blocking clarification questions to resume a paused (status=clarifying) run.", "operationId": "answerPlanningRunQuestions", "tags": [ "Planning Runs" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "planning:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "answers" ], "properties": { "answers": { "type": "array", "minItems": 1, "maxItems": 5, "items": { "type": "object", "required": [ "question_id", "answer", "resolution" ], "properties": { "question_id": { "type": "string", "format": "uuid" }, "answer": { "type": "string", "minLength": 1, "maxLength": 5000 }, "resolution": { "type": "string", "enum": [ "answered", "best_judgment" ] } } } } } } } } }, "responses": { "202": { "description": "Resumed. CONFLICT if the run is not waiting on clarification or answers omit a required blocking question.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "resumed": { "type": "boolean" }, "planning_run_id": { "type": "string", "format": "uuid" } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects": { "get": { "summary": "List simple (non-delivery) projects", "description": "A lighter project list tied to tickets, distinct from delivery projects under /planning/projects.", "operationId": "listSimpleProjects", "tags": [ "Tickets" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "tickets:read", "responses": { "200": { "description": "Projects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/meetings": { "get": { "summary": "List meetings", "description": "", "operationId": "listMeetings", "tags": [ "Meetings" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "meetings:read", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Max rows to return. Default 50, max 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor from a previous response.", "schema": { "type": "string", "maxLength": 500 } }, { "name": "status", "in": "query", "required": false, "description": "Comma-separated status values.", "schema": { "type": "string" } }, { "name": "owner_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Page of meetings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "objective": { "type": "string" }, "meeting_type": { "type": "string", "enum": [ "weekly_project_review", "sprint_planning", "sprint_retrospective", "product_discovery", "customer_feedback", "incident_review", "design_review", "one_to_one", "general" ] }, "status": { "type": "string", "enum": [ "draft", "scheduled", "in_progress", "completed", "processing", "needs_review", "published", "archived", "cancelled", "processing_failed" ] }, "review_status": { "type": "string", "nullable": true }, "visibility": { "type": "string", "enum": [ "private", "participants", "linked_context", "workspace", "external_shared" ] }, "owner_id": { "type": "string", "format": "uuid" }, "scheduled_start_at": { "type": "string", "format": "date-time", "nullable": true }, "scheduled_end_at": { "type": "string", "format": "date-time", "nullable": true }, "timezone": { "type": "string" }, "location": { "type": "string", "nullable": true }, "conferencing_url": { "type": "string", "format": "uri", "nullable": true }, "version": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "next_cursor": { "type": "string", "nullable": true } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a meeting", "description": "Owner (defaults to caller) is auto-added as an internal organizer participant.", "operationId": "createMeeting", "tags": [ "Meetings" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "meetings:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Opaque client-generated key (1-200 chars). Replaying the same key for this token within 24h returns the cached response instead of re-executing the write, and sets X-Flare-Idempotent-Replay: true on the response.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 240 }, "objective": { "type": "string", "maxLength": 10000, "default": "" }, "meeting_type": { "type": "string", "enum": [ "weekly_project_review", "sprint_planning", "sprint_retrospective", "product_discovery", "customer_feedback", "incident_review", "design_review", "one_to_one", "general" ], "default": "general" }, "visibility": { "type": "string", "enum": [ "private", "participants", "linked_context", "workspace", "external_shared" ], "default": "participants" }, "owner_id": { "type": "string", "format": "uuid" }, "scheduled_start_at": { "type": "string", "format": "date-time", "nullable": true }, "scheduled_end_at": { "type": "string", "format": "date-time", "nullable": true }, "timezone": { "type": "string", "default": "UTC" }, "location": { "type": "string", "maxLength": 500, "nullable": true }, "conferencing_url": { "type": "string", "format": "uri", "maxLength": 2048, "nullable": true }, "participants": { "type": "array", "maxItems": 250, "default": [], "items": { "oneOf": [ { "type": "object", "required": [ "participant_type", "user_id" ], "properties": { "participant_type": { "type": "string", "enum": [ "internal" ] }, "user_id": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "organizer", "facilitator", "note_taker", "attendee", "optional_attendee", "guest_viewer" ], "default": "attendee" }, "can_edit_notes": { "type": "boolean", "default": false }, "can_review_outcomes": { "type": "boolean", "default": false } } }, { "type": "object", "required": [ "participant_type", "external_email" ], "properties": { "participant_type": { "type": "string", "enum": [ "external" ] }, "external_name": { "type": "string", "maxLength": 160 }, "external_email": { "type": "string", "format": "email", "maxLength": 320 }, "role": { "type": "string", "enum": [ "attendee", "optional_attendee", "guest_viewer" ], "default": "attendee" }, "can_edit_notes": { "type": "boolean", "default": false }, "can_review_outcomes": { "type": "boolean", "default": false } } } ] } }, "agenda_items": { "type": "array", "maxItems": 100, "default": [], "items": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 240 }, "description": { "type": "string", "maxLength": 10000, "default": "" }, "desired_outcome": { "type": "string", "enum": [ "discuss", "decide", "brainstorm", "review", "approve", "inform" ], "default": "discuss" }, "owner_id": { "type": "string", "format": "uuid", "nullable": true }, "estimated_minutes": { "type": "integer", "minimum": 1, "maximum": 1440, "nullable": true } } } }, "delivery_project_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 50, "default": [] }, "app_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 50, "default": [] }, "settings": { "type": "object", "additionalProperties": true, "default": {} } } } } } }, "responses": { "201": { "description": "Created meeting (full detail shape).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "objective": { "type": "string" }, "meeting_type": { "type": "string", "enum": [ "weekly_project_review", "sprint_planning", "sprint_retrospective", "product_discovery", "customer_feedback", "incident_review", "design_review", "one_to_one", "general" ] }, "status": { "type": "string", "enum": [ "draft", "scheduled", "in_progress", "completed", "processing", "needs_review", "published", "archived", "cancelled", "processing_failed" ] }, "review_status": { "type": "string", "nullable": true }, "visibility": { "type": "string", "enum": [ "private", "participants", "linked_context", "workspace", "external_shared" ] }, "owner_id": { "type": "string", "format": "uuid" }, "scheduled_start_at": { "type": "string", "format": "date-time", "nullable": true }, "scheduled_end_at": { "type": "string", "format": "date-time", "nullable": true }, "timezone": { "type": "string" }, "location": { "type": "string", "nullable": true }, "conferencing_url": { "type": "string", "format": "uri", "nullable": true }, "version": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, { "type": "object", "properties": { "participants": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "agenda_items": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "latest_notes": { "type": "object", "additionalProperties": true, "nullable": true }, "attachments": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "delivery_project_links": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "app_links": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "transcript_segments": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "outcomes": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "artifacts": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "artifact_evidence": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "agent_runs": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "live_sessions": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "capture_artifacts": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "promises": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } ] } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/meetings/{meeting_id}": { "get": { "summary": "Get a meeting (full detail)", "description": "Includes participants, agenda, latest notes, attachments, links, transcript, outcomes, artifacts + evidence, agent runs, live sessions, capture artifacts, and the promise ledger.", "operationId": "getMeeting", "tags": [ "Meetings" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "meetings:read", "parameters": [ { "name": "meeting_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Meeting detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "objective": { "type": "string" }, "meeting_type": { "type": "string", "enum": [ "weekly_project_review", "sprint_planning", "sprint_retrospective", "product_discovery", "customer_feedback", "incident_review", "design_review", "one_to_one", "general" ] }, "status": { "type": "string", "enum": [ "draft", "scheduled", "in_progress", "completed", "processing", "needs_review", "published", "archived", "cancelled", "processing_failed" ] }, "review_status": { "type": "string", "nullable": true }, "visibility": { "type": "string", "enum": [ "private", "participants", "linked_context", "workspace", "external_shared" ] }, "owner_id": { "type": "string", "format": "uuid" }, "scheduled_start_at": { "type": "string", "format": "date-time", "nullable": true }, "scheduled_end_at": { "type": "string", "format": "date-time", "nullable": true }, "timezone": { "type": "string" }, "location": { "type": "string", "nullable": true }, "conferencing_url": { "type": "string", "format": "uri", "nullable": true }, "version": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, { "type": "object", "properties": { "participants": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "agenda_items": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "latest_notes": { "type": "object", "additionalProperties": true, "nullable": true }, "attachments": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "delivery_project_links": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "app_links": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "transcript_segments": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "outcomes": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "artifacts": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "artifact_evidence": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "agent_runs": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "live_sessions": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "capture_artifacts": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "promises": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } ] } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update a meeting", "description": "Optimistic concurrency: expected_version must match the meeting's current version or the request fails with CONFLICT.", "operationId": "updateMeeting", "tags": [ "Meetings" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "meetings:write", "parameters": [ { "name": "meeting_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Opaque client-generated key (1-200 chars). Replaying the same key for this token within 24h returns the cached response instead of re-executing the write, and sets X-Flare-Idempotent-Replay: true on the response.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "expected_version" ], "description": "At least one field besides expected_version is required.", "properties": { "expected_version": { "type": "integer", "minimum": 1 }, "title": { "type": "string", "minLength": 1, "maxLength": 240 }, "objective": { "type": "string", "maxLength": 10000, "nullable": true }, "meeting_type": { "type": "string", "enum": [ "weekly_project_review", "sprint_planning", "sprint_retrospective", "product_discovery", "customer_feedback", "incident_review", "design_review", "one_to_one", "general" ] }, "visibility": { "type": "string", "enum": [ "private", "participants", "linked_context", "workspace", "external_shared" ] }, "owner_id": { "type": "string", "format": "uuid" }, "scheduled_start_at": { "type": "string", "format": "date-time", "nullable": true }, "scheduled_end_at": { "type": "string", "format": "date-time", "nullable": true }, "timezone": { "type": "string" }, "location": { "type": "string", "maxLength": 500, "nullable": true }, "conferencing_url": { "type": "string", "format": "uri", "maxLength": 2048, "nullable": true }, "settings": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Updated meeting (full detail shape).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "objective": { "type": "string" }, "meeting_type": { "type": "string", "enum": [ "weekly_project_review", "sprint_planning", "sprint_retrospective", "product_discovery", "customer_feedback", "incident_review", "design_review", "one_to_one", "general" ] }, "status": { "type": "string", "enum": [ "draft", "scheduled", "in_progress", "completed", "processing", "needs_review", "published", "archived", "cancelled", "processing_failed" ] }, "review_status": { "type": "string", "nullable": true }, "visibility": { "type": "string", "enum": [ "private", "participants", "linked_context", "workspace", "external_shared" ] }, "owner_id": { "type": "string", "format": "uuid" }, "scheduled_start_at": { "type": "string", "format": "date-time", "nullable": true }, "scheduled_end_at": { "type": "string", "format": "date-time", "nullable": true }, "timezone": { "type": "string" }, "location": { "type": "string", "nullable": true }, "conferencing_url": { "type": "string", "format": "uri", "nullable": true }, "version": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, { "type": "object", "properties": { "participants": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "agenda_items": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "latest_notes": { "type": "object", "additionalProperties": true, "nullable": true }, "attachments": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "delivery_project_links": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "app_links": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "transcript_segments": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "outcomes": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "artifacts": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "artifact_evidence": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "agent_runs": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "live_sessions": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "capture_artifacts": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "promises": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } ] } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/meetings/{meeting_id}/{action}": { "post": { "summary": "Transition a meeting lifecycle state", "description": "action is one of start, complete, cancel, publish. Valid transitions: start (draft/scheduled → in_progress), complete (in_progress → completed), cancel (draft/scheduled/in_progress → cancelled), publish (completed/needs_review → published, requires the meetings:publish scope). Optimistic concurrency via expected_version.\n\naction=publish additionally requires the meetings:publish scope.", "operationId": "transitionMeeting", "tags": [ "Meetings" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "meetings:write", "parameters": [ { "name": "meeting_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "start", "complete", "cancel", "publish" ] } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Opaque client-generated key (1-200 chars). Replaying the same key for this token within 24h returns the cached response instead of re-executing the write, and sets X-Flare-Idempotent-Replay: true on the response.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "expected_version" ], "properties": { "expected_version": { "type": "integer", "minimum": 1 } } } } } }, "responses": { "200": { "description": "Meeting after transition (full detail shape). CONFLICT on version mismatch or illegal transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "objective": { "type": "string" }, "meeting_type": { "type": "string", "enum": [ "weekly_project_review", "sprint_planning", "sprint_retrospective", "product_discovery", "customer_feedback", "incident_review", "design_review", "one_to_one", "general" ] }, "status": { "type": "string", "enum": [ "draft", "scheduled", "in_progress", "completed", "processing", "needs_review", "published", "archived", "cancelled", "processing_failed" ] }, "review_status": { "type": "string", "nullable": true }, "visibility": { "type": "string", "enum": [ "private", "participants", "linked_context", "workspace", "external_shared" ] }, "owner_id": { "type": "string", "format": "uuid" }, "scheduled_start_at": { "type": "string", "format": "date-time", "nullable": true }, "scheduled_end_at": { "type": "string", "format": "date-time", "nullable": true }, "timezone": { "type": "string" }, "location": { "type": "string", "nullable": true }, "conferencing_url": { "type": "string", "format": "uri", "nullable": true }, "version": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, { "type": "object", "properties": { "participants": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "agenda_items": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "latest_notes": { "type": "object", "additionalProperties": true, "nullable": true }, "attachments": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "delivery_project_links": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "app_links": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "transcript_segments": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "outcomes": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "artifacts": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "artifact_evidence": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "agent_runs": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "live_sessions": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "capture_artifacts": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "promises": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } ] } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/meetings/{meeting_id}/artifacts": { "get": { "summary": "List meeting artifacts", "description": "AI-drafted artifacts (decisions/actions/etc.) with their supporting transcript evidence.", "operationId": "listMeetingArtifacts", "tags": [ "Meetings" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "meetings:read", "parameters": [ { "name": "meeting_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Artifacts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "transcript_version": { "type": "integer" }, "artifact_key": { "type": "string" }, "kind": { "type": "string" }, "title": { "type": "string" }, "structured_payload": { "type": "object", "additionalProperties": true }, "confidence": { "type": "number" }, "status": { "type": "string", "enum": [ "proposed", "approved", "rejected", "deferred" ] }, "automation_level": { "type": "number" }, "destination_type": { "type": "string", "nullable": true }, "destination_id": { "type": "string", "nullable": true }, "published_at": { "type": "string", "format": "date-time", "nullable": true }, "materialized_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "transcript_segment_id": { "type": "string" }, "quote": { "type": "string" }, "started_at": { "type": "string", "nullable": true }, "ended_at": { "type": "string", "nullable": true } } } } } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/meetings/{meeting_id}/artifacts/generate": { "post": { "summary": "Generate meeting artifacts from the transcript", "description": "Runs the AI meeting-artifact engine against the latest finalized transcript version. Idempotent by transcript checksum — replays a prior result if the transcript is unchanged.", "operationId": "generateMeetingArtifacts", "tags": [ "Meetings" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "meetings:process", "parameters": [ { "name": "meeting_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Opaque client-generated key (1-200 chars). Replaying the same key for this token within 24h returns the cached response instead of re-executing the write, and sets X-Flare-Idempotent-Replay: true on the response.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "202": { "description": "Generation result. VALIDATION if no finalized transcript exists yet.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "run": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "output": { "type": "object", "properties": { "transcript_version": { "type": "integer" }, "artifact_count": { "type": "integer" }, "artifact_ids": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "model": { "type": "string" }, "automation_level": { "type": "number" }, "destination_suggestions": { "type": "integer" }, "unresolved_destinations": { "type": "integer" } } } } }, "replayed": { "type": "boolean" } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/meetings/{meeting_id}/outcomes": { "post": { "summary": "Create a meeting outcome", "description": "Manually propose a decision/action/risk/requirement/update for review. Flips the meeting to needs_review if it was completed.", "operationId": "createMeetingOutcome", "tags": [ "Meetings" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "meetings:write", "parameters": [ { "name": "meeting_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Opaque client-generated key (1-200 chars). Replaying the same key for this token within 24h returns the cached response instead of re-executing the write, and sets X-Flare-Idempotent-Replay: true on the response.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "kind", "title" ], "properties": { "kind": { "type": "string", "enum": [ "decision", "action", "risk", "requirement", "update" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 240 }, "description": { "type": "string", "maxLength": 20000, "default": "" }, "owner_id": { "type": "string", "format": "uuid", "nullable": true }, "due_at": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "responses": { "201": { "description": "Created outcome (status=proposed).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "outcome": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "proposed" ] }, "owner_id": { "type": "string", "nullable": true }, "due_at": { "type": "string", "nullable": true } } } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/meetings/{meeting_id}/outcomes/materialize": { "post": { "summary": "Materialize an approved outcome onto the linked delivery project", "description": "action kind→destination: action→work item, decision→project decision, risk→project risk, requirement→project requirement, update→project update.", "operationId": "materializeMeetingOutcome", "tags": [ "Meetings" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "meetings:publish", "parameters": [ { "name": "meeting_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Opaque client-generated key (1-200 chars). Replaying the same key for this token within 24h returns the cached response instead of re-executing the write, and sets X-Flare-Idempotent-Replay: true on the response.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "outcome_id" ], "properties": { "outcome_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Materialized. VALIDATION if the outcome is not approved or the meeting has no linked project.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "outcome_id": { "type": "string", "format": "uuid" }, "destination_type": { "type": "string", "enum": [ "work_item", "decision", "risk", "requirement", "update" ] }, "destination_id": { "type": "string" } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/meetings/{meeting_id}/outcomes/review": { "post": { "summary": "Approve, reject, or defer a proposed outcome", "description": "", "operationId": "reviewMeetingOutcome", "tags": [ "Meetings" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "meetings:write", "parameters": [ { "name": "meeting_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Opaque client-generated key (1-200 chars). Replaying the same key for this token within 24h returns the cached response instead of re-executing the write, and sets X-Flare-Idempotent-Replay: true on the response.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "outcome_id", "decision" ], "properties": { "outcome_id": { "type": "string", "format": "uuid" }, "decision": { "type": "string", "enum": [ "approve", "reject", "defer" ] } } } } } }, "responses": { "200": { "description": "Reviewed outcome.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "outcome": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "approved", "rejected", "deferred" ] }, "title": { "type": "string" }, "kind": { "type": "string" } } } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/meetings/{meeting_id}/transcript": { "post": { "summary": "Import a meeting transcript", "description": "Plain text, one utterance per line, optionally in 'Speaker: text' format. Creates a new incrementing transcript version. Flips the meeting to needs_review if it was completed.", "operationId": "importMeetingTranscript", "tags": [ "Meetings" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "meetings:transcript", "parameters": [ { "name": "meeting_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Opaque client-generated key (1-200 chars). Replaying the same key for this token within 24h returns the cached response instead of re-executing the write, and sets X-Flare-Idempotent-Replay: true on the response.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 200000 } } } } } }, "responses": { "200": { "description": "Import result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "meeting_id": { "type": "string", "format": "uuid" }, "segments": { "type": "integer" }, "version": { "type": "integer" } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/meeting-agents": { "get": { "summary": "Get the caller's meeting-agent (Miro) settings", "description": "", "operationId": "getMeetingAgent", "tags": [ "Meeting Agents" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "meetings:read", "responses": { "200": { "description": "Settings, or null if not configured.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "nullable": true, "additionalProperties": true } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Upsert the caller's meeting-agent (Miro) settings", "description": "", "operationId": "putMeetingAgent", "tags": [ "Meeting Agents" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "meetings:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false }, "bot_display_name": { "type": "string", "minLength": 1, "maxLength": 120 }, "join_policy": { "type": "string", "enum": [ "none", "all_eligible", "organizer_only", "internal_only", "external_only" ], "default": "none" }, "allow_join_when_owner_absent": { "type": "boolean", "default": false }, "recording_mode": { "type": "string", "enum": [ "audio_transcript", "transcript_only", "audio_video_transcript" ], "default": "audio_transcript" }, "automation_level": { "type": "integer", "minimum": 1, "maximum": 3, "default": 1 }, "retention_days": { "type": "integer", "minimum": 1, "maximum": 3650, "nullable": true } } } } } }, "responses": { "200": { "description": "Upserted settings. VALIDATION if enabled=true without retention_days, or audio_video_transcript recording with automation_level>1.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/calendar-events/sync": { "post": { "summary": "Sync external calendar events", "description": "Batch-upsert events for one of the caller's calendar connections; reconciles create/update/cancel state.", "operationId": "syncCalendarEvents", "tags": [ "Meetings" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "meetings:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "connection_id", "events" ], "properties": { "connection_id": { "type": "string", "format": "uuid" }, "events": { "type": "array", "minItems": 1, "maxItems": 250, "items": { "type": "object", "required": [ "external_event_id", "title", "scheduled_start_at", "scheduled_end_at" ], "properties": { "external_event_id": { "type": "string", "minLength": 1, "maxLength": 1000 }, "i_cal_uid": { "type": "string", "maxLength": 1000, "nullable": true }, "recurring_master_id": { "type": "string", "maxLength": 1000, "nullable": true }, "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "organizer_email": { "type": "string", "format": "email", "maxLength": 320, "nullable": true }, "attendee_emails": { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 500, "default": [] }, "scheduled_start_at": { "type": "string", "format": "date-time" }, "scheduled_end_at": { "type": "string", "format": "date-time" }, "timezone": { "type": "string", "default": "UTC" }, "conference_url": { "type": "string", "format": "uri", "maxLength": 2048, "nullable": true }, "event_status": { "type": "string", "enum": [ "confirmed", "tentative", "cancelled" ], "default": "confirmed" }, "source_updated_at": { "type": "string", "format": "date-time", "nullable": true } } } } } } } } }, "responses": { "200": { "description": "Sync result counts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "created": { "type": "integer" }, "updated": { "type": "integer" }, "cancelled": { "type": "integer" }, "unchanged": { "type": "integer" }, "total": { "type": "integer" } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/meetings": { "get": { "summary": "Get org-wide meeting automation admin snapshot", "description": "Requires an admin or owner membership role in the org, in addition to the meetings:read scope.\n\nRequires the calling user to hold an admin or owner role in the organization — FORBIDDEN otherwise, even with a valid meetings:read token.", "operationId": "getMeetingsAdminSnapshot", "tags": [ "Admin" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "meetings:read", "responses": { "200": { "description": "Policy, agents, connections, sessions, meetings, and rollup metrics.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "policy": { "type": "object", "additionalProperties": true }, "agents": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "connections": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "sessions": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "meetings": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "metrics": { "type": "object", "additionalProperties": true } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Apply an org-wide meeting automation admin action", "description": "Requires an admin or owner membership role in the org, in addition to the meetings:write scope.\n\nRequires the calling user to hold an admin or owner role in the organization — FORBIDDEN otherwise, even with a valid meetings:write token.", "operationId": "patchMeetingsAdmin", "tags": [ "Admin" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "meetings:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "action", "policy" ], "properties": { "action": { "type": "string", "enum": [ "update_policy" ] }, "policy": { "type": "object", "required": [ "capture_provider_enabled", "allow_join_when_owner_absent", "admin_raw_content_access" ], "properties": { "capture_provider_enabled": { "type": "boolean" }, "allowed_calendar_providers": { "type": "array", "items": { "type": "string", "enum": [ "google_calendar", "microsoft_outlook" ] }, "maxItems": 2 }, "allowed_conference_providers": { "type": "array", "items": { "type": "string", "enum": [ "google_meet", "zoom", "microsoft_teams" ] }, "maxItems": 3 }, "default_automation_level": { "type": "integer", "minimum": 1, "maximum": 3 }, "default_retention_days": { "type": "integer", "minimum": 1, "maximum": 3650 }, "allow_join_when_owner_absent": { "type": "boolean" }, "admin_raw_content_access": { "type": "boolean" } } } } }, { "type": "object", "required": [ "action", "agent_id" ], "properties": { "action": { "type": "string", "enum": [ "disable_agent" ] }, "agent_id": { "type": "string", "format": "uuid" } } }, { "type": "object", "required": [ "action", "connection_id" ], "properties": { "action": { "type": "string", "enum": [ "disable_connection" ] }, "connection_id": { "type": "string", "format": "uuid" } } } ] } } } }, "responses": { "200": { "description": "Result shape depends on action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vault/articles": { "get": { "summary": "List knowledge base articles", "description": "Scoped to one project by default; pass workspace_all=1 to list across every project in the workspace.", "operationId": "listVaultArticles", "tags": [ "Knowledge Vault" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "vault:read", "parameters": [ { "name": "project_id", "in": "query", "required": false, "description": "Delivery/vault project UUID. Provide this or project_slug.", "schema": { "type": "string", "format": "uuid" } }, { "name": "project_slug", "in": "query", "required": false, "description": "Delivery/vault project slug. Provide this or project_id.", "schema": { "type": "string", "maxLength": 80 } }, { "name": "vault_slot", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "workspace_all", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1", "true" ] } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "description": "Max rows to return. Default 100, max 500.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ], "responses": { "200": { "description": "Articles for one project, or every project when workspace_all is set.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "workspace_all": { "type": "boolean" }, "total": { "type": "integer" }, "offset": { "type": "integer" }, "limit": { "type": "integer" }, "articles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "body": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "vault_slot": { "type": "string", "nullable": true }, "source_kind": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "embedding_updated_at": { "type": "string", "format": "date-time", "nullable": true } } } }, "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" } } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a knowledge base article", "description": "Embeds the article asynchronously for semantic search; embedding failures are logged and swallowed, not surfaced to the caller.", "operationId": "createVaultArticle", "tags": [ "Knowledge Vault" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "vault:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Opaque client-generated key (1-200 chars). Replaying the same key for this token within 24h returns the cached response instead of re-executing the write, and sets X-Flare-Idempotent-Replay: true on the response.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "body" ], "properties": { "project_id": { "type": "string", "format": "uuid" }, "project_slug": { "type": "string", "maxLength": 80 }, "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "body": { "type": "string", "minLength": 1, "maxLength": 20000 }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 40 }, "maxItems": 10 }, "vault_slot": { "type": "string", "maxLength": 80, "nullable": true } } } } } }, "responses": { "201": { "description": "Created article.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "article": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "body": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "vault_slot": { "type": "string", "nullable": true }, "source_kind": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "embedding_updated_at": { "type": "string", "format": "date-time", "nullable": true } } } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vault/articles/{id}": { "get": { "summary": "Get a knowledge base article", "description": "", "operationId": "getVaultArticle", "tags": [ "Knowledge Vault" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "vault:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Article.", "content": { "application/json": { "schema": { "type": "object", "properties": { "article": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "body": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "vault_slot": { "type": "string", "nullable": true }, "source_kind": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "embedding_updated_at": { "type": "string", "format": "date-time", "nullable": true } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update a knowledge base article", "description": "Re-embeds on change (best-effort).", "operationId": "updateVaultArticle", "tags": [ "Knowledge Vault" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "vault:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Opaque client-generated key (1-200 chars). Replaying the same key for this token within 24h returns the cached response instead of re-executing the write, and sets X-Flare-Idempotent-Replay: true on the response.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "body": { "type": "string", "minLength": 1, "maxLength": 20000 }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 40 }, "maxItems": 10 }, "vault_slot": { "type": "string", "maxLength": 80, "nullable": true } } } } } }, "responses": { "200": { "description": "Updated article.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "article": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "body": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "vault_slot": { "type": "string", "nullable": true }, "source_kind": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "embedding_updated_at": { "type": "string", "format": "date-time", "nullable": true } } } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a knowledge base article", "description": "", "operationId": "deleteVaultArticle", "tags": [ "Knowledge Vault" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "vault:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Opaque client-generated key (1-200 chars). Replaying the same key for this token within 24h returns the cached response instead of re-executing the write, and sets X-Flare-Idempotent-Replay: true on the response.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "Deleted, including its embedding chunks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "article_id": { "type": "string", "format": "uuid" } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vault/search": { "get": { "summary": "Search the knowledge base", "description": "Hybrid semantic + lexical search over article chunks for one project.", "operationId": "searchVault", "tags": [ "Knowledge Vault" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "vault:read", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "project_id", "in": "query", "required": false, "description": "Delivery/vault project UUID. Provide this or project_slug.", "schema": { "type": "string", "format": "uuid" } }, { "name": "project_slug", "in": "query", "required": false, "description": "Delivery/vault project slug. Provide this or project_id.", "schema": { "type": "string", "maxLength": 80 } }, { "name": "limit", "in": "query", "required": false, "description": "Max rows to return. Default 5, max 20.", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 5 } } ], "responses": { "200": { "description": "Ranked matches.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "matches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "chunk_id": { "type": "string", "nullable": true }, "title": { "type": "string" }, "body": { "type": "string" }, "similarity": { "type": "number" }, "vault_slot": { "type": "string", "nullable": true }, "section": { "type": "string", "nullable": true } } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vault/unanswered": { "get": { "summary": "List questions the knowledge base could not answer", "description": "", "operationId": "listUnansweredQuestions", "tags": [ "Knowledge Vault" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "vault:read", "parameters": [ { "name": "project_id", "in": "query", "required": false, "description": "Delivery/vault project UUID. Provide this or project_slug.", "schema": { "type": "string", "format": "uuid" } }, { "name": "project_slug", "in": "query", "required": false, "description": "Delivery/vault project slug. Provide this or project_id.", "schema": { "type": "string", "maxLength": 80 } }, { "name": "limit", "in": "query", "required": false, "description": "Max rows to return. Default 20, max 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "responses": { "200": { "description": "Recent unanswered questions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "query_text": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vault/handoffs": { "get": { "summary": "List customer-support handoff queue items", "description": "", "operationId": "listVaultHandoffs", "tags": [ "Knowledge Vault" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "vault:read", "parameters": [ { "name": "project_id", "in": "query", "required": false, "description": "Delivery/vault project UUID. Provide this or project_slug.", "schema": { "type": "string", "format": "uuid" } }, { "name": "project_slug", "in": "query", "required": false, "description": "Delivery/vault project slug. Provide this or project_id.", "schema": { "type": "string", "maxLength": 80 } }, { "name": "limit", "in": "query", "required": false, "description": "Max rows to return. Default 20, max 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "responses": { "200": { "description": "Handoffs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "handoffs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vault/handoffs/{id}": { "patch": { "summary": "Update a handoff's status", "description": "", "operationId": "updateVaultHandoff", "tags": [ "Knowledge Vault" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "vault:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Opaque client-generated key (1-200 chars). Replaying the same key for this token within 24h returns the cached response instead of re-executing the write, and sets X-Flare-Idempotent-Replay: true on the response.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "open", "claimed", "resolved", "dismissed" ] } } } } } }, "responses": { "200": { "description": "Updated handoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "handoff": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "project_id": { "type": "string" }, "title": { "type": "string" } } } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vault/insights": { "get": { "summary": "List customer-support insights", "description": "", "operationId": "listVaultInsights", "tags": [ "Knowledge Vault" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "vault:read", "parameters": [ { "name": "project_id", "in": "query", "required": false, "description": "Delivery/vault project UUID. Provide this or project_slug.", "schema": { "type": "string", "format": "uuid" } }, { "name": "project_slug", "in": "query", "required": false, "description": "Delivery/vault project slug. Provide this or project_id.", "schema": { "type": "string", "maxLength": 80 } }, { "name": "limit", "in": "query", "required": false, "description": "Max rows to return. Default 20, max 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "responses": { "200": { "description": "Insights.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "insights": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vault/insights/{id}": { "patch": { "summary": "Update an insight's status", "description": "'resolved' is accepted as input and normalized/stored as 'promoted'.", "operationId": "updateVaultInsight", "tags": [ "Knowledge Vault" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "vault:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Opaque client-generated key (1-200 chars). Replaying the same key for this token within 24h returns the cached response instead of re-executing the write, and sets X-Flare-Idempotent-Replay: true on the response.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "open", "acknowledged", "promoted", "dismissed", "resolved" ] } } } } } }, "responses": { "200": { "description": "Updated insight.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "insight": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "project_id": { "type": "string" }, "title": { "type": "string" } } } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vault/sync-sources": { "get": { "summary": "List help-center sync sources", "description": "", "operationId": "listVaultSyncSources", "tags": [ "Knowledge Vault" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "vault:read", "parameters": [ { "name": "project_id", "in": "query", "required": false, "description": "Delivery/vault project UUID. Provide this or project_slug.", "schema": { "type": "string", "format": "uuid" } }, { "name": "project_slug", "in": "query", "required": false, "description": "Delivery/vault project slug. Provide this or project_id.", "schema": { "type": "string", "maxLength": 80 } } ], "responses": { "200": { "description": "Sources.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "source_url": { "type": "string" }, "vault_slot": { "type": "string" }, "enabled": { "type": "boolean" }, "last_synced_at": { "type": "string", "nullable": true }, "last_error": { "type": "string", "nullable": true }, "created_at": { "type": "string" } } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Add a help-center sync source", "description": "source_url must be a public https URL.", "operationId": "createVaultSyncSource", "tags": [ "Knowledge Vault" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "vault:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Opaque client-generated key (1-200 chars). Replaying the same key for this token within 24h returns the cached response instead of re-executing the write, and sets X-Flare-Idempotent-Replay: true on the response.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "label", "source_url", "vault_slot" ], "properties": { "project_id": { "type": "string", "format": "uuid" }, "project_slug": { "type": "string", "maxLength": 80 }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "source_url": { "type": "string", "format": "uri", "maxLength": 2000 }, "vault_slot": { "type": "string", "minLength": 1, "maxLength": 80 }, "enabled": { "type": "boolean" } } } } } }, "responses": { "201": { "description": "Created source.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "source": { "type": "object", "additionalProperties": true } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vault/sync-sources/{id}": { "delete": { "summary": "Delete a help-center sync source", "description": "", "operationId": "deleteVaultSyncSource", "tags": [ "Knowledge Vault" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "vault:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Opaque client-generated key (1-200 chars). Replaying the same key for this token within 24h returns the cached response instead of re-executing the write, and sets X-Flare-Idempotent-Replay: true on the response.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "source_id": { "type": "string", "format": "uuid" } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vault/organization-knowledge": { "get": { "summary": "Get the organization knowledge profile", "description": "Org-wide (not project-scoped): extracted org facts and profile status.", "operationId": "getOrganizationKnowledge", "tags": [ "Kiro" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "kiro:read", "responses": { "200": { "description": "Org profile and facts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "organization": { "type": "object", "nullable": true, "properties": { "name": { "type": "string" }, "website": { "type": "string", "nullable": true } } }, "profile": { "type": "object", "nullable": true, "properties": { "status": { "type": "string" }, "source": { "type": "string" }, "logo_url": { "type": "string", "nullable": true }, "generated_at": { "type": "string", "nullable": true }, "updated_at": { "type": "string", "nullable": true } } }, "facts": { "type": "array", "items": { "type": "object", "properties": { "predicate": { "type": "string" }, "value": { "type": "string" }, "confidence": { "type": "number" }, "source": { "type": "string" }, "updated_at": { "type": "string" } } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vault/projects": { "get": { "summary": "List vault-enabled projects (apps)", "description": "", "operationId": "listVaultProjects", "tags": [ "Kiro" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "kiro:read", "responses": { "200": { "description": "Projects with article counts and industry pack info.", "content": { "application/json": { "schema": { "type": "object", "properties": { "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "industry_pack": { "type": "string" }, "setup_completed_at": { "type": "string", "nullable": true }, "article_count": { "type": "integer" }, "updated_at": { "type": "string" } } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vault/kiro": { "get": { "summary": "Get Kiro config and vault coverage for a project", "description": "", "operationId": "getKiro", "tags": [ "Kiro" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "vault:read", "parameters": [ { "name": "project_id", "in": "query", "required": false, "description": "Delivery/vault project UUID. Provide this or project_slug.", "schema": { "type": "string", "format": "uuid" } }, { "name": "project_slug", "in": "query", "required": false, "description": "Delivery/vault project slug. Provide this or project_id.", "schema": { "type": "string", "maxLength": 80 } } ], "responses": { "200": { "description": "Config, coverage score, and available industry packs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "config": { "type": "object", "additionalProperties": true }, "coverage": { "type": "object", "additionalProperties": true }, "packs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" } } } } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update basic Kiro config", "description": "", "operationId": "updateKiro", "tags": [ "Kiro" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "vault:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Opaque client-generated key (1-200 chars). Replaying the same key for this token within 24h returns the cached response instead of re-executing the write, and sets X-Flare-Idempotent-Replay: true on the response.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid" }, "project_slug": { "type": "string", "maxLength": 80 }, "industry_pack": { "type": "string", "enum": [ "general", "b2b_saas", "d2c_ecommerce", "bookings_services" ] }, "brand_voice": { "type": "string", "maxLength": 4000 }, "escalation_notes": { "type": "string", "maxLength": 4000 }, "mark_setup_complete": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Same shape as GET /vault/kiro.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vault/kiro/behavior": { "get": { "summary": "Get full Kiro behavior (voice, routing, connectors, taxonomy)", "description": "", "operationId": "getKiroBehavior", "tags": [ "Kiro" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "kiro:read", "parameters": [ { "name": "project_id", "in": "query", "required": false, "description": "Delivery/vault project UUID. Provide this or project_slug.", "schema": { "type": "string", "format": "uuid" } }, { "name": "project_slug", "in": "query", "required": false, "description": "Delivery/vault project slug. Provide this or project_id.", "schema": { "type": "string", "maxLength": 80 } } ], "responses": { "200": { "description": "Config, coverage, taxonomy, and behavior summary.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "config": { "type": "object", "additionalProperties": true }, "coverage": { "type": "object", "additionalProperties": true }, "packs": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "taxonomy": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "behavior": { "type": "object", "additionalProperties": true } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update Kiro behavior", "description": "Full behavior update: voice, connectors, taxonomy, governance (do-not-say / escalate-when), disclosure template. Connector secrets are persisted separately and never returned in plaintext.", "operationId": "updateKiroBehavior", "tags": [ "Kiro" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "kiro:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Opaque client-generated key (1-200 chars). Replaying the same key for this token within 24h returns the cached response instead of re-executing the write, and sets X-Flare-Idempotent-Replay: true on the response.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid" }, "project_slug": { "type": "string", "maxLength": 80 }, "industry_pack": { "type": "string", "enum": [ "general", "b2b_saas", "d2c_ecommerce", "bookings_services" ] }, "brand_voice": { "type": "string", "maxLength": 4000 }, "escalation_notes": { "type": "string", "maxLength": 4000 }, "taxonomy": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "id", "label", "handling" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 40 }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": "string", "maxLength": 400 }, "handling": { "type": "string", "enum": [ "answer", "capture", "route" ] }, "severityScale": { "type": "boolean" }, "routeMessage": { "type": "string", "maxLength": 500 } } } }, "connector_order_enabled": { "type": "boolean" }, "connector_order_url": { "type": "string", "maxLength": 500 }, "connector_order_header": { "type": "string", "maxLength": 64 }, "connector_order_token": { "type": "string", "maxLength": 500 }, "connector_booking_enabled": { "type": "boolean" }, "connector_booking_url": { "type": "string", "maxLength": 500 }, "connector_booking_header": { "type": "string", "maxLength": 64 }, "connector_booking_token": { "type": "string", "maxLength": 500 }, "do_not_say": { "type": "array", "items": { "type": "string", "minLength": 3, "maxLength": 80 }, "maxItems": 40 }, "escalate_when": { "type": "array", "items": { "type": "string", "minLength": 3, "maxLength": 80 }, "maxItems": 40 }, "disclosure_template": { "type": "string", "maxLength": 500 }, "mark_setup_complete": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Same shape as GET /vault/kiro/behavior.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vault/kiro/connector/test": { "post": { "summary": "Test a Kiro order/booking-status connector", "description": "Live-tests the endpoint, then persists the (redacted) result whether it succeeds or fails. Not idempotent — always live-tests.", "operationId": "testKiroConnector", "tags": [ "Kiro" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "kiro:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "kind", "endpoint_url" ], "properties": { "project_id": { "type": "string", "format": "uuid" }, "project_slug": { "type": "string", "maxLength": 80 }, "kind": { "type": "string", "enum": [ "order_status", "booking_status" ] }, "endpoint_url": { "type": "string", "minLength": 1, "maxLength": 500 }, "auth_header_name": { "type": "string", "maxLength": 64 }, "auth_token": { "type": "string", "maxLength": 500 } } } } } }, "responses": { "200": { "description": "Test result. VALIDATION if the live connector test fails (config is saved either way).", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "kind": { "type": "string" }, "message": { "type": "string" }, "connector": { "type": "object", "additionalProperties": true } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vault/kiro/health": { "get": { "summary": "Get Kiro health dashboard", "description": "Coverage, unanswered question count, open insights/handoffs, 7-day tool-call stats, and a readiness verdict.", "operationId": "getKiroHealth", "tags": [ "Kiro" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "vault:read", "parameters": [ { "name": "project_id", "in": "query", "required": false, "description": "Delivery/vault project UUID. Provide this or project_slug.", "schema": { "type": "string", "format": "uuid" } }, { "name": "project_slug", "in": "query", "required": false, "description": "Delivery/vault project slug. Provide this or project_id.", "schema": { "type": "string", "maxLength": 80 } } ], "responses": { "200": { "description": "Health snapshot.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "coverage": { "type": "object", "additionalProperties": true }, "setup_completed_at": { "type": "string", "nullable": true }, "unanswered_count": { "type": "integer" }, "open_insights": { "type": "integer" }, "open_handoffs": { "type": "integer" }, "tool_calls": { "type": "object", "properties": { "call_count": { "type": "integer" }, "error_count": { "type": "integer" }, "success_rate": { "type": "number" }, "p50_ms": { "type": "number", "nullable": true }, "p95_ms": { "type": "number", "nullable": true }, "by_tool": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "status": { "type": "string", "enum": [ "ready", "needs_content" ] } } } } } }, "default": { "description": "Structured JSON error. `error.code` is one of MISSING_TOKEN, INVALID_TOKEN, REVOKED, EXPIRED, RATE_LIMITED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INTERNAL. RATE_LIMITED responses also set a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }