{ "openapi": "3.1.0", "info": { "title": "Archie Connect API", "version": "2026-04-24", "description": "REST surface for the Archie skill registry, conversations, and workstreams. When a capability ships, this spec regenerates.", "contact": { "name": "Archie Connect", "url": "https://developers.heyarchie.ai", "email": "hey@archie.ai" } }, "servers": [ { "url": "https://api.heyarchie.ai", "description": "Production" }, { "url": "https://api.alpha.heyarchie.com", "description": "Alpha" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "conversations", "description": "Chat with Archie. Single or multi-turn." }, { "name": "catalogue", "description": "Discover available skills." }, { "name": "WorkStreams", "description": "WorkStream templates, Workplans (a template bound to a client), Cycles (executions), and Tasks. Inline and containerized execution modes share this surface. Replaces the retired playbooks API.", "externalDocs": { "url": "/docs/workstreams" } }, { "name": "WorkStreams Cycles", "description": "Launch, track, and resolve WorkStream cycle executions." }, { "name": "WorkStreams Drafts", "description": "Draft a WorkStream conversationally before you commit it." }, { "name": "WorkStreams Studio", "description": "Author and refine WorkStream blueprints in Studio." }, { "name": "Connect Keys", "description": "Create, list, and revoke the API keys that authenticate Connect requests." }, { "name": "advisory", "description": "Advisory" }, { "name": "analysis", "description": "Analysis" }, { "name": "audit", "description": "Audit" }, { "name": "authoring", "description": "Authoring" }, { "name": "communication", "description": "Communication" }, { "name": "compliance", "description": "Compliance" }, { "name": "data", "description": "Data" }, { "name": "forensic", "description": "Forensic" }, { "name": "general", "description": "General" }, { "name": "integrations", "description": "Integrations" }, { "name": "memo", "description": "Memo" }, { "name": "reports", "description": "Reports" }, { "name": "research", "description": "Research" }, { "name": "review", "description": "Review" }, { "name": "topics", "description": "Topics" }, { "name": "transactions", "description": "Transactions" }, { "name": "utility", "description": "Utility" } ], "paths": { "/api/v1/connect-keys": { "get": { "tags": [ "Connect Keys" ], "summary": "List API keys for the caller's organization", "description": "Return all keys for the caller's org, merged with mirror metadata.\n\nCombines the WorkOS-canonical view (``id``, ``name``,\n``obfuscated_value``, ``last_used_at``, ``permissions``,\n``created_at``, ``updated_at``) with the mirror-canonical view\n(``workspace_id``, ``rate_limit_per_minute``, ``description``,\n``environment``, ``created_by_user_id``, ``rotated_from_key_id``,\n``expires_at``, ``revoked_at``). Mirror fields are None when no\nmirror row exists yet for a particular key.", "operationId": "list_keys_api_v1_connect_keys_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "title": "Response List Keys Api V1 Connect Keys Get" } } } } } }, "post": { "tags": [ "Connect Keys" ], "summary": "Create a new API key", "description": "Mint a new WorkOS-managed `sk_*` key + INSERT canonical mirror row.\n\nBody shape \u2014 all fields optional except ``name``::\n\n {\n \"name\": \"label string\", # required\n \"permissions\": [\"topics:read\"], # optional, default []\n \"workspace_id\": \"\", # optional, pins key to a workspace\n \"rate_limit_per_minute\": 60, # optional, per-key override\n \"description\": \"free text\", # optional\n \"environment\": \"sandbox\" | \"live\" # optional, default sandbox\n }\n\nMirror INSERT is part of the success contract \u2014 if it fails, we\nrollback by deleting the just-created WorkOS key. The caller never\nsees a key that exists in WorkOS but not in our mirror.\n\nResponse includes the full ``value`` (sk_\u2026) **once** \u2014 caller MUST\nsurface it to the developer and never store it. WorkOS will not\nreturn it again. Response also includes the full merged shape\n(mirror fields populated with whatever the body set).\n\n``expires_in_days`` (optional): when present and > 0 the mirror row's\n``expires_at`` is stamped ``now() + N days`` so the reaper revokes the\nkey on schedule. Omit (or 0/null) for a **non-expiring** key \u2014 the\nproduct surface's \"permanent\" / permakey-style key. ``expires_at IS\nNULL`` is the reaper's untouched state.", "operationId": "create_key_api_v1_connect_keys_post", "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "title": "Response Create Key Api V1 Connect Keys Post" } } } } } } }, "/api/v1/connect-keys/_helpers/permission-catalog": { "get": { "tags": [ "Connect Keys" ], "summary": "Permission catalog for key creation (derived from the skills registry)", "description": "Registry-derived permission catalog for the create-key dialog.\n\nSame open-to-org-members read gate as ``list_keys``; ``_helpers``\nsegment marks it portal-auxiliary, not customer-SDK contract.", "operationId": "permission_catalog_api_v1_connect_keys__helpers_permission_catalog_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "title": "Response Permission Catalog Api V1 Connect Keys Helpers Permission Catalog Get" } } } } } } }, "/api/v1/connect-keys/_helpers/workspaces": { "get": { "tags": [ "Connect Keys" ], "summary": "List workspaces in the caller's organization (for portal key-pin dropdown)", "description": "Return ``[{id, name, slug, created_at}]`` for the caller's org.\n\nPhase 8.c.2 helper for the portal's \"pin to workspace\" dropdown when\nediting a key. The ``_helpers`` segment indicates this is auxiliary\nsurface for the portal \u2014 not part of the canonical Connect Keys\ncontract that customer SDKs depend on. The result shape stays narrow\non purpose; if a richer workspaces resource ships later the portal\nwill move to it.", "operationId": "list_workspaces_for_keys_api_v1_connect_keys__helpers_workspaces_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "title": "Response List Workspaces For Keys Api V1 Connect Keys Helpers Workspaces Get" } } } } } } }, "/api/v1/connect-keys/{key_id}": { "get": { "tags": [ "Connect Keys" ], "summary": "Get a single API key (merged WorkOS + mirror shape)", "description": "Single-key read, same merged shape as the list endpoint.\n\nReturns 404 if WorkOS doesn't recognise the key. The mirror row may\nstill be present (e.g., revoked-in-WorkOS-but-not-cleaned-up) but\nwe 404 on WorkOS source-of-truth for the secret material.", "operationId": "get_key_api_v1_connect_keys__key_id__get", "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "title": "Response Get Key Api V1 Connect Keys Key Id Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Connect Keys" ], "summary": "Revoke an API key", "description": "Revoke a WorkOS API key + mark the mirror row revoked.\n\nIdempotent: a key that's already gone from WorkOS still updates the\nmirror's ``revoked_at`` (in case earlier revoke succeeded in WorkOS\nbut failed locally) and flushes the validator cache so any\nin-flight cached token rejects immediately.", "operationId": "revoke_key_api_v1_connect_keys__key_id__delete", "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "Connect Keys" ], "summary": "Update API key metadata (name/permissions in WorkOS, the rest in mirror)", "description": "Patch fields on a key.\n\nBody shape \u2014 every field optional, send only what you want changed::\n\n {\n \"name\": \"new label\",\n \"permissions\": [\"topics:read\"],\n \"workspace_id\": \" | null\",\n \"rate_limit_per_minute\": 60 | null,\n \"description\": \"text\" | null,\n \"environment\": \"sandbox\" | \"live\"\n }\n\nSplit semantics:\n\n* ``name`` / ``permissions`` go to the WorkOS Management API. WorkOS\n doesn't expose a PATCH on api_keys today, so a name-only update\n writes a no-op into the WorkOS call (logs a TODO); permissions\n changes are flagged as \"needs WorkOS PATCH support\" and rejected\n with 501. (Phase 8.b adds rotation as the workaround.)\n* ``workspace_id`` / ``rate_limit_per_minute`` / ``description`` /\n ``environment`` are mirror-only writes. ``workspace_id`` validated\n against the caller's org; ``rate_limit_per_minute`` >= 0;\n ``environment`` \u2208 {sandbox, live}.\n\nOn success, drops the per-key rate-limit cache so the next request\nre-reads from the mirror (avoids the up-to-5-minute stale window\nuntil the next ``validate_workos_api_key`` cache miss).", "operationId": "update_key_api_v1_connect_keys__key_id__patch", "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "title": "Response Update Key Api V1 Connect Keys Key Id Patch" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/connect-keys/{key_id}/flush-cache": { "post": { "tags": [ "Connect Keys" ], "summary": "Flush the in-process WorkOS validator cache for a key", "description": "Force the next bearer call with this key to re-validate against WorkOS.\n\nUse after rotating, revoking, or changing permissions on a key. The\nWorkOS validator caches results for 5 minutes per key value to avoid\nhammering api.workos.com; this endpoint short-circuits that cache by\ndropping any entry whose owner key_id matches.", "operationId": "flush_key_cache_api_v1_connect_keys__key_id__flush_cache_post", "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/connect-keys/{key_id}/rotate": { "post": { "tags": [ "Connect Keys" ], "summary": "Rotate an API key (new sk_*, old expires after grace period)", "description": "Mint a replacement key, schedule the old key for revoke.\n\nBody shape \u2014 all fields optional::\n\n {\n \"grace_period_hours\": 24 # how long the old key keeps working; default 24\n }\n\nThe new key inherits ``name``, ``permissions``, ``workspace_id``,\n``rate_limit_per_minute``, ``description``, ``environment`` from\nthe old key. ``rotated_from_key_id`` on the new row points back to\nthe old key_id (lets the reaper cron walk the chain).\n\nOld key gets ``expires_at = now() + grace_period_hours`` stamped on\nits mirror row; a separate reaper job is expected to revoke once\n``expires_at`` passes.\n\nResponse: same shape as POST / (full merged shape + one-time sk_\u2026\nvalue for the new key).", "operationId": "rotate_key_api_v1_connect_keys__key_id__rotate_post", "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "title": "Response Rotate Key Api V1 Connect Keys Key Id Rotate Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/accounts.reconcile/invoke": { "post": { "operationId": "invokeSkill_accounts_reconcile", "summary": "Reconcile bank, AR, AP, intercompany, or other accounts.", "tags": [ "transactions" ], "x-skill-name": "accounts.reconcile", "x-skill-slug": "reconcile_accounts", "x-skill-category": "transactions", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "client_id": { "format": "uuid", "title": "Client Id", "type": "string" }, "account_code": { "title": "Account Code", "type": "string" }, "period_start": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "default": null, "title": "Period Start" }, "period_end": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "default": null, "title": "Period End" }, "auto_match": { "default": true, "title": "Auto Match", "type": "boolean" } }, "required": [ "client_id", "account_code" ], "title": "ReconcileAccountsInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "reconcile_accounts" }, "output": { "$defs": { "Finding": { "properties": { "area": { "title": "Area", "type": "string" }, "description": { "title": "Description", "type": "string" }, "severity": { "default": "info", "title": "Severity", "type": "string" }, "recommendation": { "default": "", "title": "Recommendation", "type": "string" } }, "required": [ "area", "description" ], "title": "Finding", "type": "object" } }, "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "reconciliation_id": { "format": "uuid", "title": "Reconciliation Id", "type": "string" }, "matched_count": { "default": 0, "title": "Matched Count", "type": "integer" }, "unmatched_count": { "default": 0, "title": "Unmatched Count", "type": "integer" }, "reconciled": { "default": false, "title": "Reconciled", "type": "boolean" }, "difference": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ], "default": "0", "title": "Difference" }, "findings": { "items": { "$ref": "#/$defs/Finding" }, "title": "Findings", "type": "array" } }, "title": "ReconcileAccountsOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/accruals.suggest/invoke": { "post": { "operationId": "invokeSkill_accruals_suggest", "summary": "Advisory \u2014 LLM-driven; verify against authoritative sources before relying. Suggest month-end accruals for a client by scanning the trial balance, variance against prior periods, and recurring patterns. Read-only \u2014 produces structured suggestions for review; the user posts via record_journal_entry.", "tags": [ "transactions" ], "x-skill-name": "accruals.suggest", "x-skill-slug": "accruals_suggest", "x-skill-category": "transactions", "x-skill-cluster": "BOP", "x-skill-streaming": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "client_id": { "format": "uuid", "title": "Client Id", "type": "string" }, "period": { "description": "YYYY-MM month-end target (e.g. '2026-04')", "title": "Period", "type": "string" }, "lookback_months": { "default": 12, "description": "How many prior periods to scan for recurring patterns.", "maximum": 36, "minimum": 1, "title": "Lookback Months", "type": "integer" }, "focus_areas": { "description": "Optional shortlist of accrual categories \u2014 e.g. ['wages', 'interest', 'rent', 'utilities']. Empty means scan everything.", "items": { "type": "string" }, "title": "Focus Areas", "type": "array" }, "jurisdiction": { "anyOf": [ { "enum": [ "AU", "GB", "CA", "US", "NZ" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Jurisdiction" } }, "required": [ "client_id", "period" ], "title": "AccrualsSuggestInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "accruals_suggest" }, "output": { "$defs": { "AccrualSuggestion": { "description": "A single proposed accrual entry. The user reviews and posts via\nrecord_journal_entry; this skill never writes.", "properties": { "account": { "description": "Human-readable account name, e.g. 'Accrued Wages'.", "title": "Account", "type": "string" }, "account_code": { "description": "GL code (chart-of-accounts).", "title": "Account Code", "type": "string" }, "amount": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ], "description": "Suggested accrual amount in client currency.", "title": "Amount" }, "narration": { "description": "Short description for the journal narration.", "title": "Narration", "type": "string" }, "evidence": { "default": "", "description": "Why we suggested this \u2014 e.g. 'Prior 3 months avg $X, this period invoice missing'.", "title": "Evidence", "type": "string" }, "confidence": { "default": "medium", "enum": [ "high", "medium", "low" ], "title": "Confidence", "type": "string" } }, "required": [ "account", "account_code", "amount", "narration" ], "title": "AccrualSuggestion", "type": "object" }, "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" } }, "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "summary": { "default": "", "title": "Summary", "type": "string" }, "suggestions": { "items": { "$ref": "#/$defs/AccrualSuggestion" }, "title": "Suggestions", "type": "array" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" } }, "title": "AccrualsSuggestOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/acquisitions.advise/invoke": { "post": { "operationId": "invokeSkill_acquisitions_advise", "summary": "M&A advice \u2014 acquisition, merger, asset/share purchase, due diligence framing.", "tags": [ "advisory" ], "x-skill-name": "acquisitions.advise", "x-skill-slug": "advise_acquisition", "x-skill-category": "advisory", "x-skill-cluster": "MAV", "x-skill-streaming": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "topic": { "maxLength": 5000, "title": "Topic", "type": "string" }, "deal_type": { "default": "acquisition", "enum": [ "acquisition", "merger", "asset_purchase", "share_purchase", "due_diligence" ], "title": "Deal Type", "type": "string" }, "jurisdiction": { "anyOf": [ { "enum": [ "AU", "GB", "CA", "US", "NZ" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Jurisdiction" }, "client_context": { "additionalProperties": true, "title": "Client Context", "type": "object" }, "file_ids": { "items": { "format": "uuid", "type": "string" }, "title": "File Ids", "type": "array" } }, "required": [ "topic" ], "title": "AdviseAcquisitionInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "advise_acquisition" }, "output": { "$defs": { "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" } }, "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "advice": { "default": "", "title": "Advice", "type": "string" }, "checklist": { "items": { "type": "string" }, "title": "Checklist", "type": "array" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" }, "open_items": { "items": { "type": "string" }, "title": "Open Items", "type": "array" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "title": "AdviseAcquisitionOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/anomalies.investigate/invoke": { "post": { "operationId": "invokeSkill_anomalies_investigate", "summary": "Forensic investigation \u2014 Benford's Law, ACFE classification, chain-of-custody output.", "tags": [ "forensic" ], "x-skill-name": "anomalies.investigate", "x-skill-slug": "investigate_anomaly", "x-skill-category": "forensic", "x-skill-cluster": "ASR", "x-skill-streaming": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "client_id": { "format": "uuid", "title": "Client Id", "type": "string" }, "investigation_scope": { "additionalProperties": true, "title": "Investigation Scope", "type": "object" }, "benford_test": { "default": true, "title": "Benford Test", "type": "boolean" }, "round_number_test": { "default": true, "title": "Round Number Test", "type": "boolean" }, "duplicate_test": { "default": true, "title": "Duplicate Test", "type": "boolean" }, "vendor_abr_check": { "default": true, "title": "Vendor Abr Check", "type": "boolean" }, "threshold_override": { "additionalProperties": true, "title": "Threshold Override", "type": "object" }, "jurisdiction": { "anyOf": [ { "enum": [ "AU", "GB", "CA", "US", "NZ" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Jurisdiction" }, "alert_level": { "default": "standard", "enum": [ "conservative", "standard", "aggressive" ], "title": "Alert Level", "type": "string" } }, "required": [ "client_id" ], "title": "InvestigateAnomalyInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "investigate_anomaly" }, "output": { "$defs": { "BenfordResult": { "description": "First-digit Benford's-Law analysis output.", "properties": { "applied": { "default": false, "title": "Applied", "type": "boolean" }, "transactions_analysed": { "default": 0, "title": "Transactions Analysed", "type": "integer" }, "chi_square_statistic": { "default": 0.0, "title": "Chi Square Statistic", "type": "number" }, "p_value": { "default": 1.0, "title": "P Value", "type": "number" }, "significant": { "default": false, "title": "Significant", "type": "boolean" }, "digit_distribution": { "additionalProperties": { "additionalProperties": { "type": "number" }, "type": "object" }, "title": "Digit Distribution", "type": "object" }, "interpretation": { "default": "", "title": "Interpretation", "type": "string" } }, "title": "BenfordResult", "type": "object" }, "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" }, "RedFlag": { "description": "Forensic finding (used by investigate_anomaly, trace_assets).", "properties": { "flag_id": { "title": "Flag Id", "type": "string" }, "classification": { "default": "", "title": "Classification", "type": "string" }, "severity": { "default": "MODERATE", "enum": [ "MINOR", "MODERATE", "SIGNIFICANT", "CRITICAL" ], "title": "Severity", "type": "string" }, "description": { "default": "", "title": "Description", "type": "string" }, "evidence": { "items": { "type": "string" }, "title": "Evidence", "type": "array" }, "amount_at_risk": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ], "default": "0", "title": "Amount At Risk" }, "recommended_action": { "default": "", "title": "Recommended Action", "type": "string" } }, "required": [ "flag_id" ], "title": "RedFlag", "type": "object" } }, "properties": { "artifact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Artifact Id" }, "download_url": { "default": "", "title": "Download Url", "type": "string" }, "summary": { "default": "", "title": "Summary", "type": "string" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "investigation_id": { "format": "uuid", "title": "Investigation Id", "type": "string" }, "risk_rating": { "default": "LOW", "enum": [ "LOW", "MEDIUM", "HIGH", "CRITICAL" ], "title": "Risk Rating", "type": "string" }, "red_flags": { "items": { "$ref": "#/$defs/RedFlag" }, "title": "Red Flags", "type": "array" }, "benford_result": { "$ref": "#/$defs/BenfordResult" }, "duplicate_analysis": { "additionalProperties": { "items": {}, "type": "array" }, "title": "Duplicate Analysis", "type": "object" }, "evidence_checklist": { "items": { "type": "string" }, "title": "Evidence Checklist", "type": "array" }, "referral_pathways": { "items": { "type": "string" }, "title": "Referral Pathways", "type": "array" }, "limitations": { "items": { "type": "string" }, "title": "Limitations", "type": "array" }, "forensic_narrative": { "default": "", "title": "Forensic Narrative", "type": "string" } }, "title": "InvestigateAnomalyOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/assets.trace/invoke": { "post": { "operationId": "invokeSkill_assets_trace", "summary": "Forensic asset tracing \u2014 funds flow, related-party mapping, ownership trails.", "tags": [ "forensic" ], "x-skill-name": "assets.trace", "x-skill-slug": "trace_assets", "x-skill-category": "forensic", "x-skill-cluster": "ASR", "x-skill-streaming": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "client_id": { "format": "uuid", "title": "Client Id", "type": "string" }, "scope": { "default": "funds_flow", "enum": [ "funds_flow", "related_party", "asset_dissipation", "ownership", "matrimonial" ], "title": "Scope", "type": "string" }, "time_period": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Time Period" }, "target_entity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Target Entity" }, "file_ids": { "items": { "format": "uuid", "type": "string" }, "title": "File Ids", "type": "array" }, "jurisdiction": { "anyOf": [ { "enum": [ "AU", "GB", "CA", "US", "NZ" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Jurisdiction" } }, "required": [ "client_id" ], "title": "TraceAssetsInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "trace_assets" }, "output": { "$defs": { "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" }, "RedFlag": { "description": "Forensic finding (used by investigate_anomaly, trace_assets).", "properties": { "flag_id": { "title": "Flag Id", "type": "string" }, "classification": { "default": "", "title": "Classification", "type": "string" }, "severity": { "default": "MODERATE", "enum": [ "MINOR", "MODERATE", "SIGNIFICANT", "CRITICAL" ], "title": "Severity", "type": "string" }, "description": { "default": "", "title": "Description", "type": "string" }, "evidence": { "items": { "type": "string" }, "title": "Evidence", "type": "array" }, "amount_at_risk": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ], "default": "0", "title": "Amount At Risk" }, "recommended_action": { "default": "", "title": "Recommended Action", "type": "string" } }, "required": [ "flag_id" ], "title": "RedFlag", "type": "object" } }, "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "investigation_id": { "format": "uuid", "title": "Investigation Id", "type": "string" }, "funds_flow": { "items": { "additionalProperties": true, "type": "object" }, "title": "Funds Flow", "type": "array" }, "related_parties": { "items": { "additionalProperties": true, "type": "object" }, "title": "Related Parties", "type": "array" }, "red_flags": { "items": { "$ref": "#/$defs/RedFlag" }, "title": "Red Flags", "type": "array" }, "forensic_narrative": { "default": "", "title": "Forensic Narrative", "type": "string" }, "evidence_checklist": { "items": { "type": "string" }, "title": "Evidence Checklist", "type": "array" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" } }, "title": "TraceAssetsOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/audit.workpaper.review/invoke": { "post": { "operationId": "invokeSkill_audit_workpaper_review", "summary": "Advisory \u2014 LLM-driven; verify against authoritative sources before relying. Review an audit workpaper \u2014 completeness, methodology, evidence sufficiency, and standards compliance. Pairs with prepare_audit_workpaper; supports self-check, senior review, partner review, and concurring-partner review tiers.", "tags": [ "audit" ], "x-skill-name": "audit.workpaper.review", "x-skill-slug": "audit_workpaper_review", "x-skill-category": "audit", "x-skill-cluster": "ASR", "x-skill-streaming": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "client_id": { "format": "uuid", "title": "Client Id", "type": "string" }, "period": { "title": "Period", "type": "string" }, "file_ids": { "description": "Uploaded workpaper file(s) to review. At least one required.", "items": { "format": "uuid", "type": "string" }, "minItems": 1, "title": "File Ids", "type": "array" }, "workpaper_type": { "default": "lead_schedule", "enum": [ "lead_schedule", "substantive_test", "planning_memo", "going_concern", "subsequent_events", "revenue_testing", "expense_testing", "debt_confirmation", "related_party" ], "title": "Workpaper Type", "type": "string" }, "framework": { "default": "ISA", "enum": [ "ASA", "ISA", "PCAOB", "GAAS", "ISA_UK" ], "title": "Framework", "type": "string" }, "review_level": { "default": "self_check", "enum": [ "self_check", "senior_review", "partner_review", "concurring_partner_review" ], "title": "Review Level", "type": "string" }, "materiality": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Materiality" }, "focus_areas": { "description": "Optional reviewer focus shortlist \u2014 e.g. ['sample_selection', 'evidence_sufficiency', 'cutoff', 'standards_compliance']. Empty means full review.", "items": { "type": "string" }, "title": "Focus Areas", "type": "array" } }, "required": [ "client_id", "period", "file_ids" ], "title": "AuditWorkpaperReviewInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "audit_workpaper_review" }, "output": { "$defs": { "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" }, "Finding": { "properties": { "area": { "title": "Area", "type": "string" }, "description": { "title": "Description", "type": "string" }, "severity": { "default": "info", "title": "Severity", "type": "string" }, "recommendation": { "default": "", "title": "Recommendation", "type": "string" } }, "required": [ "area", "description" ], "title": "Finding", "type": "object" } }, "properties": { "artifact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Artifact Id" }, "download_url": { "default": "", "title": "Download Url", "type": "string" }, "summary": { "default": "", "title": "Summary", "type": "string" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "review_status": { "default": "pending", "enum": [ "pending", "cleared", "findings_to_address", "rejected" ], "title": "Review Status", "type": "string" }, "findings": { "items": { "$ref": "#/$defs/Finding" }, "title": "Findings", "type": "array" }, "recommendations": { "items": { "type": "string" }, "title": "Recommendations", "type": "array" }, "coverage_assessment": { "additionalProperties": { "type": "string" }, "description": "Per-area coverage rating \u2014 e.g. {'sample_selection': 'adequate', 'evidence': 'weak', 'cutoff': 'not_tested'}.", "title": "Coverage Assessment", "type": "object" } }, "title": "AuditWorkpaperReviewOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/clients.financials.get/invoke": { "post": { "operationId": "invokeSkill_clients_financials_get", "summary": "Get client financial data (raw, summary, variance, cashflow, or profitability view).", "tags": [ "data" ], "x-skill-name": "clients.financials.get", "x-skill-slug": "get_client_financials", "x-skill-category": "data", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "client_id": { "format": "uuid", "title": "Client Id", "type": "string" }, "view": { "default": "summary", "enum": [ "raw", "summary", "variance", "cashflow", "profitability" ], "title": "View", "type": "string" }, "period": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Period" }, "compare_period": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Compare Period" } }, "required": [ "client_id" ], "title": "GetClientFinancialsInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "get_client_financials" }, "output": { "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "view": { "default": "", "title": "View", "type": "string" }, "data": { "additionalProperties": true, "title": "Data", "type": "object" }, "period": { "default": "", "title": "Period", "type": "string" }, "currency": { "default": "AUD", "title": "Currency", "type": "string" }, "source": { "default": "", "title": "Source", "type": "string" } }, "title": "GetClientFinancialsOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/clients.list/invoke": { "post": { "operationId": "invokeSkill_clients_list", "summary": "(Utility) List accessible clients.", "tags": [ "utility" ], "x-skill-name": "clients.list", "x-skill-slug": "list_clients", "x-skill-category": "utility", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "search": { "default": "", "title": "Search", "type": "string" }, "jurisdiction": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Jurisdiction" }, "status": { "default": "active", "title": "Status", "type": "string" }, "limit": { "default": 50, "title": "Limit", "type": "integer" }, "offset": { "default": 0, "title": "Offset", "type": "integer" } }, "title": "ListClientsInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "list_clients" }, "output": { "$defs": { "ClientInfo": { "properties": { "id": { "format": "uuid", "title": "Id", "type": "string" }, "name": { "title": "Name", "type": "string" }, "jurisdiction": { "default": "", "title": "Jurisdiction", "type": "string" }, "status": { "default": "active", "title": "Status", "type": "string" } }, "required": [ "id", "name" ], "title": "ClientInfo", "type": "object" } }, "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "clients": { "items": { "$ref": "#/$defs/ClientInfo" }, "title": "Clients", "type": "array" }, "total_count": { "default": 0, "title": "Total Count", "type": "integer" }, "has_more": { "default": false, "title": "Has More", "type": "boolean" } }, "title": "ListClientsOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/communications.draft/invoke": { "post": { "operationId": "invokeSkill_communications_draft", "summary": "Draft a client communication \u2014 email, letter, memo, or report.", "tags": [ "communication" ], "x-skill-name": "communications.draft", "x-skill-slug": "prepare_communication", "x-skill-category": "communication", "x-skill-cluster": "ASR", "x-skill-streaming": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "type": { "enum": [ "email", "letter", "memo", "report" ], "title": "Type", "type": "string" }, "recipients": { "items": { "type": "string" }, "title": "Recipients", "type": "array" }, "subject": { "default": "", "title": "Subject", "type": "string" }, "context": { "default": "", "title": "Context", "type": "string" }, "tone": { "default": "formal", "enum": [ "formal", "friendly", "urgent" ], "title": "Tone", "type": "string" } }, "required": [ "type", "recipients" ], "title": "PrepareCommunicationInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "prepare_communication" }, "output": { "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "draft_id": { "format": "uuid", "title": "Draft Id", "type": "string" }, "content": { "default": "", "title": "Content", "type": "string" }, "subject_line": { "default": "", "title": "Subject Line", "type": "string" }, "suggested_attachments": { "items": { "type": "string" }, "title": "Suggested Attachments", "type": "array" } }, "title": "PrepareCommunicationOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/compliance.deadline.calendar/invoke": { "post": { "operationId": "invokeSkill_compliance_deadline_calendar", "summary": "Produce a structured calendar of upcoming filing/compliance deadlines for a client over a window. Covers tax returns, BAS/VAT/GST, payroll/STP/RTI, annual returns, audit requirements, super/pension, and board meetings. Read-only \u2014 the user or a workstream cycle acts on each entry separately.", "tags": [ "compliance" ], "x-skill-name": "compliance.deadline.calendar", "x-skill-slug": "compliance_deadline_calendar", "x-skill-category": "compliance", "x-skill-cluster": "CMP", "x-skill-streaming": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "client_id": { "format": "uuid", "title": "Client Id", "type": "string" }, "jurisdiction": { "enum": [ "AU", "GB", "CA", "US", "NZ" ], "title": "Jurisdiction", "type": "string" }, "entity_type": { "default": "individual", "enum": [ "individual", "corporation", "s_corporation", "partnership", "trust", "non_profit" ], "title": "Entity Type", "type": "string" }, "window": { "default": "next_quarter", "enum": [ "next_30_days", "next_quarter", "next_year", "explicit" ], "title": "Window", "type": "string" }, "lookahead_days": { "anyOf": [ { "maximum": 730, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null, "description": "Used only when window='explicit'; ignored otherwise.", "title": "Lookahead Days" }, "deadline_types": { "description": "Optional category filter \u2014 e.g. ['tax_return', 'bas', 'vat', 'payroll', 'annual_return', 'audit', 'super', 'pension']. Empty means scan all categories.", "items": { "type": "string" }, "title": "Deadline Types", "type": "array" } }, "required": [ "client_id", "jurisdiction" ], "title": "ComplianceDeadlineCalendarInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "compliance_deadline_calendar" }, "output": { "$defs": { "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" }, "DeadlineEntry": { "description": "A single compliance deadline. Output rows for the calendar.", "properties": { "name": { "description": "Human-readable deadline name, e.g. 'BAS Q2 lodgement'.", "title": "Name", "type": "string" }, "category": { "description": "Deadline category \u2014 `tax_return`, `bas`, `vat`, `gst_hst`, `payroll`, `annual_return`, `audit`, `super`, `pension`, `board_meeting`, etc. Free-form; the LLM specialist names it.", "title": "Category", "type": "string" }, "due_date": { "format": "date", "title": "Due Date", "type": "string" }, "urgency": { "default": "medium", "enum": [ "overdue", "high", "medium", "low" ], "title": "Urgency", "type": "string" }, "authority": { "default": "", "description": "Filing authority \u2014 'IRS', 'HMRC', 'ATO', 'CRA', etc.", "title": "Authority", "type": "string" }, "action_required": { "default": "", "description": "What the user must do \u2014 'Lodge online via Business Portal', etc.", "title": "Action Required", "type": "string" }, "reference": { "default": "", "description": "Citation for the rule, e.g. 'ATO BAS \u2014 28 days after end of quarter'.", "title": "Reference", "type": "string" } }, "required": [ "name", "category", "due_date" ], "title": "DeadlineEntry", "type": "object" } }, "properties": { "artifact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Artifact Id" }, "download_url": { "default": "", "title": "Download Url", "type": "string" }, "summary": { "default": "", "title": "Summary", "type": "string" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "deadlines": { "items": { "$ref": "#/$defs/DeadlineEntry" }, "title": "Deadlines", "type": "array" }, "jurisdiction": { "default": "", "title": "Jurisdiction", "type": "string" }, "window_start": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "default": null, "title": "Window Start" }, "window_end": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "default": null, "title": "Window End" } }, "title": "ComplianceDeadlineCalendarOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/compliance.review/invoke": { "post": { "operationId": "invokeSkill_compliance_review", "summary": "Review a document for regulatory compliance gaps.", "tags": [ "review" ], "x-skill-name": "compliance.review", "x-skill-slug": "review_compliance", "x-skill-category": "review", "x-skill-cluster": "CMP", "x-skill-streaming": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "document_id": { "format": "uuid", "title": "Document Id", "type": "string" }, "framework": { "title": "Framework", "type": "string" }, "scope": { "items": { "type": "string" }, "title": "Scope", "type": "array" } }, "required": [ "document_id", "framework" ], "title": "ReviewComplianceInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "review_compliance" }, "output": { "$defs": { "Finding": { "properties": { "area": { "title": "Area", "type": "string" }, "description": { "title": "Description", "type": "string" }, "severity": { "default": "info", "title": "Severity", "type": "string" }, "recommendation": { "default": "", "title": "Recommendation", "type": "string" } }, "required": [ "area", "description" ], "title": "Finding", "type": "object" } }, "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "status": { "default": "", "title": "Status", "type": "string" }, "findings": { "items": { "$ref": "#/$defs/Finding" }, "title": "Findings", "type": "array" }, "risk_level": { "default": "low", "title": "Risk Level", "type": "string" }, "recommendations": { "items": { "type": "string" }, "title": "Recommendations", "type": "array" }, "coverage_pct": { "default": 0.0, "title": "Coverage Pct", "type": "number" } }, "title": "ReviewComplianceOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/controls.test/invoke": { "post": { "operationId": "invokeSkill_controls_test", "summary": "Test internal controls \u2014 design or operating effectiveness, sample selection, exceptions.", "tags": [ "audit" ], "x-skill-name": "controls.test", "x-skill-slug": "test_controls", "x-skill-category": "audit", "x-skill-cluster": "ASR", "x-skill-streaming": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "client_id": { "format": "uuid", "title": "Client Id", "type": "string" }, "control_set": { "default": "payment_authorisation", "enum": [ "payment_authorisation", "journal_approval", "user_access", "segregation_of_duties", "expense_approval", "custom" ], "title": "Control Set", "type": "string" }, "test_type": { "default": "operating", "enum": [ "design", "operating", "both" ], "title": "Test Type", "type": "string" }, "sample_size": { "default": 25, "title": "Sample Size", "type": "integer" }, "period": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Period" }, "custom_controls": { "items": { "type": "string" }, "title": "Custom Controls", "type": "array" } }, "required": [ "client_id" ], "title": "TestControlsInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "test_controls" }, "output": { "$defs": { "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" }, "ControlTest": { "description": "Single control-testing result row.", "properties": { "control_id": { "title": "Control Id", "type": "string" }, "description": { "default": "", "title": "Description", "type": "string" }, "test_type": { "default": "operating", "enum": [ "design", "operating" ], "title": "Test Type", "type": "string" }, "sample_size": { "default": 0, "title": "Sample Size", "type": "integer" }, "exceptions": { "default": 0, "title": "Exceptions", "type": "integer" }, "conclusion": { "default": "n/a", "enum": [ "effective", "deficient", "material_weakness", "n/a" ], "title": "Conclusion", "type": "string" } }, "required": [ "control_id" ], "title": "ControlTest", "type": "object" }, "Finding": { "properties": { "area": { "title": "Area", "type": "string" }, "description": { "title": "Description", "type": "string" }, "severity": { "default": "info", "title": "Severity", "type": "string" }, "recommendation": { "default": "", "title": "Recommendation", "type": "string" } }, "required": [ "area", "description" ], "title": "Finding", "type": "object" } }, "properties": { "artifact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Artifact Id" }, "download_url": { "default": "", "title": "Download Url", "type": "string" }, "summary": { "default": "", "title": "Summary", "type": "string" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "test_id": { "format": "uuid", "title": "Test Id", "type": "string" }, "overall_conclusion": { "default": "effective", "enum": [ "effective", "deficient", "material_weakness" ], "title": "Overall Conclusion", "type": "string" }, "controls_tested": { "items": { "$ref": "#/$defs/ControlTest" }, "title": "Controls Tested", "type": "array" }, "exceptions": { "items": { "$ref": "#/$defs/Finding" }, "title": "Exceptions", "type": "array" }, "recommendations": { "items": { "type": "string" }, "title": "Recommendations", "type": "array" } }, "title": "TestControlsOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/derive.period/invoke": { "post": { "operationId": "invokeSkill_derive_period", "summary": "(Utility) Derive canonical period bounds + matching prior-period bounds from a kind discriminator + anchor date. Pure compute \u2014 same input always produces identical output. Supports BAS-AU monthly/quarterly/annual today; additional jurisdictions are new ``kind`` values.", "tags": [ "utility" ], "x-skill-name": "derive.period", "x-skill-slug": "derive_period", "x-skill-category": "utility", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$defs": { "PeriodKind": { "description": "Discriminator for the period rule to apply.\n\nPer-jurisdiction kinds are explicit (no implicit \"monthly\" that means\ndifferent things in different jurisdictions). Add a new entry +\na branch in :func:`_compute_range` to support a new jurisdiction.", "enum": [ "bas_au_monthly", "bas_au_quarterly", "bas_au_annual" ], "title": "PeriodKind", "type": "string" } }, "additionalProperties": false, "description": "Skill input \u2014 kind + anchor_date.\n\n``anchor_date`` can be any date within the target period (typically\nthe period end, but the rule handles any in-range date correctly).\nSame ``(kind, anchor_date)`` always produces identical output bytes\nso callers can cache by the input fingerprint if they want.", "properties": { "kind": { "$ref": "#/$defs/PeriodKind" }, "anchor_date": { "format": "date", "title": "Anchor Date", "type": "string" } }, "required": [ "kind", "anchor_date" ], "title": "DerivePeriodInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "derive_period" }, "output": { "$defs": { "PeriodKind": { "description": "Discriminator for the period rule to apply.\n\nPer-jurisdiction kinds are explicit (no implicit \"monthly\" that means\ndifferent things in different jurisdictions). Add a new entry +\na branch in :func:`_compute_range` to support a new jurisdiction.", "enum": [ "bas_au_monthly", "bas_au_quarterly", "bas_au_annual" ], "title": "PeriodKind", "type": "string" } }, "additionalProperties": false, "description": "Skill output \u2014 period bounds + matching prior-period bounds.\n\nAll date fields are ISO strings so they substitute cleanly into Jinja2\ntemplates in WDL (``{{ outputs.derive_period.period_start }}``)\nwithout ``date`` repr surprises.\n\nPrior period: the unique period of the same kind immediately\npreceding the current one \u2014 useful for comparatives. For BAS this is\nthe prior month / prior FY quarter / prior FY.", "properties": { "kind": { "$ref": "#/$defs/PeriodKind" }, "anchor_date": { "title": "Anchor Date", "type": "string" }, "period_start": { "title": "Period Start", "type": "string" }, "period_end": { "title": "Period End", "type": "string" }, "period_label": { "title": "Period Label", "type": "string" }, "prior_period_start": { "title": "Prior Period Start", "type": "string" }, "prior_period_end": { "title": "Prior Period End", "type": "string" }, "prior_period_label": { "title": "Prior Period Label", "type": "string" }, "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" } }, "required": [ "kind", "anchor_date", "period_start", "period_end", "period_label", "prior_period_start", "prior_period_end", "prior_period_label" ], "title": "DerivePeriodOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/detect.tb.duplicates/invoke": { "post": { "operationId": "invokeSkill_detect_tb_duplicates", "summary": "(Utility) Surface trial-balance rows that share an ``account_number`` (``code``) with another non-zero-balance row. Zero-balance rows are excluded from the duplicate check \u2014 a stale inactive account sharing a code with a real one does NOT poison the real one. Output is the conflict subset with ``conflict_codes`` + ``conflict_count`` added per row.", "tags": [ "utility" ], "x-skill-name": "detect.tb.duplicates", "x-skill-slug": "detect_tb_duplicates", "x-skill-category": "utility", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Envelope for ``detect_tb_duplicates`` \u2014 TB rows to scan.", "properties": { "rows": { "items": { "additionalProperties": true, "type": "object" }, "title": "Rows", "type": "array" } }, "title": "DetectTbDuplicatesInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "detect_tb_duplicates" }, "output": { "description": "Envelope for ``detect_tb_duplicates`` output \u2014 the conflict subset\nwith ``conflict_codes`` + ``conflict_count`` added per row.", "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "duplicates": { "items": { "additionalProperties": true, "type": "object" }, "title": "Duplicates", "type": "array" } }, "title": "DetectTbDuplicatesOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/documents.analyse/invoke": { "post": { "operationId": "invokeSkill_documents_analyse", "summary": "Analyse an uploaded document \u2014 summarise, extract figures, classify, risk-assess.", "tags": [ "analysis" ], "x-skill-name": "documents.analyse", "x-skill-slug": "analyse_document", "x-skill-category": "analysis", "x-skill-cluster": "", "x-skill-streaming": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "file_id": { "format": "uuid", "title": "File Id", "type": "string" }, "analysis_type": { "default": "summarize", "enum": [ "summarize", "extract_figures", "classify", "risk_assess" ], "title": "Analysis Type", "type": "string" } }, "required": [ "file_id" ], "title": "AnalyseDocumentInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "analyse_document" }, "output": { "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "analysis": { "title": "Analysis", "type": "string" }, "extracted_data": { "additionalProperties": true, "title": "Extracted Data", "type": "object" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "analysis" ], "title": "AnalyseDocumentOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/enrich.tb.rows/invoke": { "post": { "operationId": "invokeSkill_enrich_tb_rows", "summary": "(Utility) Enrich a trial balance with auto-renumber + classification. Operates on alpha's canonical TB-row dict shape (``{code, name, section, debit, credit}``) and CoA-row dict shape (``{account_id, code, name, type, balance}``). Adds ``classification`` \u2208 ``ok|auto_renumbered|dropped|needs_manual_review``, assigns Maginot-style numbers (1xxx Assets / 2xxx Liabilities / ...) to rows missing a code, flags duplicate-code collisions for manual review, drops zero-balance rows. Pure compute \u2014 same input always produces identical output. Does NOT re-implement the balance check; that remains inline at the 5 existing sites.", "tags": [ "utility" ], "x-skill-name": "enrich.tb.rows", "x-skill-slug": "enrich_tb_rows", "x-skill-category": "utility", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Envelope for ``enrich_tb_rows`` \u2014 alpha-canonical TB + CoA dicts.", "properties": { "tb_rows": { "items": { "additionalProperties": true, "type": "object" }, "title": "Tb Rows", "type": "array" }, "coa_rows": { "items": { "additionalProperties": true, "type": "object" }, "title": "Coa Rows", "type": "array" } }, "title": "EnrichTbRowsInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "enrich_tb_rows" }, "output": { "description": "Envelope for ``enrich_tb_rows`` output \u2014 same dict shape as input\nrows with added ``classification`` / ``original_code`` /\n``auto_assigned_code`` / ``drop_reason`` keys.", "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "rows": { "items": { "additionalProperties": true, "type": "object" }, "title": "Rows", "type": "array" } }, "title": "EnrichTbRowsOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/estate.review/invoke": { "post": { "operationId": "invokeSkill_estate_review", "summary": "Review wills, trusts, beneficiaries, control, and tax exposure of an estate plan.", "tags": [ "review" ], "x-skill-name": "estate.review", "x-skill-slug": "review_estate_structure", "x-skill-category": "review", "x-skill-cluster": "WLT", "x-skill-streaming": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "file_ids": { "items": { "format": "uuid", "type": "string" }, "title": "File Ids", "type": "array" }, "jurisdiction": { "anyOf": [ { "enum": [ "AU", "GB", "CA", "US", "NZ" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Jurisdiction" }, "review_mode": { "default": "full", "enum": [ "full", "tax_only", "control_only", "trust_only" ], "title": "Review Mode", "type": "string" }, "client_context": { "additionalProperties": true, "title": "Client Context", "type": "object" } }, "title": "ReviewEstateStructureInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "review_estate_structure" }, "output": { "$defs": { "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" }, "Finding": { "properties": { "area": { "title": "Area", "type": "string" }, "description": { "title": "Description", "type": "string" }, "severity": { "default": "info", "title": "Severity", "type": "string" }, "recommendation": { "default": "", "title": "Recommendation", "type": "string" } }, "required": [ "area", "description" ], "title": "Finding", "type": "object" } }, "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "summary": { "default": "", "title": "Summary", "type": "string" }, "findings": { "items": { "$ref": "#/$defs/Finding" }, "title": "Findings", "type": "array" }, "recommendations": { "items": { "type": "string" }, "title": "Recommendations", "type": "array" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" }, "risk_level": { "default": "low", "enum": [ "low", "medium", "high" ], "title": "Risk Level", "type": "string" } }, "title": "ReviewEstateStructureOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/financials.analyse/invoke": { "post": { "operationId": "invokeSkill_financials_analyse", "summary": "Analyse client financials \u2014 variance, trend, ratio, cashflow, profitability, or working capital.", "tags": [ "analysis" ], "x-skill-name": "financials.analyse", "x-skill-slug": "analyse_financials", "x-skill-category": "analysis", "x-skill-cluster": "ASR", "x-skill-streaming": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "client_id": { "format": "uuid", "title": "Client Id", "type": "string" }, "analysis_type": { "default": "variance", "enum": [ "variance", "trend", "ratio", "cashflow", "profitability", "working_capital" ], "title": "Analysis Type", "type": "string" }, "period": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Period" }, "compare_period": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Compare Period" } }, "required": [ "client_id" ], "title": "AnalyseFinancialsInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "analyse_financials" }, "output": { "$defs": { "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" }, "Finding": { "properties": { "area": { "title": "Area", "type": "string" }, "description": { "title": "Description", "type": "string" }, "severity": { "default": "info", "title": "Severity", "type": "string" }, "recommendation": { "default": "", "title": "Recommendation", "type": "string" } }, "required": [ "area", "description" ], "title": "Finding", "type": "object" }, "Trend": { "properties": { "metric": { "title": "Metric", "type": "string" }, "direction": { "title": "Direction", "type": "string" }, "change_pct": { "default": 0.0, "title": "Change Pct", "type": "number" } }, "required": [ "metric", "direction" ], "title": "Trend", "type": "object" } }, "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "analysis": { "default": "", "title": "Analysis", "type": "string" }, "metrics": { "additionalProperties": true, "title": "Metrics", "type": "object" }, "trends": { "items": { "$ref": "#/$defs/Trend" }, "title": "Trends", "type": "array" }, "findings": { "items": { "$ref": "#/$defs/Finding" }, "title": "Findings", "type": "array" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "title": "AnalyseFinancialsOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/get.meeting.record/invoke": { "post": { "operationId": "invokeSkill_get_meeting_record", "summary": "(Utility) Fetch meeting record including transcript and short-lived recording URL.", "tags": [ "utility" ], "x-skill-name": "get.meeting.record", "x-skill-slug": "get_meeting_record", "x-skill-category": "utility", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "session_id": { "format": "uuid", "title": "Session Id", "type": "string" } }, "required": [ "session_id" ], "title": "GetMeetingRecordInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "get_meeting_record" }, "output": { "$defs": { "MeetingTranscriptSegment": { "properties": { "sequence_number": { "title": "Sequence Number", "type": "integer" }, "speaker": { "default": "", "title": "Speaker", "type": "string" }, "start": { "default": 0.0, "title": "Start", "type": "number" }, "end": { "default": 0.0, "title": "End", "type": "number" }, "text": { "default": "", "title": "Text", "type": "string" } }, "required": [ "sequence_number" ], "title": "MeetingTranscriptSegment", "type": "object" } }, "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "session_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Session Id" }, "title": { "default": "", "title": "Title", "type": "string" }, "start": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Start" }, "end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "End" }, "status": { "default": "", "title": "Status", "type": "string" }, "participant_count": { "default": 0, "title": "Participant Count", "type": "integer" }, "has_recording": { "default": false, "title": "Has Recording", "type": "boolean" }, "has_transcript": { "default": false, "title": "Has Transcript", "type": "boolean" }, "recording_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Recording Url" }, "transcript": { "items": { "$ref": "#/$defs/MeetingTranscriptSegment" }, "title": "Transcript", "type": "array" } }, "title": "GetMeetingRecordOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/journal.record/invoke": { "post": { "operationId": "invokeSkill_journal_record", "summary": "Record an accounting journal entry to Xero/QBO.", "tags": [ "transactions" ], "x-skill-name": "journal.record", "x-skill-slug": "record_journal_entry", "x-skill-category": "transactions", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$defs": { "JournalLine": { "description": "Single journal line \u2014 bound by double-entry accounting invariants.\n\nL1 validators (gpt-5.5-pro v2 review):\n\n* ``debit`` and ``credit`` must be non-negative.\n* Exactly one of ``debit``/``credit`` must be non-zero (zero-value lines\n and lines carrying both sides are rejected \u2014 the double-entry sign would\n be ambiguous).", "properties": { "account_code": { "title": "Account Code", "type": "string" }, "description": { "default": "", "title": "Description", "type": "string" }, "debit": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ], "default": "0", "title": "Debit" }, "credit": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ], "default": "0", "title": "Credit" } }, "required": [ "account_code" ], "title": "JournalLine", "type": "object" } }, "properties": { "client_id": { "format": "uuid", "title": "Client Id", "type": "string" }, "entries": { "items": { "$ref": "#/$defs/JournalLine" }, "minItems": 2, "title": "Entries", "type": "array" }, "memo": { "default": "", "title": "Memo", "type": "string" }, "entry_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "default": null, "title": "Entry Date" }, "idempotency_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Idempotency Key" } }, "required": [ "client_id", "entries" ], "title": "RecordJournalEntryInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "record_journal_entry" }, "output": { "$defs": { "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" } }, "properties": { "artifact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Artifact Id" }, "download_url": { "default": "", "title": "Download Url", "type": "string" }, "summary": { "default": "", "title": "Summary", "type": "string" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "journal_id": { "format": "uuid", "title": "Journal Id", "type": "string" }, "status": { "default": "queued", "enum": [ "queued", "pending_approval", "dry_run", "created", "rejected_unbalanced", "failed" ], "title": "Status", "type": "string" }, "total_debits": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ], "default": "0", "title": "Total Debits" }, "total_credits": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ], "default": "0", "title": "Total Credits" }, "balanced": { "default": false, "title": "Balanced", "type": "boolean" }, "erp": { "anyOf": [ { "enum": [ "xero", "qbo", "sage", "internal" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Erp" }, "archive_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ERP-assigned reference (e.g. Xero JournalNumber, QBO Id) for re-fetch.", "title": "Archive Reference" }, "reversal_created": { "default": false, "title": "Reversal Created", "type": "boolean" }, "reversal_journal_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Reversal Journal Id" } }, "title": "RecordJournalEntryOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/list.connections/invoke": { "post": { "operationId": "invokeSkill_list_connections", "summary": "List the caller's connected accounting systems (Xero today) and their data-sync health \u2014 answers 'what am I connected to', 'is my Xero connected', 'did the sync finish'. Returns each connection's tenant name, type, status, last sync time, and per-entity sync_state (written/failed per entity). No parameters.", "tags": [ "integrations" ], "x-skill-name": "list.connections", "x-skill-slug": "list_connections", "x-skill-category": "integrations", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "No parameters \u2014 returns every accounting connection for the caller's org.", "properties": {}, "title": "ListConnectionsInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "list_connections" }, "output": { "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "found": { "default": 0, "description": "Number of connections found for the caller's org", "title": "Found", "type": "integer" }, "connections": { "description": "Per-connection status + per-entity sync_state (tenant name, connection type, status, last sync time, written/failed per entity).", "items": { "additionalProperties": true, "type": "object" }, "title": "Connections", "type": "array" }, "note": { "default": "", "description": "Human-readable note (e.g. when no connections exist)", "title": "Note", "type": "string" } }, "title": "ListConnectionsOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/list.meetings/invoke": { "post": { "operationId": "invokeSkill_list_meetings", "summary": "(Utility) List accessible meetings in the workspace.", "tags": [ "utility" ], "x-skill-name": "list.meetings", "x-skill-slug": "list_meetings", "x-skill-category": "utility", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "limit": { "default": 50, "title": "Limit", "type": "integer" }, "offset": { "default": 0, "title": "Offset", "type": "integer" } }, "title": "ListMeetingsInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "list_meetings" }, "output": { "$defs": { "MeetingItem": { "properties": { "id": { "format": "uuid", "title": "Id", "type": "string" }, "title": { "default": "", "title": "Title", "type": "string" }, "start": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Start" }, "end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "End" }, "participant_count": { "default": 0, "title": "Participant Count", "type": "integer" }, "has_recording": { "default": false, "title": "Has Recording", "type": "boolean" }, "has_transcript": { "default": false, "title": "Has Transcript", "type": "boolean" } }, "required": [ "id" ], "title": "MeetingItem", "type": "object" } }, "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "meetings": { "items": { "$ref": "#/$defs/MeetingItem" }, "title": "Meetings", "type": "array" }, "total_count": { "default": 0, "title": "Total Count", "type": "integer" }, "has_more": { "default": false, "title": "Has More", "type": "boolean" } }, "title": "ListMeetingsOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/meeting.followup/invoke": { "post": { "operationId": "invokeSkill_meeting_followup", "summary": "Extract action items, decisions, and a follow-up email draft from a meeting transcript or uploaded recording. Read-only \u2014 the user reviews and sends the draft. Pairs with meeting.prep.", "tags": [ "communication" ], "x-skill-name": "meeting.followup", "x-skill-slug": "meeting_followup", "x-skill-category": "communication", "x-skill-cluster": "XCT", "x-skill-streaming": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "client_id": { "format": "uuid", "title": "Client Id", "type": "string" }, "meeting_date": { "format": "date", "title": "Meeting Date", "type": "string" }, "transcript": { "default": "", "description": "Pasted/typed transcript or notes. Empty when relying on file_ids.", "title": "Transcript", "type": "string" }, "file_ids": { "description": "Uploaded transcript / recording / notes documents.", "items": { "format": "uuid", "type": "string" }, "title": "File Ids", "type": "array" }, "attendees": { "items": { "type": "string" }, "title": "Attendees", "type": "array" }, "agenda_topics_covered": { "items": { "type": "string" }, "title": "Agenda Topics Covered", "type": "array" }, "draft_email": { "default": true, "description": "When True, the LLM emits a follow-up email draft alongside action items.", "title": "Draft Email", "type": "boolean" } }, "required": [ "client_id", "meeting_date" ], "title": "MeetingFollowupInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "meeting_followup" }, "output": { "$defs": { "ActionItem": { "description": "A single action extracted from the meeting transcript.", "properties": { "description": { "title": "Description", "type": "string" }, "owner": { "default": "", "description": "Who owns the action; free-form.", "title": "Owner", "type": "string" }, "due_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "default": null, "title": "Due Date" }, "priority": { "default": "medium", "enum": [ "urgent", "high", "medium", "low" ], "title": "Priority", "type": "string" } }, "required": [ "description" ], "title": "ActionItem", "type": "object" }, "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" } }, "properties": { "artifact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Artifact Id" }, "download_url": { "default": "", "title": "Download Url", "type": "string" }, "summary": { "default": "", "title": "Summary", "type": "string" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "action_items": { "items": { "$ref": "#/$defs/ActionItem" }, "title": "Action Items", "type": "array" }, "decisions": { "items": { "type": "string" }, "title": "Decisions", "type": "array" }, "follow_up_email_draft": { "default": "", "description": "Markdown/plain-text draft; empty when draft_email=False.", "title": "Follow Up Email Draft", "type": "string" }, "next_meeting_suggested": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "default": null, "title": "Next Meeting Suggested" } }, "title": "MeetingFollowupOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/meeting.prep/invoke": { "post": { "operationId": "invokeSkill_meeting_prep", "summary": "Produce a pre-meeting briefing for a client meeting \u2014 recent topics, open action items, talking points, suggested questions. Read-only; pairs with meeting.followup for the post-meeting half.", "tags": [ "communication" ], "x-skill-name": "meeting.prep", "x-skill-slug": "meeting_prep", "x-skill-category": "communication", "x-skill-cluster": "XCT", "x-skill-streaming": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "client_id": { "format": "uuid", "title": "Client Id", "type": "string" }, "meeting_date": { "format": "date", "title": "Meeting Date", "type": "string" }, "meeting_type": { "default": "quarterly_review", "enum": [ "initial", "quarterly_review", "annual", "planning", "advisory_board", "ad_hoc" ], "title": "Meeting Type", "type": "string" }, "attendees": { "description": "Optional attendee names \u2014 drives addressee-aware talking points.", "items": { "type": "string" }, "title": "Attendees", "type": "array" }, "agenda_topics": { "description": "If provided, focus on these topics rather than scanning broadly.", "items": { "type": "string" }, "title": "Agenda Topics", "type": "array" }, "lookback_days": { "default": 90, "description": "Trailing window of comms/topics/workstream activity to summarise.", "maximum": 365, "minimum": 1, "title": "Lookback Days", "type": "integer" } }, "required": [ "client_id", "meeting_date" ], "title": "MeetingPrepInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "meeting_prep" }, "output": { "$defs": { "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" } }, "properties": { "artifact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Artifact Id" }, "download_url": { "default": "", "title": "Download Url", "type": "string" }, "summary": { "default": "", "title": "Summary", "type": "string" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "briefing_text": { "default": "", "description": "Long-form briefing in markdown \u2014 readable version of the artifact.", "title": "Briefing Text", "type": "string" }, "talking_points": { "items": { "type": "string" }, "title": "Talking Points", "type": "array" }, "recent_topics": { "description": "Recent topics surfaced from KB / comms \u2014 each entry: {'topic': str, 'last_touched': YYYY-MM-DD}.", "items": { "additionalProperties": true, "type": "object" }, "title": "Recent Topics", "type": "array" }, "open_action_items": { "items": { "type": "string" }, "title": "Open Action Items", "type": "array" }, "suggested_questions": { "items": { "type": "string" }, "title": "Suggested Questions", "type": "array" } }, "title": "MeetingPrepOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/memos.expert.prepare/invoke": { "post": { "operationId": "invokeSkill_memos_expert_prepare", "summary": "Prepare a litigation expert report \u2014 damages, loss quantification, opinion.", "tags": [ "memo" ], "x-skill-name": "memos.expert.prepare", "x-skill-slug": "prepare_expert_report", "x-skill-category": "memo", "x-skill-cluster": "ASR", "x-skill-streaming": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "client_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Client Id" }, "matter_type": { "default": "damages", "enum": [ "damages", "loss_quantification", "valuation_dispute", "fraud_opinion", "professional_negligence" ], "title": "Matter Type", "type": "string" }, "file_ids": { "items": { "format": "uuid", "type": "string" }, "title": "File Ids", "type": "array" }, "scenario": { "maxLength": 5000, "title": "Scenario", "type": "string" }, "jurisdiction": { "anyOf": [ { "enum": [ "AU", "GB", "CA", "US", "NZ" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Jurisdiction" }, "professional_standard": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Professional Standard" } }, "required": [ "scenario" ], "title": "PrepareExpertReportInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "prepare_expert_report" }, "output": { "$defs": { "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" } }, "properties": { "artifact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Artifact Id" }, "download_url": { "default": "", "title": "Download Url", "type": "string" }, "executive_summary": { "default": "", "title": "Executive Summary", "type": "string" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "methodology": { "default": "", "title": "Methodology", "type": "string" }, "quantum": { "additionalProperties": true, "title": "Quantum", "type": "object" }, "limitations": { "items": { "type": "string" }, "title": "Limitations", "type": "array" } }, "title": "PrepareExpertReportOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/messages.create/invoke": { "post": { "operationId": "invokeSkill_messages_create", "summary": "General accounting question \u2014 fallback for anything that doesn't fit a specific skill.", "tags": [ "general" ], "x-skill-name": "messages.create", "x-skill-slug": "ask_archie", "x-skill-category": "general", "x-skill-cluster": "", "x-skill-streaming": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "query": { "maxLength": 10000, "title": "Query", "type": "string" }, "context_ids": { "items": { "format": "uuid", "type": "string" }, "title": "Context Ids", "type": "array" }, "locale": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Locale" }, "jurisdiction": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Jurisdiction" } }, "required": [ "query" ], "title": "AskArchieInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "ask_archie" }, "output": { "$defs": { "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" } }, "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "answer": { "title": "Answer", "type": "string" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" }, "model_used": { "default": "", "title": "Model Used", "type": "string" } }, "required": [ "answer" ], "title": "AskArchieOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/payroll.advise/invoke": { "post": { "operationId": "invokeSkill_payroll_advise", "summary": "Payroll compliance advice \u2014 STP/RTI/SGC, contractor classification, payroll tax.", "tags": [ "advisory" ], "x-skill-name": "payroll.advise", "x-skill-slug": "advise_payroll", "x-skill-category": "advisory", "x-skill-cluster": "PAY", "x-skill-streaming": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "topic": { "maxLength": 5000, "title": "Topic", "type": "string" }, "jurisdiction": { "anyOf": [ { "enum": [ "AU", "GB", "CA", "US", "NZ" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Jurisdiction" }, "client_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Client Id" }, "payroll_system": { "default": "unknown", "enum": [ "xero", "adp", "gusto", "rippling", "myob", "unknown" ], "title": "Payroll System", "type": "string" } }, "required": [ "topic" ], "title": "AdvisePayrollInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "advise_payroll" }, "output": { "$defs": { "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" } }, "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "advice": { "default": "", "title": "Advice", "type": "string" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" }, "data": { "additionalProperties": true, "title": "Data", "type": "object" }, "caveats": { "items": { "type": "string" }, "title": "Caveats", "type": "array" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "title": "AdvisePayrollOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/payroll.data.get/invoke": { "post": { "operationId": "invokeSkill_payroll_data_get", "summary": "Get payroll data \u2014 summary, by employee, by period, tax/super obligations.", "tags": [ "data" ], "x-skill-name": "payroll.data.get", "x-skill-slug": "get_payroll_data", "x-skill-category": "data", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "client_id": { "format": "uuid", "title": "Client Id", "type": "string" }, "view": { "default": "summary", "enum": [ "summary", "by_employee", "by_period", "tax_liabilities", "super_obligations" ], "title": "View", "type": "string" }, "period": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Period" }, "employee_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Employee Id" } }, "required": [ "client_id" ], "title": "GetPayrollDataInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "get_payroll_data" }, "output": { "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "view": { "default": "", "title": "View", "type": "string" }, "data": { "additionalProperties": true, "title": "Data", "type": "object" }, "period": { "default": "", "title": "Period", "type": "string" }, "currency": { "default": "AUD", "title": "Currency", "type": "string" }, "source": { "default": "", "title": "Source", "type": "string" } }, "title": "GetPayrollDataOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/playbook.creator/invoke": { "post": { "operationId": "invokeSkill_playbook_creator", "summary": "Draft a new workstream conversationally \u2014 describe a workflow and Archie produces a structured, reviewable workstream draft with typed steps, dependencies, and validation. Legacy slug retained for back-compat; prefer `workstream.draft` for new integrations.", "tags": [ "authoring" ], "x-skill-name": "playbook.creator", "x-skill-slug": "playbook_creator", "x-skill-category": "authoring", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Input for the conversational workstream drafting skill.\n\nA natural-language ``description`` is required. ``topic_id`` anchors the\ndraft to a Topic so subsequent messages in that Topic regenerate the same\ndraft. ``prior_draft_id`` lets the caller iterate on an existing draft\nrather than starting fresh.\n\n(Class name retained for SDK back-compat; the skill produces Workstream\ndrafts since the Phase-7 unification 2026-05-10.)", "properties": { "description": { "description": "Natural-language description of the workflow to draft.", "minLength": 1, "title": "Description", "type": "string" }, "topic_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Topic to anchor the draft to \u2014 permakey (preferred) or UUID.", "title": "Topic Id" }, "prior_draft_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional prior draft to iterate on instead of creating a new one.", "title": "Prior Draft Id" } }, "required": [ "description" ], "title": "WorkstreamCreatorInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "playbook_creator" }, "output": { "description": "Output from the workstream drafting skill \u2014 pointer to the draft + summary.\n\n``draft_id`` is None when the request couldn't produce a draft (missing\nworkspace / topic / generation failure); in that case ``error`` carries\na one-line reason. Successful invocations always set ``draft_id``.", "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "draft_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Draft Id" }, "name": { "default": "", "title": "Name", "type": "string" }, "step_count": { "default": 0, "title": "Step Count", "type": "integer" }, "validation_warning_count": { "default": 0, "title": "Validation Warning Count", "type": "integer" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" } }, "title": "WorkstreamCreatorOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/portfolios.analyse/invoke": { "post": { "operationId": "invokeSkill_portfolios_analyse", "summary": "Analyse an investment portfolio \u2014 opening/closing reconciliation, FX and fair-value movements, capital gains/losses, and journal generation. Used by Family Investment Company (FIC) analysis (UK), trust accounts, personal SIPP/ISA reviews, and other wealth workstreams across UK, AU, US, CA jurisdictions. Currency-agnostic; the workstream step supplies jurisdiction-specific parameters such as the annual exempt amount.", "tags": [ "analysis" ], "x-skill-name": "portfolios.analyse", "x-skill-slug": "analyse_investment_portfolio", "x-skill-category": "analysis", "x-skill-cluster": "WLT", "x-skill-streaming": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "topic": { "maxLength": 5000, "title": "Topic", "type": "string" }, "jurisdiction": { "anyOf": [ { "enum": [ "AU", "GB", "CA", "US", "NZ" ], "type": "string" }, { "type": "null" } ], "default": "GB", "title": "Jurisdiction" }, "period": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Period" }, "entity_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Entity Name" }, "client_context": { "additionalProperties": true, "title": "Client Context", "type": "object" } }, "required": [ "topic" ], "title": "AnalyseInvestmentPortfolioInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "analyse_investment_portfolio" }, "output": { "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "analysis": { "default": "", "title": "Analysis", "type": "string" }, "summary": { "default": "", "title": "Summary", "type": "string" }, "findings": { "items": { "type": "string" }, "title": "Findings", "type": "array" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "title": "AnalyseInvestmentPortfolioOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/prepare.asc360.memo/invoke": { "post": { "operationId": "invokeSkill_prepare_asc360_memo", "summary": "Prepare an ASC 360 capex memo (PP&E capitalise-vs-expense, depreciation, impairment). Deterministic engine: capitalised cost = sum of GROUNDED cost components; depreciation = depreciable base / useful life; impairment via the recoverability test. An ungrounded capitalisation policy or cost component is FLAGGED for partner input \u2014 never printed as a cost.", "tags": [ "reports" ], "x-skill-name": "prepare.asc360.memo", "x-skill-slug": "prepare_asc360_memo", "x-skill-category": "reports", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$defs": { "Asc360CostComponent": { "description": "One grounded capitalisable cost component.", "properties": { "label": { "title": "Label", "type": "string" }, "amount": { "anyOf": [ { "type": "number" }, { "type": "integer" } ], "title": "Amount" }, "quote": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Quote" }, "file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "File Id" }, "asserted_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Asserted By" }, "note": { "default": "", "title": "Note", "type": "string" } }, "required": [ "label", "amount" ], "title": "Asc360CostComponent", "type": "object" }, "Asc360ImpairmentInput": { "description": "A grounded ASC 360 impairment input (carrying amount / sum of undiscounted\ncash flows / fair value): amount + verbatim quote/file_id or a named assertor.\nA plain number is also accepted on the field (back-compat) but arrives\nUNGROUNDED \u2014 the impairment conclusion is then withheld unless the figure\nself-grounds from the document set.", "properties": { "amount": { "anyOf": [ { "type": "number" }, { "type": "integer" } ], "title": "Amount" }, "quote": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Quote" }, "file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "File Id" }, "asserted_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Asserted By" }, "note": { "default": "", "title": "Note", "type": "string" } }, "required": [ "amount" ], "title": "Asc360ImpairmentInput", "type": "object" }, "Asc842GroundedScalar": { "description": "Grounding for a scalar lease input (the rate / the base-rent clause).", "properties": { "quote": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Quote" }, "file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "File Id" }, "asserted_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Asserted By" }, "note": { "default": "", "title": "Note", "type": "string" } }, "title": "Asc842GroundedScalar", "type": "object" } }, "properties": { "subject_entity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Subject Entity" }, "cost_components": { "items": { "$ref": "#/$defs/Asc360CostComponent" }, "title": "Cost Components", "type": "array" }, "capitalisation_policy": { "anyOf": [ { "$ref": "#/$defs/Asc842GroundedScalar" }, { "type": "null" } ], "default": null }, "salvage_value": { "anyOf": [ { "type": "number" }, { "type": "integer" } ], "default": 0, "title": "Salvage Value" }, "useful_life": { "title": "Useful Life", "type": "integer" }, "lhi_cost": { "anyOf": [ { "type": "number" }, { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Lhi Cost" }, "lhi_useful_life": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Lhi Useful Life" }, "remaining_lease_term": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Remaining Lease Term" }, "carrying_amount": { "anyOf": [ { "type": "number" }, { "type": "integer" }, { "$ref": "#/$defs/Asc360ImpairmentInput" }, { "type": "null" } ], "default": null, "title": "Carrying Amount" }, "sum_undiscounted_cash_flows": { "anyOf": [ { "type": "number" }, { "type": "integer" }, { "$ref": "#/$defs/Asc360ImpairmentInput" }, { "type": "null" } ], "default": null, "title": "Sum Undiscounted Cash Flows" }, "fair_value": { "anyOf": [ { "type": "number" }, { "type": "integer" }, { "$ref": "#/$defs/Asc360ImpairmentInput" }, { "type": "null" } ], "default": null, "title": "Fair Value" } }, "required": [ "cost_components", "useful_life" ], "title": "Asc360CapexInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "prepare_asc360_memo" }, "output": { "$defs": { "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" } }, "properties": { "artifact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Artifact Id" }, "download_url": { "default": "", "title": "Download Url", "type": "string" }, "summary": { "default": "", "title": "Summary", "type": "string" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "capitalised_cost": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Capitalised Cost" }, "annual_depreciation": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Annual Depreciation" }, "verification_status": { "default": "", "title": "Verification Status", "type": "string" }, "impairment_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The impairment conclusion's OWN grounding gate. None = no impairment test ran; 'passed' = the impairment inputs grounded and the conclusion is stated; 'failed_quote_grounding' = an impairment input did not ground (named in blocked_inputs) and the conclusion is withheld \u2014 verification_status covers ONLY the capitalised cost and can still be 'passed' on a blocked-impairment run.", "title": "Impairment Status" }, "memo_sections": { "items": { "additionalProperties": true, "type": "object" }, "title": "Memo Sections", "type": "array" }, "blocked_inputs": { "items": { "type": "string" }, "title": "Blocked Inputs", "type": "array" } }, "title": "Asc360CapexOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/prepare.asc606.memo/invoke": { "post": { "operationId": "invokeSkill_prepare_asc606_memo", "summary": "Prepare an ASC 606 revenue-recognition workpaper + memo. Supply either an uploaded contract (file_ids) OR the full contract text as scenario \u2014 the engine extracts payment streams, parties, term, and royalty tiers from the text inline. No file upload needed when scenario contains the contract text.", "tags": [ "memo" ], "x-skill-name": "prepare.asc606.memo", "x-skill-slug": "prepare_asc606_memo", "x-skill-category": "memo", "x-skill-cluster": "ASR", "x-skill-streaming": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "file_ids": { "description": "Optional Archie file IDs for uploaded contract PDFs. If empty, the engine synthesises the brief from scenario alone.", "items": { "format": "uuid", "type": "string" }, "title": "File Ids", "type": "array" }, "scenario": { "default": "", "description": "Full contract text OR a detailed arrangement description. When file_ids is empty, the engine synthesises the document brief directly from this text \u2014 paste the contract verbatim. When file_ids is present, a short description suffices.", "maxLength": 100000, "title": "Scenario", "type": "string" }, "questions": { "items": { "type": "string" }, "title": "Questions", "type": "array" }, "jurisdiction": { "anyOf": [ { "enum": [ "AU", "GB", "CA", "US", "NZ" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Jurisdiction" }, "framework": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Framework" } }, "title": "MemoInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "prepare_asc606_memo" }, "output": { "$defs": { "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" } }, "properties": { "artifact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Artifact Id" }, "download_url": { "default": "", "title": "Download Url", "type": "string" }, "executive_summary": { "default": "", "title": "Executive Summary", "type": "string" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "positions_analysed": { "items": { "type": "string" }, "title": "Positions Analysed", "type": "array" }, "open_items": { "items": { "type": "string" }, "title": "Open Items", "type": "array" } }, "title": "MemoOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/prepare.asc610.20.gain/invoke": { "post": { "operationId": "invokeSkill_prepare_asc610_20_gain", "summary": "Prepare an ASC 610-20 gain-on-derecognition memo for the sale of a nonfinancial asset to a non-customer. Deterministic engine: gain = consideration - carrying amount - transaction costs, re-computed from GROUNDED inputs (each a verbatim document quote or an attributed assertion). An ungrounded monetary input (e.g. a GL carrying amount not in the deal docs) is FLAGGED for partner input \u2014 never printed as a gain.", "tags": [ "reports" ], "x-skill-name": "prepare.asc610.20.gain", "x-skill-slug": "prepare_asc610_20_gain", "x-skill-category": "reports", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$defs": { "Asc610GainComponent": { "description": "One grounded monetary input. Grounding: verbatim ``quote`` + ``file_id``\n(SourceQuote), else ``asserted_by`` (HumanInput), else ungrounded \u2192 flagged.", "properties": { "label": { "title": "Label", "type": "string" }, "amount": { "anyOf": [ { "type": "number" }, { "type": "integer" } ], "title": "Amount" }, "quote": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Quote" }, "file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "File Id" }, "asserted_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Asserted By" }, "note": { "default": "", "title": "Note", "type": "string" }, "reason": { "default": "", "title": "Reason", "type": "string" } }, "required": [ "label", "amount" ], "title": "Asc610GainComponent", "type": "object" } }, "properties": { "subject_entity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Subject Entity" }, "consideration_components": { "items": { "$ref": "#/$defs/Asc610GainComponent" }, "title": "Consideration Components", "type": "array" }, "carrying_amount": { "$ref": "#/$defs/Asc610GainComponent" }, "transaction_costs": { "items": { "$ref": "#/$defs/Asc610GainComponent" }, "title": "Transaction Costs", "type": "array" }, "judgment_items": { "items": { "$ref": "#/$defs/Asc610GainComponent" }, "title": "Judgment Items", "type": "array" } }, "required": [ "consideration_components", "carrying_amount" ], "title": "Asc610GainInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "prepare_asc610_20_gain" }, "output": { "$defs": { "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" } }, "properties": { "artifact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Artifact Id" }, "download_url": { "default": "", "title": "Download Url", "type": "string" }, "summary": { "default": "", "title": "Summary", "type": "string" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "gain_on_derecognition": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Gain On Derecognition" }, "verification_status": { "default": "", "title": "Verification Status", "type": "string" }, "memo_sections": { "items": { "additionalProperties": true, "type": "object" }, "title": "Memo Sections", "type": "array" }, "blocked_inputs": { "items": { "type": "string" }, "title": "Blocked Inputs", "type": "array" } }, "title": "Asc610GainOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/prepare.asc842.memo/invoke": { "post": { "operationId": "invokeSkill_prepare_asc842_memo", "summary": "Prepare an ASC 842 lessee memo + lease schedules. Deterministic engine: lease liability = present value of the payment vector at the discount rate; ROU asset, operating single-cost / finance amortisation and the maturity ladder all re-computed from GROUNDED inputs. An ungrounded discount rate or payment clause is FLAGGED for partner input \u2014 never printed as a measurement.", "tags": [ "reports" ], "x-skill-name": "prepare.asc842.memo", "x-skill-slug": "prepare_asc842_memo", "x-skill-category": "reports", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$defs": { "Asc842GroundedScalar": { "description": "Grounding for a scalar lease input (the rate / the base-rent clause).", "properties": { "quote": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Quote" }, "file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "File Id" }, "asserted_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Asserted By" }, "note": { "default": "", "title": "Note", "type": "string" } }, "title": "Asc842GroundedScalar", "type": "object" } }, "properties": { "subject_entity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Subject Entity" }, "classification": { "default": "OPERATING", "title": "Classification", "type": "string" }, "monthly_payment": { "anyOf": [ { "type": "number" }, { "type": "integer" } ], "title": "Monthly Payment" }, "lease_term_months": { "title": "Lease Term Months", "type": "integer" }, "annual_rate": { "anyOf": [ { "type": "number" }, { "type": "integer" } ], "title": "Annual Rate" }, "in_advance": { "default": false, "title": "In Advance", "type": "boolean" }, "abatement_months": { "default": 0, "title": "Abatement Months", "type": "integer" }, "initial_direct_costs": { "anyOf": [ { "type": "number" }, { "type": "integer" } ], "default": 0, "title": "Initial Direct Costs" }, "lease_incentives": { "anyOf": [ { "type": "number" }, { "type": "integer" } ], "default": 0, "title": "Lease Incentives" }, "prepaid_rent": { "anyOf": [ { "type": "number" }, { "type": "integer" } ], "default": 0, "title": "Prepaid Rent" }, "rent_grounding": { "anyOf": [ { "$ref": "#/$defs/Asc842GroundedScalar" }, { "type": "null" } ], "default": null }, "rate_grounding": { "anyOf": [ { "$ref": "#/$defs/Asc842GroundedScalar" }, { "type": "null" } ], "default": null } }, "required": [ "monthly_payment", "lease_term_months", "annual_rate" ], "title": "Asc842LeaseInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "prepare_asc842_memo" }, "output": { "$defs": { "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" } }, "properties": { "artifact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Artifact Id" }, "download_url": { "default": "", "title": "Download Url", "type": "string" }, "summary": { "default": "", "title": "Summary", "type": "string" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "lease_liability_initial": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Lease Liability Initial" }, "rou_asset_initial": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Rou Asset Initial" }, "classification": { "default": "", "title": "Classification", "type": "string" }, "verification_status": { "default": "", "title": "Verification Status", "type": "string" }, "memo_sections": { "items": { "additionalProperties": true, "type": "object" }, "title": "Memo Sections", "type": "array" }, "blocked_inputs": { "items": { "type": "string" }, "title": "Blocked Inputs", "type": "array" } }, "title": "Asc842LeaseOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/propose.qbo.tax.group.mapping/invoke": { "post": { "operationId": "invokeSkill_propose_qbo_tax_group_mapping", "summary": "Propose CCH-Axcess-style tax-line mappings for the rows of a prepared QBO trial balance. Conversational \u2014 uses consult_accounting_expert + search_knowledge_base + the firm's tax-group catalog to assign each TB row a tax_code / engagement_tax_code / line_description with confidence + reasoning. Inputs: tb_rows (alpha-canonical from enrich_tb_rows) + tax_group_catalog + entity_type (1065/1120/1120S/1040). Output: 1:1 mapping list + counts + unmapped account_numbers. Does NOT render a CCH file \u2014 the deliverable is the source Caseware TB Excel with TaxCodeCode populated, rendered by the existing TB Excel generator downstream.", "tags": [ "analysis" ], "x-skill-name": "propose.qbo.tax.group.mapping", "x-skill-slug": "propose_qbo_tax_group_mapping", "x-skill-category": "analysis", "x-skill-cluster": "TAX", "x-skill-streaming": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "tb_rows": { "description": "Prepared trial balance rows (alpha-canonical dict shape from enrich_tb_rows). Each row carries code, name, debit, credit, classification.", "items": { "additionalProperties": true, "type": "object" }, "title": "Tb Rows", "type": "array" }, "tax_group_catalog": { "description": "Firm's tax-line catalog \u2014 one dict per tax group / line with tax_code, engagement_tax_code, line_description, category, worksheet, section. Source: CCH Axcess import template or Caseware TB extract.", "items": { "additionalProperties": true, "type": "object" }, "title": "Tax Group Catalog", "type": "array" }, "entity_type": { "default": "1065", "enum": [ "1065", "1120", "1120S", "1040" ], "title": "Entity Type", "type": "string" }, "confidence_threshold": { "default": 0.85, "title": "Confidence Threshold", "type": "number" } }, "title": "ProposeQboTaxGroupMappingInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "propose_qbo_tax_group_mapping" }, "output": { "$defs": { "ProposedTaxMapping": { "additionalProperties": false, "description": "One proposed mapping row, one per active TB row in input order.", "properties": { "account_number": { "default": "", "title": "Account Number", "type": "string" }, "account_name": { "default": "", "title": "Account Name", "type": "string" }, "proposed_tax_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Proposed Tax Code" }, "proposed_engagement_tax_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Proposed Engagement Tax Code" }, "proposed_line_description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Proposed Line Description" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" }, "reasoning": { "default": "", "title": "Reasoning", "type": "string" } }, "title": "ProposedTaxMapping", "type": "object" } }, "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "mappings": { "items": { "$ref": "#/$defs/ProposedTaxMapping" }, "title": "Mappings", "type": "array" }, "counts": { "additionalProperties": { "type": "integer" }, "title": "Counts", "type": "object" }, "unmapped": { "description": "account_numbers we could not propose a mapping for.", "items": { "type": "string" }, "title": "Unmapped", "type": "array" } }, "title": "ProposeQboTaxGroupMappingOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/reports.audit-workpaper.prepare/invoke": { "post": { "operationId": "invokeSkill_reports_audit_workpaper_prepare", "summary": "Prepare an audit working paper \u2014 lead schedules, substantive testing, planning memos, going-concern, debt confirmations, related-party.", "tags": [ "audit" ], "x-skill-name": "reports.audit-workpaper.prepare", "x-skill-slug": "prepare_audit_workpaper", "x-skill-category": "audit", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "client_id": { "format": "uuid", "title": "Client Id", "type": "string" }, "workpaper_type": { "default": "lead_schedule", "enum": [ "lead_schedule", "substantive_test", "planning_memo", "going_concern", "subsequent_events", "revenue_testing", "expense_testing", "debt_confirmation", "related_party" ], "title": "Workpaper Type", "type": "string" }, "period": { "title": "Period", "type": "string" }, "materiality": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Materiality" }, "sample_size": { "default": 25, "title": "Sample Size", "type": "integer" }, "framework": { "default": "ISA", "enum": [ "ASA", "ISA", "PCAOB", "GAAS", "ISA_UK" ], "title": "Framework", "type": "string" } }, "required": [ "client_id", "period" ], "title": "PrepareAuditWorkpaperInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "prepare_audit_workpaper" }, "output": { "$defs": { "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" }, "Finding": { "properties": { "area": { "title": "Area", "type": "string" }, "description": { "title": "Description", "type": "string" }, "severity": { "default": "info", "title": "Severity", "type": "string" }, "recommendation": { "default": "", "title": "Recommendation", "type": "string" } }, "required": [ "area", "description" ], "title": "Finding", "type": "object" } }, "properties": { "artifact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Artifact Id" }, "download_url": { "default": "", "title": "Download Url", "type": "string" }, "summary": { "default": "", "title": "Summary", "type": "string" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "workpaper_type": { "default": "", "title": "Workpaper Type", "type": "string" }, "sections": { "items": { "type": "string" }, "title": "Sections", "type": "array" }, "findings": { "items": { "$ref": "#/$defs/Finding" }, "title": "Findings", "type": "array" }, "sample_results": { "additionalProperties": true, "title": "Sample Results", "type": "object" } }, "title": "PrepareAuditWorkpaperOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/reports.cfo-pack.prepare/invoke": { "post": { "operationId": "invokeSkill_reports_cfo_pack_prepare", "summary": "Prepare a CFO/board pack \u2014 KPI dashboard, financial review, forecast, commentary, risks, actions.", "tags": [ "reports" ], "x-skill-name": "reports.cfo-pack.prepare", "x-skill-slug": "prepare_cfo_pack", "x-skill-category": "reports", "x-skill-cluster": "MAV", "x-skill-streaming": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "client_id": { "format": "uuid", "title": "Client Id", "type": "string" }, "period": { "title": "Period", "type": "string" }, "sections": { "items": { "enum": [ "financial_review", "forecast", "commentary", "risks", "actions", "kpi_dashboard" ], "type": "string" }, "title": "Sections", "type": "array" }, "output_format": { "default": "pptx", "enum": [ "pptx", "pdf", "both" ], "title": "Output Format", "type": "string" }, "branding": { "additionalProperties": true, "title": "Branding", "type": "object" } }, "required": [ "client_id", "period" ], "title": "PrepareCfoPackInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "prepare_cfo_pack" }, "output": { "$defs": { "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" } }, "properties": { "artifact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Artifact Id" }, "download_url": { "default": "", "title": "Download Url", "type": "string" }, "summary": { "default": "", "title": "Summary", "type": "string" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "docx_download_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Docx Download Url" }, "sections_built": { "items": { "type": "string" }, "title": "Sections Built", "type": "array" }, "kpis": { "additionalProperties": true, "title": "Kpis", "type": "object" } }, "title": "PrepareCfoPackOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/reports.due-diligence.prepare/invoke": { "post": { "operationId": "invokeSkill_reports_due_diligence_prepare", "summary": "Prepare an M&A due-diligence / quality-of-earnings report.", "tags": [ "reports" ], "x-skill-name": "reports.due-diligence.prepare", "x-skill-slug": "prepare_due_diligence_report", "x-skill-category": "reports", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "client_id": { "format": "uuid", "title": "Client Id", "type": "string" }, "target_entity": { "title": "Target Entity", "type": "string" }, "deal_type": { "default": "acquisition", "enum": [ "acquisition", "merger", "investment" ], "title": "Deal Type", "type": "string" }, "file_ids": { "items": { "format": "uuid", "type": "string" }, "title": "File Ids", "type": "array" }, "sections": { "items": { "enum": [ "qoe", "working_capital", "debt_like", "tax_exposures", "customer_concentration", "revenue_quality", "key_dependencies", "red_flags" ], "type": "string" }, "title": "Sections", "type": "array" }, "period": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Period" } }, "required": [ "client_id", "target_entity" ], "title": "PrepareDueDiligenceReportInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "prepare_due_diligence_report" }, "output": { "$defs": { "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" }, "RedFlag": { "description": "Forensic finding (used by investigate_anomaly, trace_assets).", "properties": { "flag_id": { "title": "Flag Id", "type": "string" }, "classification": { "default": "", "title": "Classification", "type": "string" }, "severity": { "default": "MODERATE", "enum": [ "MINOR", "MODERATE", "SIGNIFICANT", "CRITICAL" ], "title": "Severity", "type": "string" }, "description": { "default": "", "title": "Description", "type": "string" }, "evidence": { "items": { "type": "string" }, "title": "Evidence", "type": "array" }, "amount_at_risk": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ], "default": "0", "title": "Amount At Risk" }, "recommended_action": { "default": "", "title": "Recommended Action", "type": "string" } }, "required": [ "flag_id" ], "title": "RedFlag", "type": "object" } }, "properties": { "artifact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Artifact Id" }, "download_url": { "default": "", "title": "Download Url", "type": "string" }, "summary": { "default": "", "title": "Summary", "type": "string" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "target_entity": { "default": "", "title": "Target Entity", "type": "string" }, "normalised_ebitda": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ], "default": "0", "title": "Normalised Ebitda" }, "working_capital_peg": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ], "default": "0", "title": "Working Capital Peg" }, "debt_like_items": { "items": { "additionalProperties": true, "type": "object" }, "title": "Debt Like Items", "type": "array" }, "red_flags": { "items": { "$ref": "#/$defs/RedFlag" }, "title": "Red Flags", "type": "array" }, "sections_built": { "items": { "type": "string" }, "title": "Sections Built", "type": "array" } }, "title": "PrepareDueDiligenceReportOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/reports.financial.prepare/invoke": { "post": { "operationId": "invokeSkill_reports_financial_prepare", "summary": "Generate a financial report (TB, P&L, balance sheet, mgmt accounts, or financial statements).", "tags": [ "reports" ], "x-skill-name": "reports.financial.prepare", "x-skill-slug": "prepare_financial_report", "x-skill-category": "reports", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "client_id": { "format": "uuid", "title": "Client Id", "type": "string" }, "report_type": { "enum": [ "trial_balance", "profit_loss", "balance_sheet", "management_accounts", "monthly_management", "leave_provision", "soce", "payroll_summary", "financial_statements" ], "title": "Report Type", "type": "string" }, "period": { "title": "Period", "type": "string" }, "comparison_periods": { "items": { "type": "string" }, "title": "Comparison Periods", "type": "array" }, "industry": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Industry" }, "output_format": { "default": "pdf", "enum": [ "pdf", "xlsx", "both" ], "title": "Output Format", "type": "string" }, "max_age_hours": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Max Age Hours" } }, "required": [ "client_id", "report_type", "period" ], "title": "PrepareFinancialReportInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "prepare_financial_report" }, "output": { "$defs": { "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" } }, "properties": { "artifact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Artifact Id" }, "download_url": { "default": "", "title": "Download Url", "type": "string" }, "summary": { "default": "", "title": "Summary", "type": "string" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "xlsx_download_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Xlsx Download Url" }, "report_type": { "default": "", "title": "Report Type", "type": "string" }, "period": { "default": "", "title": "Period", "type": "string" }, "sections": { "items": { "type": "string" }, "title": "Sections", "type": "array" }, "rows_written": { "default": 0, "title": "Rows Written", "type": "integer" } }, "title": "PrepareFinancialReportOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/reports.forecast.prepare/invoke": { "post": { "operationId": "invokeSkill_reports_forecast_prepare", "summary": "Prepare a financial forecast \u2014 multi-scenario, with assumptions register.", "tags": [ "reports" ], "x-skill-name": "reports.forecast.prepare", "x-skill-slug": "prepare_forecast", "x-skill-category": "reports", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "client_id": { "format": "uuid", "title": "Client Id", "type": "string" }, "horizon_months": { "default": 12, "title": "Horizon Months", "type": "integer" }, "scenarios": { "items": { "enum": [ "base", "optimistic", "pessimistic" ], "type": "string" }, "title": "Scenarios", "type": "array" }, "projection_type": { "items": { "enum": [ "pnl", "cashflow", "balance_sheet" ], "type": "string" }, "title": "Projection Type", "type": "array" }, "seasonal_adjustment": { "default": true, "title": "Seasonal Adjustment", "type": "boolean" }, "growth_assumptions": { "additionalProperties": true, "title": "Growth Assumptions", "type": "object" }, "output_format": { "default": "both", "enum": [ "data", "document", "both" ], "title": "Output Format", "type": "string" } }, "required": [ "client_id" ], "title": "PrepareForecastInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "prepare_forecast" }, "output": { "$defs": { "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" } }, "properties": { "artifact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Artifact Id" }, "download_url": { "default": "", "title": "Download Url", "type": "string" }, "summary": { "default": "", "title": "Summary", "type": "string" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "forecast_id": { "format": "uuid", "title": "Forecast Id", "type": "string" }, "horizon_months": { "default": 0, "title": "Horizon Months", "type": "integer" }, "base_period": { "default": "", "title": "Base Period", "type": "string" }, "currency": { "default": "AUD", "title": "Currency", "type": "string" }, "scenarios": { "additionalProperties": true, "title": "Scenarios", "type": "object" }, "assumptions_register": { "items": { "additionalProperties": true, "type": "object" }, "title": "Assumptions Register", "type": "array" }, "data_quality": { "additionalProperties": true, "title": "Data Quality", "type": "object" } }, "title": "PrepareForecastOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/reports.tax-return.prepare/invoke": { "post": { "operationId": "invokeSkill_reports_tax_return_prepare", "summary": "Prepare a tax return artifact \u2014 income, BAS, IAS, VAT, corporate tax, payroll, or self-assessment.", "tags": [ "reports" ], "x-skill-name": "reports.tax-return.prepare", "x-skill-slug": "prepare_tax_return", "x-skill-category": "reports", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "client_id": { "format": "uuid", "title": "Client Id", "type": "string" }, "jurisdiction": { "enum": [ "AU", "GB", "CA", "US", "NZ" ], "title": "Jurisdiction", "type": "string" }, "entity_type": { "default": "company", "enum": [ "individual", "company", "partnership", "trust" ], "title": "Entity Type", "type": "string" }, "return_type": { "default": "income", "enum": [ "income", "bas", "ias", "vat", "corp", "payroll", "self_assessment" ], "title": "Return Type", "type": "string" }, "tax_year": { "title": "Tax Year", "type": "string" }, "file_ids": { "items": { "format": "uuid", "type": "string" }, "title": "File Ids", "type": "array" } }, "required": [ "client_id", "jurisdiction", "tax_year" ], "title": "PrepareTaxReturnInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "prepare_tax_return" }, "output": { "$defs": { "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" } }, "properties": { "artifact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Artifact Id" }, "download_url": { "default": "", "title": "Download Url", "type": "string" }, "summary": { "default": "", "title": "Summary", "type": "string" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "return_type": { "default": "", "title": "Return Type", "type": "string" }, "jurisdiction": { "default": "", "title": "Jurisdiction", "type": "string" }, "tax_year": { "default": "", "title": "Tax Year", "type": "string" }, "tax_summary": { "additionalProperties": true, "description": "Structured per-return-type summary (e.g. BAS: G1/1A/1B/net; VAT: box_1/3/4/5/6/7). Pre-PR-D3 this was named `summary` and stayed dict-typed; the rename was forced by the BaseArtifactOutput shell which carries `summary: str` for the short narrative line.", "title": "Tax Summary", "type": "object" }, "workpapers": { "items": { "additionalProperties": true, "type": "object" }, "title": "Workpapers", "type": "array" }, "estimated_liability": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ], "default": "0", "title": "Estimated Liability" } }, "title": "PrepareTaxReturnOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/reports.trust-accounts.prepare/invoke": { "post": { "operationId": "invokeSkill_reports_trust_accounts_prepare", "summary": "Prepare trust accounts \u2014 distributions, beneficiary statements, capital accounts, income allocation, trustee reporting.", "tags": [ "reports" ], "x-skill-name": "reports.trust-accounts.prepare", "x-skill-slug": "prepare_trust_accounts", "x-skill-category": "reports", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "client_id": { "format": "uuid", "title": "Client Id", "type": "string" }, "period": { "title": "Period", "type": "string" }, "distribution_resolution": { "additionalProperties": true, "title": "Distribution Resolution", "type": "object" }, "output_format": { "default": "both", "enum": [ "pdf", "xlsx", "both" ], "title": "Output Format", "type": "string" }, "include_beneficiary_statements": { "default": true, "title": "Include Beneficiary Statements", "type": "boolean" } }, "required": [ "client_id", "period" ], "title": "PrepareTrustAccountsInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "prepare_trust_accounts" }, "output": { "$defs": { "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" } }, "properties": { "artifact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Artifact Id" }, "download_url": { "default": "", "title": "Download Url", "type": "string" }, "summary": { "default": "", "title": "Summary", "type": "string" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "xlsx_download_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Xlsx Download Url" }, "period": { "default": "", "title": "Period", "type": "string" }, "income_allocation": { "additionalProperties": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ] }, "title": "Income Allocation", "type": "object" }, "distributions": { "items": { "additionalProperties": true, "type": "object" }, "title": "Distributions", "type": "array" }, "beneficiary_statements": { "items": { "additionalProperties": true, "type": "object" }, "title": "Beneficiary Statements", "type": "array" }, "capital_accounts": { "additionalProperties": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ] }, "title": "Capital Accounts", "type": "object" } }, "title": "PrepareTrustAccountsOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/reports.valuation.prepare/invoke": { "post": { "operationId": "invokeSkill_reports_valuation_prepare", "summary": "Prepare a business valuation report \u2014 DCF, multiples, asset-based, or maintainable earnings.", "tags": [ "reports" ], "x-skill-name": "reports.valuation.prepare", "x-skill-slug": "prepare_valuation", "x-skill-category": "reports", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "client_id": { "format": "uuid", "title": "Client Id", "type": "string" }, "valuation_method": { "default": "dcf", "enum": [ "dcf", "market_multiples", "asset_based", "maintainable_earnings", "scenario" ], "title": "Valuation Method", "type": "string" }, "valuation_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "default": null, "title": "Valuation Date" }, "purpose": { "default": "acquisition", "enum": [ "shareholder_dispute", "acquisition", "succession", "matrimonial", "tax_planning", "fundraising" ], "title": "Purpose", "type": "string" }, "discount_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Discount Rate" }, "growth_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Growth Rate" }, "custom_assumptions": { "additionalProperties": true, "title": "Custom Assumptions", "type": "object" } }, "required": [ "client_id" ], "title": "PrepareValuationInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "prepare_valuation" }, "output": { "$defs": { "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" } }, "properties": { "artifact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Artifact Id" }, "download_url": { "default": "", "title": "Download Url", "type": "string" }, "summary": { "default": "", "title": "Summary", "type": "string" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "valuation_id": { "format": "uuid", "title": "Valuation Id", "type": "string" }, "valuation_range_low": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ], "default": "0", "title": "Valuation Range Low" }, "valuation_range_high": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ], "default": "0", "title": "Valuation Range High" }, "point_estimate": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ], "default": "0", "title": "Point Estimate" }, "method": { "default": "", "title": "Method", "type": "string" }, "sensitivity": { "additionalProperties": true, "title": "Sensitivity", "type": "object" }, "assumptions": { "additionalProperties": true, "title": "Assumptions", "type": "object" } }, "title": "PrepareValuationOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/search.query/invoke": { "post": { "operationId": "invokeSkill_search_query", "summary": "(Utility) Search the knowledge base directly.", "tags": [ "utility" ], "x-skill-name": "search.query", "x-skill-slug": "search_knowledge", "x-skill-category": "utility", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "query": { "title": "Query", "type": "string" }, "sources": { "items": { "type": "string" }, "title": "Sources", "type": "array" }, "jurisdiction": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Jurisdiction" } }, "required": [ "query" ], "title": "SearchKnowledgeInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "search_knowledge" }, "output": { "$defs": { "KnowledgeItem": { "properties": { "source": { "title": "Source", "type": "string" }, "section": { "title": "Section", "type": "string" }, "content": { "title": "Content", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "source", "section", "content" ], "title": "KnowledgeItem", "type": "object" } }, "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "results": { "items": { "$ref": "#/$defs/KnowledgeItem" }, "title": "Results", "type": "array" }, "total_count": { "default": 0, "title": "Total Count", "type": "integer" }, "facets": { "additionalProperties": true, "title": "Facets", "type": "object" } }, "title": "SearchKnowledgeOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/standards.research/invoke": { "post": { "operationId": "invokeSkill_standards_research", "summary": "Research accounting standards or compare two standards on a topic.", "tags": [ "research" ], "x-skill-name": "standards.research", "x-skill-slug": "research_standards", "x-skill-category": "research", "x-skill-cluster": "ASR", "x-skill-streaming": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "topic": { "maxLength": 2000, "title": "Topic", "type": "string" }, "standard_references": { "items": { "type": "string" }, "title": "Standard References", "type": "array" }, "jurisdiction": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Jurisdiction" }, "mode": { "default": "research", "enum": [ "research", "compare" ], "title": "Mode", "type": "string" }, "compare_standard_b": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Compare Standard B" }, "output_format": { "default": "summary", "enum": [ "summary", "memo", "detailed" ], "title": "Output Format", "type": "string" } }, "required": [ "topic" ], "title": "ResearchStandardsInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "research_standards" }, "output": { "$defs": { "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" }, "Difference": { "properties": { "topic": { "title": "Topic", "type": "string" }, "standard_a_position": { "title": "Standard A Position", "type": "string" }, "standard_b_position": { "title": "Standard B Position", "type": "string" } }, "required": [ "topic", "standard_a_position", "standard_b_position" ], "title": "Difference", "type": "object" } }, "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "executive_summary": { "default": "", "title": "Executive Summary", "type": "string" }, "detailed_analysis": { "default": "", "title": "Detailed Analysis", "type": "string" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" }, "practical_implications": { "items": { "type": "string" }, "title": "Practical Implications", "type": "array" }, "open_questions": { "items": { "type": "string" }, "title": "Open Questions", "type": "array" }, "differences": { "items": { "$ref": "#/$defs/Difference" }, "title": "Differences", "type": "array" }, "artifact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Artifact Id" } }, "title": "ResearchStandardsOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/tax.advise/invoke": { "post": { "operationId": "invokeSkill_tax_advise", "summary": "Get tax advice (income, corporate, CGT, FBT, stamp duty) by jurisdiction.", "tags": [ "advisory" ], "x-skill-name": "tax.advise", "x-skill-slug": "advise_tax", "x-skill-category": "advisory", "x-skill-cluster": "TAX", "x-skill-streaming": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "topic": { "maxLength": 5000, "title": "Topic", "type": "string" }, "jurisdiction": { "anyOf": [ { "enum": [ "AU", "GB", "CA", "US", "NZ" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Jurisdiction" }, "tax_type": { "anyOf": [ { "enum": [ "income", "corporate", "capital_gains", "fringe_benefits", "stamp_duty" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Tax Type" }, "client_context": { "additionalProperties": true, "title": "Client Context", "type": "object" }, "tax_year": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Tax Year" } }, "required": [ "topic" ], "title": "AdviseTaxInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "advise_tax" }, "output": { "$defs": { "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" } }, "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "advice": { "default": "", "title": "Advice", "type": "string" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" }, "caveats": { "items": { "type": "string" }, "title": "Caveats", "type": "array" }, "effective_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "default": null, "title": "Effective Date" } }, "title": "AdviseTaxOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/tax.indirect.advise/invoke": { "post": { "operationId": "invokeSkill_tax_indirect_advise", "summary": "GST, VAT, sales tax, HST, QST, use-tax advice by jurisdiction.", "tags": [ "advisory" ], "x-skill-name": "tax.indirect.advise", "x-skill-slug": "advise_indirect_tax", "x-skill-category": "advisory", "x-skill-cluster": "TAX", "x-skill-streaming": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "topic": { "maxLength": 5000, "title": "Topic", "type": "string" }, "jurisdiction": { "anyOf": [ { "enum": [ "AU", "GB", "CA", "US", "NZ" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Jurisdiction" }, "indirect_tax_type": { "anyOf": [ { "enum": [ "gst", "vat", "sales_tax", "hst", "qst", "use_tax" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Indirect Tax Type" }, "client_context": { "additionalProperties": true, "title": "Client Context", "type": "object" } }, "required": [ "topic" ], "title": "AdviseIndirectTaxInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "advise_indirect_tax" }, "output": { "$defs": { "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" } }, "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "advice": { "default": "", "title": "Advice", "type": "string" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" }, "caveats": { "items": { "type": "string" }, "title": "Caveats", "type": "array" } }, "title": "AdviseIndirectTaxOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/tax.international.advise/invoke": { "post": { "operationId": "invokeSkill_tax_international_advise", "summary": "Cross-border tax advice \u2014 transfer pricing, treaties, withholding, PE, CFC, structure.", "tags": [ "advisory" ], "x-skill-name": "tax.international.advise", "x-skill-slug": "advise_international_tax", "x-skill-category": "advisory", "x-skill-cluster": "TAX", "x-skill-streaming": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "topic": { "maxLength": 5000, "title": "Topic", "type": "string" }, "home_jurisdiction": { "anyOf": [ { "enum": [ "AU", "GB", "CA", "US", "NZ" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Home Jurisdiction" }, "counterparty_jurisdiction": { "anyOf": [ { "enum": [ "AU", "GB", "CA", "US", "NZ" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Counterparty Jurisdiction" }, "issue_type": { "anyOf": [ { "enum": [ "transfer_pricing", "withholding", "treaty", "permanent_establishment", "cfc_rules", "structure" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Issue Type" }, "client_context": { "additionalProperties": true, "title": "Client Context", "type": "object" } }, "required": [ "topic" ], "title": "AdviseInternationalTaxInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "advise_international_tax" }, "output": { "$defs": { "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" } }, "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "advice": { "default": "", "title": "Advice", "type": "string" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" }, "caveats": { "items": { "type": "string" }, "title": "Caveats", "type": "array" } }, "title": "AdviseInternationalTaxOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/tax.quarterly.estimate/invoke": { "post": { "operationId": "invokeSkill_tax_quarterly_estimate", "summary": "Advisory \u2014 LLM-driven; verify against authoritative sources before relying. Calculate a US federal quarterly estimated tax payment under one of the three IRC \u00a76654/\u00a76655 safe harbor rules (prior-year, annualised, or current-year). Read-only \u2014 outputs a worksheet with cumulative-required tracking and underpayment risk flag.", "tags": [ "advisory" ], "x-skill-name": "tax.quarterly.estimate", "x-skill-slug": "tax_quarterly_estimate", "x-skill-category": "advisory", "x-skill-cluster": "TAX", "x-skill-streaming": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "client_id": { "format": "uuid", "title": "Client Id", "type": "string" }, "tax_year": { "description": "Tax year, e.g. '2026'.", "title": "Tax Year", "type": "string" }, "quarter": { "enum": [ "Q1", "Q2", "Q3", "Q4" ], "title": "Quarter", "type": "string" }, "entity_type": { "default": "individual", "enum": [ "individual", "corporation", "s_corporation", "partnership", "trust" ], "title": "Entity Type", "type": "string" }, "safe_harbor_method": { "default": "prior_year", "enum": [ "prior_year", "annualised", "current_year" ], "title": "Safe Harbor Method", "type": "string" }, "prior_year_tax": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" }, { "type": "null" } ], "default": null, "description": "If known; otherwise the handler reads from prior-year TB.", "title": "Prior Year Tax" }, "current_ytd_income": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" }, { "type": "null" } ], "default": null, "description": "Override for current-year YTD income (skips TB read).", "title": "Current Ytd Income" }, "tax_jurisdiction": { "default": "US-federal", "description": "US-federal (IRS) by default. State-level extensions use US-{state} codes (e.g. US-CA for California Form 540-ES).", "title": "Tax Jurisdiction", "type": "string" } }, "required": [ "client_id", "tax_year", "quarter" ], "title": "TaxQuarterlyEstimateInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "tax_quarterly_estimate" }, "output": { "$defs": { "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" } }, "properties": { "artifact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Artifact Id" }, "download_url": { "default": "", "title": "Download Url", "type": "string" }, "summary": { "default": "", "title": "Summary", "type": "string" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "estimate_amount": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ], "default": "0", "title": "Estimate Amount" }, "cumulative_required": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ], "default": "0", "description": "Running sum of payments required YTD through this quarter.", "title": "Cumulative Required" }, "safe_harbor_basis": { "default": "prior_year", "enum": [ "prior_year", "annualised", "current_year" ], "title": "Safe Harbor Basis", "type": "string" }, "due_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "default": null, "title": "Due Date" }, "irs_form": { "default": "", "description": "The IRS form applicable, e.g. '1040-ES' (individuals), '1120-W' (corp).", "title": "Irs Form", "type": "string" }, "breakdown": { "additionalProperties": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ] }, "description": "Line-item working \u2014 prior-year tax, safe-harbor pct, quarterly target.", "title": "Breakdown", "type": "object" }, "underpayment_risk": { "default": "none", "enum": [ "none", "low", "medium", "high" ], "title": "Underpayment Risk", "type": "string" } }, "title": "TaxQuarterlyEstimateOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/topic.archive/invoke": { "post": { "operationId": "invokeSkill_topic_archive", "summary": "Archive a Topic (status='archived'). Archiving an already-archived topic is rejected; un-archive via topic_update status='active'.", "tags": [ "topics" ], "x-skill-name": "topic.archive", "x-skill-slug": "topic_archive", "x-skill-category": "topics", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "topic_id": { "description": "Topic permakey (preferred) or UUID", "title": "Topic Id", "type": "string" } }, "required": [ "topic_id" ], "title": "TopicArchiveInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "topic_archive" }, "output": { "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "topic_id": { "default": "", "description": "The topic's permakey (the public id).", "title": "Topic Id", "type": "string" }, "permakey": { "default": "", "description": "The 7-char public topic id \u2014 THE id to show users and reuse in later topic_* calls (UUIDs are internal).", "title": "Permakey", "type": "string" }, "status": { "default": "archived", "description": "The topic's new status", "title": "Status", "type": "string" } }, "title": "TopicArchiveOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/topic.ask/invoke": { "post": { "operationId": "invokeSkill_topic_ask", "summary": "Ask a question in a Topic conversation and wait (bounded) for the final answer. On timeout the turn keeps running server-side and status=running is returned \u2014 poll the conversation.", "tags": [ "topics" ], "x-skill-name": "topic.ask", "x-skill-slug": "topic_ask", "x-skill-category": "topics", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "topic_id": { "description": "Topic permakey (preferred) or UUID", "title": "Topic Id", "type": "string" }, "question": { "maxLength": 20000, "minLength": 1, "title": "Question", "type": "string" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Existing conversation in the topic; omitted = the topic's most-recent conversation, auto-created+linked if none exists", "title": "Conversation Id" }, "timeout_seconds": { "default": 120, "maximum": 300, "minimum": 10, "title": "Timeout Seconds", "type": "integer" } }, "required": [ "topic_id", "question" ], "title": "TopicAskInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "topic_ask" }, "output": { "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "topic_id": { "default": "", "description": "The topic's permakey (the public id).", "title": "Topic Id", "type": "string" }, "permakey": { "default": "", "description": "The 7-char public topic id \u2014 THE id to show users and reuse in later topic_* calls (UUIDs are internal).", "title": "Permakey", "type": "string" }, "conversation_id": { "default": "", "title": "Conversation Id", "type": "string" }, "message_id": { "default": "", "title": "Message Id", "type": "string" }, "query_id": { "default": "", "title": "Query Id", "type": "string" }, "status": { "default": "", "title": "Status", "type": "string" }, "answer": { "default": "", "title": "Answer", "type": "string" }, "metadata": { "additionalProperties": true, "title": "Metadata", "type": "object" } }, "title": "TopicAskOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/topic.create/invoke": { "post": { "operationId": "invokeSkill_topic_create", "summary": "Create a Topic in the caller's workspace (optionally bound to a client). The topic is stamped created_by_type=archie.", "tags": [ "topics" ], "x-skill-name": "topic.create", "x-skill-slug": "topic_create", "x-skill-category": "topics", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "maxLength": 200, "minLength": 1, "title": "Name", "type": "string" }, "type": { "default": "client", "description": "Topic type: client | matter | process_period | advisory | compliance | internal (DB-enforced enum)", "title": "Type", "type": "string" }, "client_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "UUID of the client to bind", "title": "Client Id" }, "theme_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Hex like #DAFBE1; default applied server-side", "title": "Theme Color" } }, "required": [ "name" ], "title": "TopicCreateInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "topic_create" }, "output": { "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "topic_id": { "default": "", "description": "The new topic's permakey (the public id).", "title": "Topic Id", "type": "string" }, "permakey": { "default": "", "description": "The 7-char public topic id \u2014 THE id to show users and reuse in later topic_* calls (UUIDs are internal).", "title": "Permakey", "type": "string" }, "name": { "default": "", "title": "Name", "type": "string" }, "type": { "default": "", "title": "Type", "type": "string" }, "workspace_id": { "default": "", "title": "Workspace Id", "type": "string" } }, "title": "TopicCreateOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/topic.delete/invoke": { "post": { "operationId": "invokeSkill_topic_delete", "summary": "Soft-delete a Topic (status='deleted') and unlink its conversations. The topic drops off every list surface; reversible only by an operator. Deleted is terminal.", "tags": [ "topics" ], "x-skill-name": "topic.delete", "x-skill-slug": "topic_delete", "x-skill-category": "topics", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "topic_id": { "description": "Topic permakey (preferred) or UUID", "title": "Topic Id", "type": "string" } }, "required": [ "topic_id" ], "title": "TopicDeleteInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "topic_delete" }, "output": { "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "topic_id": { "default": "", "description": "The deleted topic's permakey (the public id).", "title": "Topic Id", "type": "string" }, "permakey": { "default": "", "description": "The 7-char public topic id \u2014 THE id to show users and reuse in later topic_* calls (UUIDs are internal).", "title": "Permakey", "type": "string" }, "deleted": { "default": false, "description": "True when the topic was soft-deleted", "title": "Deleted", "type": "boolean" } }, "title": "TopicDeleteOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/topic.get/invoke": { "post": { "operationId": "invokeSkill_topic_get", "summary": "Get a Topic by UUID (aggregate counts; optional canvas descriptor with sections/tabs/email_draft).", "tags": [ "topics" ], "x-skill-name": "topic.get", "x-skill-slug": "topic_get", "x-skill-category": "topics", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "topic_id": { "description": "Topic permakey (preferred) or UUID", "title": "Topic Id", "type": "string" }, "include_canvas": { "default": false, "description": "Include the canvas descriptor (sections/tabs/email_draft)", "title": "Include Canvas", "type": "boolean" } }, "required": [ "topic_id" ], "title": "TopicGetInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "topic_get" }, "output": { "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "topic_id": { "default": "", "description": "The topic's permakey (the public id).", "title": "Topic Id", "type": "string" }, "permakey": { "default": "", "description": "The 7-char public topic id \u2014 THE id to show users and reuse in later topic_* calls (UUIDs are internal).", "title": "Permakey", "type": "string" }, "name": { "default": "", "title": "Name", "type": "string" }, "type": { "default": "", "title": "Type", "type": "string" }, "status": { "default": "", "title": "Status", "type": "string" }, "client_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Client Id" }, "conversation_count": { "default": 0, "title": "Conversation Count", "type": "integer" }, "member_count": { "default": 0, "title": "Member Count", "type": "integer" }, "metadata": { "additionalProperties": true, "title": "Metadata", "type": "object" }, "canvas": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Canvas" } }, "title": "TopicGetOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/topic.link.conversation/invoke": { "post": { "operationId": "invokeSkill_topic_link_conversation", "summary": "Link a conversation to a Topic (idempotent on same-topic re-link; a conversation belongs to at most one topic).", "tags": [ "topics" ], "x-skill-name": "topic.link.conversation", "x-skill-slug": "topic_link_conversation", "x-skill-category": "topics", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "topic_id": { "description": "Topic permakey (preferred) or UUID", "title": "Topic Id", "type": "string" }, "conversation_id": { "description": "Conversation UUID to link", "title": "Conversation Id", "type": "string" } }, "required": [ "topic_id", "conversation_id" ], "title": "TopicLinkConversationInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "topic_link_conversation" }, "output": { "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "topic_id": { "default": "", "description": "The topic's permakey (the public id).", "title": "Topic Id", "type": "string" }, "permakey": { "default": "", "description": "The 7-char public topic id \u2014 THE id to show users and reuse in later topic_* calls (UUIDs are internal).", "title": "Permakey", "type": "string" }, "conversation_id": { "default": "", "title": "Conversation Id", "type": "string" }, "linked": { "default": false, "title": "Linked", "type": "boolean" } }, "title": "TopicLinkConversationOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/topic.list/invoke": { "post": { "operationId": "invokeSkill_topic_list", "summary": "List Topics in the caller's workspace (filter by status/type/search, paginated).", "tags": [ "topics" ], "x-skill-name": "topic.list", "x-skill-slug": "topic_list", "x-skill-category": "topics", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "status": { "default": "active", "description": "Topic status filter: active (default) | archived | deleted", "title": "Status", "type": "string" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Topic type filter, e.g. 'client'", "title": "Type" }, "search": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Substring match on topic name", "title": "Search" }, "limit": { "default": 20, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" }, "offset": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } }, "title": "TopicListInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "topic_list" }, "output": { "$defs": { "TopicSummary": { "properties": { "topic_id": { "description": "The topic's permakey (the public id). Accepts UUIDs for back-compat.", "title": "Topic Id", "type": "string" }, "permakey": { "default": "", "description": "The 7-char public topic id \u2014 THE id to show users and reuse in later topic_* calls (UUIDs are internal).", "title": "Permakey", "type": "string" }, "name": { "title": "Name", "type": "string" }, "type": { "title": "Type", "type": "string" }, "status": { "title": "Status", "type": "string" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated At" } }, "required": [ "topic_id", "name", "type", "status" ], "title": "TopicSummary", "type": "object" } }, "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "topics": { "items": { "$ref": "#/$defs/TopicSummary" }, "title": "Topics", "type": "array" }, "total": { "default": 0, "title": "Total", "type": "integer" } }, "title": "TopicListOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/topic.messages/invoke": { "post": { "operationId": "invokeSkill_topic_messages", "summary": "Read a Topic conversation's messages (user + assistant turns, chronological, paginated) \u2014 the pick-it-up-anywhere reader: poll a running topic_ask for its answer, or read turns that happened on the web. Never creates a conversation.", "tags": [ "topics" ], "x-skill-name": "topic.messages", "x-skill-slug": "topic_messages", "x-skill-category": "topics", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "topic_id": { "description": "Topic permakey (preferred) or UUID", "title": "Topic Id", "type": "string" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Conversation in the topic to read; omitted = the topic's most-recent conversation (the reader never creates one)", "title": "Conversation Id" }, "limit": { "default": 20, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" }, "offset": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } }, "required": [ "topic_id" ], "title": "TopicMessagesInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "topic_messages" }, "output": { "$defs": { "TopicMessage": { "properties": { "message_id": { "default": "", "title": "Message Id", "type": "string" }, "role": { "default": "", "title": "Role", "type": "string" }, "content": { "default": "", "title": "Content", "type": "string" }, "created_at": { "default": "", "title": "Created At", "type": "string" }, "query_id": { "default": "", "title": "Query Id", "type": "string" }, "model_used": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Model Used" }, "citations": { "items": { "additionalProperties": true, "type": "object" }, "title": "Citations", "type": "array" }, "artifacts": { "items": {}, "title": "Artifacts", "type": "array" } }, "title": "TopicMessage", "type": "object" } }, "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "topic_id": { "default": "", "description": "The topic's permakey (the public id).", "title": "Topic Id", "type": "string" }, "permakey": { "default": "", "description": "The 7-char public topic id \u2014 THE id to show users and reuse in later topic_* calls (UUIDs are internal).", "title": "Permakey", "type": "string" }, "conversation_id": { "default": "", "title": "Conversation Id", "type": "string" }, "messages": { "items": { "$ref": "#/$defs/TopicMessage" }, "title": "Messages", "type": "array" }, "total": { "default": 0, "title": "Total", "type": "integer" } }, "title": "TopicMessagesOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/topic.post.message/invoke": { "post": { "operationId": "invokeSkill_topic_post_message", "summary": "Post a message into a Topic conversation and dispatch the turn (fire-and-return: poll the conversation for the answer). Auto-creates and links a conversation when the topic has none.", "tags": [ "topics" ], "x-skill-name": "topic.post.message", "x-skill-slug": "topic_post_message", "x-skill-category": "topics", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "topic_id": { "description": "Topic permakey (preferred) or UUID", "title": "Topic Id", "type": "string" }, "message": { "maxLength": 20000, "minLength": 1, "title": "Message", "type": "string" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Existing conversation in the topic; omitted = the topic's most-recent conversation, auto-created+linked if none exists", "title": "Conversation Id" } }, "required": [ "topic_id", "message" ], "title": "TopicPostMessageInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "topic_post_message" }, "output": { "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "topic_id": { "default": "", "description": "The topic's permakey (the public id).", "title": "Topic Id", "type": "string" }, "permakey": { "default": "", "description": "The 7-char public topic id \u2014 THE id to show users and reuse in later topic_* calls (UUIDs are internal).", "title": "Permakey", "type": "string" }, "conversation_id": { "default": "", "title": "Conversation Id", "type": "string" }, "message_id": { "default": "", "title": "Message Id", "type": "string" }, "query_id": { "default": "", "title": "Query Id", "type": "string" }, "status": { "default": "submitted", "title": "Status", "type": "string" } }, "title": "TopicPostMessageOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/topic.update/invoke": { "post": { "operationId": "invokeSkill_topic_update", "summary": "Update a Topic's metadata \u2014 rename (name), retitle, set type / theme_color / status / description / icon, or rebind client_id. Only the provided fields change. Set status='active' to unarchive; soft-deleted topics are terminal (answer not-found).", "tags": [ "topics" ], "x-skill-name": "topic.update", "x-skill-slug": "topic_update", "x-skill-category": "topics", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "topic_id": { "description": "Topic permakey (preferred) or UUID", "title": "Topic Id", "type": "string" }, "name": { "anyOf": [ { "maxLength": 200, "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "New topic name (rename)", "title": "Name" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "client | matter | process_period | advisory | compliance | internal", "title": "Type" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "active | archived. Set 'active' to unarchive; soft-deleted topics are terminal and answer not-found.", "title": "Status" }, "theme_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Hex like #DAFBE1", "title": "Theme Color" }, "client_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "UUID of the client to bind", "title": "Client Id" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Free-text topic description", "title": "Description" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Topic icon", "title": "Icon" } }, "required": [ "topic_id" ], "title": "TopicUpdateInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "topic_update" }, "output": { "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "topic_id": { "default": "", "description": "The topic's permakey (the public id).", "title": "Topic Id", "type": "string" }, "permakey": { "default": "", "description": "The 7-char public topic id \u2014 THE id to show users and reuse in later topic_* calls (UUIDs are internal).", "title": "Permakey", "type": "string" }, "name": { "default": "", "title": "Name", "type": "string" }, "type": { "default": "", "title": "Type", "type": "string" }, "status": { "default": "", "title": "Status", "type": "string" } }, "title": "TopicUpdateOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/transactions.classify/invoke": { "post": { "operationId": "invokeSkill_transactions_classify", "summary": "Classify a financial transaction to chart-of-accounts code.", "tags": [ "transactions" ], "x-skill-name": "transactions.classify", "x-skill-slug": "classify_transaction", "x-skill-category": "transactions", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "description": { "title": "Description", "type": "string" }, "amount": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ], "title": "Amount" }, "currency": { "default": "AUD", "title": "Currency", "type": "string" }, "transaction_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "default": null, "title": "Transaction Date" }, "vendor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Vendor" } }, "required": [ "description", "amount" ], "title": "ClassifyTransactionInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "classify_transaction" }, "output": { "$defs": { "Alternative": { "properties": { "account_code": { "title": "Account Code", "type": "string" }, "account_name": { "title": "Account Name", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "account_code", "account_name" ], "title": "Alternative", "type": "object" } }, "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "account_code": { "default": "", "title": "Account Code", "type": "string" }, "account_name": { "default": "", "title": "Account Name", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" }, "alternatives": { "items": { "$ref": "#/$defs/Alternative" }, "title": "Alternatives", "type": "array" }, "tax_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Tax Code" } }, "title": "ClassifyTransactionOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/wealth.advise/invoke": { "post": { "operationId": "invokeSkill_wealth_advise", "summary": "Wealth management advice \u2014 investment structures, retirement, asset protection.", "tags": [ "advisory" ], "x-skill-name": "wealth.advise", "x-skill-slug": "advise_wealth", "x-skill-category": "advisory", "x-skill-cluster": "WLT", "x-skill-streaming": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "topic": { "maxLength": 5000, "title": "Topic", "type": "string" }, "jurisdiction": { "anyOf": [ { "enum": [ "AU", "GB", "CA", "US", "NZ" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Jurisdiction" }, "wealth_mode": { "default": "advisory", "enum": [ "advisory", "retirement", "asset_protection", "investment" ], "title": "Wealth Mode", "type": "string" }, "client_context": { "additionalProperties": true, "title": "Client Context", "type": "object" } }, "required": [ "topic" ], "title": "AdviseWealthInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "advise_wealth" }, "output": { "$defs": { "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" } }, "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "advice": { "default": "", "title": "Advice", "type": "string" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" }, "caveats": { "items": { "type": "string" }, "title": "Caveats", "type": "array" }, "disclaimer": { "default": "General information only \u2014 does not constitute personal financial advice.", "title": "Disclaimer", "type": "string" } }, "title": "AdviseWealthOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/wealth.succession.advise/invoke": { "post": { "operationId": "invokeSkill_wealth_succession_advise", "summary": "Succession planning \u2014 family business transition, buy-sell, ownership transfer, governance.", "tags": [ "advisory" ], "x-skill-name": "wealth.succession.advise", "x-skill-slug": "advise_succession", "x-skill-category": "advisory", "x-skill-cluster": "WLT", "x-skill-streaming": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "topic": { "maxLength": 5000, "title": "Topic", "type": "string" }, "jurisdiction": { "anyOf": [ { "enum": [ "AU", "GB", "CA", "US", "NZ" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Jurisdiction" }, "succession_mode": { "default": "family_business", "enum": [ "family_business", "buy_sell", "ownership_transfer", "governance" ], "title": "Succession Mode", "type": "string" }, "client_context": { "additionalProperties": true, "title": "Client Context", "type": "object" } }, "required": [ "topic" ], "title": "AdviseSuccessionInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "advise_succession" }, "output": { "$defs": { "Citation": { "properties": { "standard": { "title": "Standard", "type": "string" }, "section": { "default": "", "title": "Section", "type": "string" }, "url": { "default": "", "title": "Url", "type": "string" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "required": [ "standard" ], "title": "ProtocolSkills__Citation", "type": "object" } }, "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "advice": { "default": "", "title": "Advice", "type": "string" }, "plan_steps": { "items": { "type": "string" }, "title": "Plan Steps", "type": "array" }, "citations": { "items": { "$ref": "#/$defs/Citation" }, "title": "Citations", "type": "array" }, "open_items": { "items": { "type": "string" }, "title": "Open Items", "type": "array" }, "confidence": { "default": 0.0, "title": "Confidence", "type": "number" } }, "title": "AdviseSuccessionOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/workflows.decide/invoke": { "post": { "operationId": "invokeSkill_workflows_decide", "summary": "(Utility) Approve or reject a workflow item.", "tags": [ "utility" ], "x-skill-name": "workflows.decide", "x-skill-slug": "approve_or_reject", "x-skill-category": "utility", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "item_id": { "format": "uuid", "title": "Item Id", "type": "string" }, "decision": { "enum": [ "approve", "reject", "request_changes" ], "title": "Decision", "type": "string" }, "reason": { "default": "", "title": "Reason", "type": "string" }, "delegated_by": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Delegated By" } }, "required": [ "item_id", "decision" ], "title": "ApproveOrRejectInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "approve_or_reject" }, "output": { "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "approval_id": { "format": "uuid", "title": "Approval Id", "type": "string" }, "status": { "default": "", "title": "Status", "type": "string" }, "next_step": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Next Step" }, "notification_sent": { "default": false, "title": "Notification Sent", "type": "boolean" } }, "title": "ApproveOrRejectOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/workstream.advance/invoke": { "post": { "operationId": "invokeSkill_workstream_advance", "summary": "Advance a paused or awaiting-approval workstream run \u2014 approve a task, skip a step, pause, or resume. This is the supervisory surface; for starting a new run use workstream_run, for cancelling use workstream_cancel.", "tags": [ "WorkStreams" ], "x-skill-name": "workstream.advance", "x-skill-slug": "workstream_advance", "x-skill-category": "workstreams", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Drive a paused or awaiting-approval cycle forward.\n\nThe canonical field is ``cycle_id``; ``run_id`` is accepted as a\ndeprecated alias for backwards compat. ``cycle_id`` accepts a UUID\nor a 7-char permakey (resolved workspace-scoped by the handler).", "properties": { "cycle_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "string" } ], "description": "The cycle to advance (UUID or permakey).", "title": "Cycle Id" }, "action": { "description": "What to do:\n- `approve_task`: mark the task in `task_id` approved; the run moves on.\n- `skip_step`: skip the current step.\n- `pause`: halt the run in-place.\n- `resume`: continue a previously paused run.", "enum": [ "approve_task", "skip_step", "pause", "resume" ], "title": "Action", "type": "string" }, "task_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "Required for `approve_task`. The task being approved.", "title": "Task Id" }, "reason": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ], "default": null, "description": "Audit trail. Recommended for skip_step.", "title": "Reason" }, "idempotency_key": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "default": null, "description": "Caller-supplied stable token. Replaying within 24h returns the same outcome rather than re-applying the action.", "title": "Idempotency Key" } }, "required": [ "cycle_id", "action" ], "title": "WorkstreamAdvanceInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "workstream_advance" }, "output": { "$defs": { "Error": { "description": "Canonical error envelope set on output models when a skill fails.\n\nUse ``error_envelope`` on any output where the bare ``error: str`` field\nis being phased out. Both fields will be populated during the migration\nwindow so SDK consumers don't break.", "properties": { "code": { "description": "Machine-readable error code in SCREAMING_SNAKE_CASE. Stable across releases \u2014 branch on this, not on `message`.", "examples": [ "WORKSTREAM_NOT_FOUND", "VALIDATION_FAILED", "RATE_LIMITED" ], "maxLength": 120, "title": "Code", "type": "string" }, "message": { "description": "Human-readable single-sentence summary suitable for surfacing to a user.", "maxLength": 500, "title": "Message", "type": "string" }, "details": { "anyOf": [ { "additionalProperties": { "$ref": "#/$defs/JsonValue" }, "type": "object" }, { "type": "null" } ], "default": null, "description": "Optional structured context \u2014 e.g. validation error paths, the offending input value, or upstream provider response codes.", "title": "Details" }, "retryable": { "default": false, "description": "True if the caller should safely retry the same request. When true, callers should pair the retry with the same `idempotency_key` they sent on the original request.", "title": "Retryable", "type": "boolean" } }, "required": [ "code", "message" ], "title": "ProtocolSkills__Error", "type": "object" }, "JsonValue": {} }, "description": "Cycle state after the action lands.", "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "cycle_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "The cycle the action was applied to.", "title": "Cycle Id" }, "run_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "deprecated": true, "title": "Run Id" }, "status": { "default": "running", "description": "Lifecycle state after the action.", "enum": [ "running", "paused", "awaiting_approval", "completed", "cancelled", "failed" ], "title": "Status", "type": "string" }, "current_step": { "default": "", "description": "Slug of the currently-executing step.", "title": "Current Step", "type": "string" }, "next_step": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Slug of the next step (None on terminal states).", "title": "Next Step" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "deprecated": true, "title": "Error" }, "error_envelope": { "anyOf": [ { "$ref": "#/$defs/Error" }, { "type": "null" } ], "default": null, "description": "Canonical structured error. Populated when the action could not be applied." } }, "title": "WorkstreamAdvanceOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/workstream.cancel/invoke": { "post": { "operationId": "invokeSkill_workstream_cancel", "summary": "Cancel a running workstream run. The run terminates; you'll need to start a fresh one if you want to retry. Reason is recorded to the audit trail and shown in Studio.", "tags": [ "WorkStreams" ], "x-skill-name": "workstream.cancel", "x-skill-slug": "workstream_cancel", "x-skill-category": "workstreams", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Identify the cycle to cancel.\n\nThe canonical field is ``cycle_id``; ``run_id`` is accepted as a\ndeprecated alias for backwards compat. ``cycle_id`` accepts a UUID\nor a 7-char permakey (resolved workspace-scoped by the handler).", "properties": { "cycle_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "string" } ], "description": "The cycle to cancel (UUID or permakey). Identified by `cycle_id` from `workstream_run`.", "title": "Cycle Id" }, "reason": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ], "default": null, "description": "Audit trail. Strongly recommended.", "title": "Reason" }, "idempotency_key": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "default": null, "description": "Caller-supplied stable token. Replaying within 24h returns the same cancellation result rather than erroring on the already-cancelled cycle.", "title": "Idempotency Key" } }, "required": [ "cycle_id" ], "title": "WorkstreamCancelInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "workstream_cancel" }, "output": { "$defs": { "Error": { "description": "Canonical error envelope set on output models when a skill fails.\n\nUse ``error_envelope`` on any output where the bare ``error: str`` field\nis being phased out. Both fields will be populated during the migration\nwindow so SDK consumers don't break.", "properties": { "code": { "description": "Machine-readable error code in SCREAMING_SNAKE_CASE. Stable across releases \u2014 branch on this, not on `message`.", "examples": [ "WORKSTREAM_NOT_FOUND", "VALIDATION_FAILED", "RATE_LIMITED" ], "maxLength": 120, "title": "Code", "type": "string" }, "message": { "description": "Human-readable single-sentence summary suitable for surfacing to a user.", "maxLength": 500, "title": "Message", "type": "string" }, "details": { "anyOf": [ { "additionalProperties": { "$ref": "#/$defs/JsonValue" }, "type": "object" }, { "type": "null" } ], "default": null, "description": "Optional structured context \u2014 e.g. validation error paths, the offending input value, or upstream provider response codes.", "title": "Details" }, "retryable": { "default": false, "description": "True if the caller should safely retry the same request. When true, callers should pair the retry with the same `idempotency_key` they sent on the original request.", "title": "Retryable", "type": "boolean" } }, "required": [ "code", "message" ], "title": "ProtocolSkills__Error", "type": "object" }, "JsonValue": {} }, "description": "Cycle state after cancellation.", "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "cycle_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "The cycle that was cancelled.", "title": "Cycle Id" }, "run_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "deprecated": true, "title": "Run Id" }, "status": { "default": "cancelled", "description": "`cancelled` on success; `failed` if the cancel signal could not be delivered.", "enum": [ "cancelled", "failed" ], "title": "Status", "type": "string" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "deprecated": true, "title": "Error" }, "error_envelope": { "anyOf": [ { "$ref": "#/$defs/Error" }, { "type": "null" } ], "default": null, "description": "Canonical structured error. Populated when `status == 'failed'`." } }, "title": "WorkstreamCancelOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/workstream.commit/invoke": { "post": { "operationId": "invokeSkill_workstream_commit", "summary": "Promote a workstream draft to an active, executable workstream definition. The draft must validate cleanly; the resulting workstream gets a new permakey and becomes runnable via workstream_run.", "tags": [ "authoring" ], "x-skill-name": "workstream.commit", "x-skill-slug": "workstream_commit", "x-skill-category": "authoring", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Promote a draft to a real, executable workstream.", "properties": { "draft_id": { "description": "The draft id from `workstream_draft.draft_id`.", "format": "uuid", "title": "Draft Id", "type": "string" }, "scope": { "default": "firm", "description": "Authoring scope for the committed workstream.", "enum": [ "user", "team", "firm" ], "title": "Scope", "type": "string" }, "name": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional final name. Defaults to the draft's working name. Cannot collide with another active workstream in the workspace.", "title": "Name" }, "idempotency_key": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "default": null, "description": "Caller-supplied stable token. Replaying within 24h returns the previously-created workstream id rather than erroring on the name collision.", "title": "Idempotency Key" } }, "required": [ "draft_id" ], "title": "WorkstreamCommitInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "workstream_commit" }, "output": { "$defs": { "Error": { "description": "Canonical error envelope set on output models when a skill fails.\n\nUse ``error_envelope`` on any output where the bare ``error: str`` field\nis being phased out. Both fields will be populated during the migration\nwindow so SDK consumers don't break.", "properties": { "code": { "description": "Machine-readable error code in SCREAMING_SNAKE_CASE. Stable across releases \u2014 branch on this, not on `message`.", "examples": [ "WORKSTREAM_NOT_FOUND", "VALIDATION_FAILED", "RATE_LIMITED" ], "maxLength": 120, "title": "Code", "type": "string" }, "message": { "description": "Human-readable single-sentence summary suitable for surfacing to a user.", "maxLength": 500, "title": "Message", "type": "string" }, "details": { "anyOf": [ { "additionalProperties": { "$ref": "#/$defs/JsonValue" }, "type": "object" }, { "type": "null" } ], "default": null, "description": "Optional structured context \u2014 e.g. validation error paths, the offending input value, or upstream provider response codes.", "title": "Details" }, "retryable": { "default": false, "description": "True if the caller should safely retry the same request. When true, callers should pair the retry with the same `idempotency_key` they sent on the original request.", "title": "Retryable", "type": "boolean" } }, "required": [ "code", "message" ], "title": "ProtocolSkills__Error", "type": "object" }, "JsonValue": {} }, "description": "Pointer to the committed workstream.", "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "workstream_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "Newly-created workstream id.", "title": "Workstream Id" }, "permakey": { "default": "", "description": "7-char human-friendly id for URLs and Slack.", "title": "Permakey", "type": "string" }, "status": { "default": "active", "description": "`active` on success; `draft` if commit failed validation and the draft still exists.", "enum": [ "draft", "active" ], "title": "Status", "type": "string" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "deprecated": true, "title": "Error" }, "error_envelope": { "anyOf": [ { "$ref": "#/$defs/Error" }, { "type": "null" } ], "default": null, "description": "Canonical structured error. Populated when commit failed." } }, "title": "WorkstreamCommitOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/workstream.delete/invoke": { "post": { "operationId": "invokeSkill_workstream_delete", "summary": "Delete a workstream \u2014 a guarded soft-delete (status='deleted'); it disappears from listings but the row is retained. REFUSES if the workstream has any non-terminal (running/paused/queued) cycle, and requires an explicit confirm=true. In-flight cycles are unaffected.", "tags": [ "WorkStreams" ], "x-skill-name": "workstream.delete", "x-skill-slug": "workstream_delete", "x-skill-category": "workstreams", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "workstream_id": { "description": "Workstream UUID, slug, or 7-char permakey to delete", "title": "Workstream Id", "type": "string" }, "confirm": { "default": false, "description": "Explicit confirmation. Must be true to proceed \u2014 a delete with confirm=false is refused (error='confirmation_required'), so an accidental call is a safe no-op.", "title": "Confirm", "type": "boolean" } }, "required": [ "workstream_id" ], "title": "WorkstreamDeleteInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "workstream_delete" }, "output": { "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "workstream_id": { "default": "", "description": "The deleted workstream's permakey (the public id).", "title": "Workstream Id", "type": "string" }, "deleted": { "default": false, "description": "True when the workstream was soft-deleted.", "title": "Deleted", "type": "boolean" }, "status": { "default": "", "description": "The workstream's status after the call (e.g. 'deleted').", "title": "Status", "type": "string" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "missing_workspace | not_found | confirmation_required | has_active_cycles on failure, else null", "title": "Error" } }, "title": "WorkstreamDeleteOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/workstream.describe/invoke": { "post": { "operationId": "invokeSkill_workstream_describe", "summary": "Describe a workstream by id, slug, or permakey. Returns the full definition: metadata, execution_mode, declared inputs, and step count. The adapter resolves the literal across both inline and containerized execution modes.", "tags": [ "WorkStreams" ], "x-skill-name": "workstream.describe", "x-skill-slug": "workstream_describe", "x-skill-category": "workstreams", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Identify a workstream to describe.", "properties": { "workstream_id": { "description": "UUID, slug, or 7-char permakey. The adapter resolves it.", "examples": [ "7f3c8d9e-1a2b-4c5d-8e6f-901234567890", "month-end-close", "abc1234" ], "title": "Workstream Id", "type": "string" } }, "required": [ "workstream_id" ], "title": "WorkstreamDescribeInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "workstream_describe" }, "output": { "$defs": { "Error": { "description": "Canonical error envelope set on output models when a skill fails.\n\nUse ``error_envelope`` on any output where the bare ``error: str`` field\nis being phased out. Both fields will be populated during the migration\nwindow so SDK consumers don't break.", "properties": { "code": { "description": "Machine-readable error code in SCREAMING_SNAKE_CASE. Stable across releases \u2014 branch on this, not on `message`.", "examples": [ "WORKSTREAM_NOT_FOUND", "VALIDATION_FAILED", "RATE_LIMITED" ], "maxLength": 120, "title": "Code", "type": "string" }, "message": { "description": "Human-readable single-sentence summary suitable for surfacing to a user.", "maxLength": 500, "title": "Message", "type": "string" }, "details": { "anyOf": [ { "additionalProperties": { "$ref": "#/$defs/JsonValue" }, "type": "object" }, { "type": "null" } ], "default": null, "description": "Optional structured context \u2014 e.g. validation error paths, the offending input value, or upstream provider response codes.", "title": "Details" }, "retryable": { "default": false, "description": "True if the caller should safely retry the same request. When true, callers should pair the retry with the same `idempotency_key` they sent on the original request.", "title": "Retryable", "type": "boolean" } }, "required": [ "code", "message" ], "title": "ProtocolSkills__Error", "type": "object" }, "JsonValue": {} }, "description": "Full definition of a workstream \u2014 metadata + step graph.", "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "workstream_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "Stable internal id.", "title": "Workstream Id" }, "permakey": { "default": "", "description": "7-char human-friendly id.", "title": "Permakey", "type": "string" }, "name": { "default": "", "description": "Display name.", "title": "Name", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "One-paragraph overview.", "title": "Description" }, "execution_mode": { "default": "inline", "description": "`inline` (Temporal declarative) or `containerized` (Fly.io agentic).", "enum": [ "inline", "containerized" ], "title": "Execution Mode", "type": "string" }, "status": { "default": "draft", "description": "Lifecycle state.", "enum": [ "draft", "active", "archived" ], "title": "Status", "type": "string" }, "step_count": { "default": 0, "description": "Number of declared steps in the workstream graph.", "minimum": 0, "title": "Step Count", "type": "integer" }, "inputs_required": { "description": "Declaration of every input the caller can or must supply via `runtime_vars` when starting a cycle. Each entry follows the `WorkstreamInputSpec` shape (name, type, required, description, default) but is wire-typed as a JSON object for backward compatibility with stored authoring metadata. Empty for client-agnostic workstreams that take no runtime inputs.", "items": { "additionalProperties": { "$ref": "#/$defs/JsonValue" }, "type": "object" }, "title": "Inputs Required", "type": "array" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "deprecated": true, "title": "Error" }, "error_envelope": { "anyOf": [ { "$ref": "#/$defs/Error" }, { "type": "null" } ], "default": null, "description": "Canonical structured error. Set when describe failed (e.g. workstream not found, FGA denied). The legacy `error` string field is populated alongside it for back-compat." } }, "title": "WorkstreamDescribeOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/workstream.design/invoke": { "post": { "operationId": "invokeSkill_workstream_design", "summary": "Specify a WorkStream before drafting its steps \u2014 runs the pre-flight interview and returns the spec: the decisions, each with its question, the builder's proposal, its reason, its citation, and its status. Persists to the spec store so the spec can be read back (workstream_spec) and open decisions answered (workstream_spec_answer). Does NOT propose steps and does NOT create a WorkStream \u2014 that is workstream_draft's job, unchanged.", "tags": [ "authoring" ], "x-skill-name": "workstream.design", "x-skill-slug": "workstream_design", "x-skill-category": "authoring", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Run the pre-flight interview and return the WorkStream spec.\n\nSame resumption contract as ``workstream_draft`` (``draft_key`` +\n``prior_draft_id`` + ``thread``) \u2014 design IS the draft interview, stopped\nbefore the proposal. ``prior_draft_id`` addresses the draft under revision,\nnot a finished WorkStream (design never creates one).", "properties": { "description": { "description": "Natural-language description of the workstream to specify.", "examples": [ "Monthly close for SaaS clients with deferred revenue tracking." ], "maxLength": 4000, "minLength": 1, "title": "Description", "type": "string" }, "topic_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Topic to anchor the design interview to \u2014 permakey (preferred) or UUID.", "title": "Topic Id" }, "prior_draft_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional prior draft to iterate on instead of starting a new interview.", "title": "Prior Draft Id" }, "name": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional working name; context for the authoring agent, not a constraint.", "title": "Name" }, "file_ids": { "description": "Source documents the questions come from. With none, the tool says it has nothing to read rather than asking generic shape questions.", "items": { "format": "uuid", "type": "string" }, "title": "File Ids", "type": "array" }, "thread": { "description": "Prior authoring frames/messages for one-question-at-a-time refinement.", "items": { "additionalProperties": true, "type": "object" }, "maxItems": 100, "title": "Thread", "type": "array" }, "draft_key": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "default": null, "description": "Stable caller identity for this conversational interview.", "title": "Draft Key" }, "target_execution_mode": { "default": "inline", "description": "Canonical authoring creates inline WorkStreams. The legacy containerized authoring destination is refused; bounded agentic work uses agent_run steps.", "enum": [ "inline", "containerized" ], "title": "Target Execution Mode", "type": "string" }, "idempotency_key": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "default": null, "description": "Caller-supplied stable token. Replaying within 24h resumes the same interview rather than starting a duplicate.", "title": "Idempotency Key" } }, "required": [ "description" ], "title": "WorkstreamDesignInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "workstream_design" }, "output": { "$defs": { "Error": { "description": "Canonical error envelope set on output models when a skill fails.\n\nUse ``error_envelope`` on any output where the bare ``error: str`` field\nis being phased out. Both fields will be populated during the migration\nwindow so SDK consumers don't break.", "properties": { "code": { "description": "Machine-readable error code in SCREAMING_SNAKE_CASE. Stable across releases \u2014 branch on this, not on `message`.", "examples": [ "WORKSTREAM_NOT_FOUND", "VALIDATION_FAILED", "RATE_LIMITED" ], "maxLength": 120, "title": "Code", "type": "string" }, "message": { "description": "Human-readable single-sentence summary suitable for surfacing to a user.", "maxLength": 500, "title": "Message", "type": "string" }, "details": { "anyOf": [ { "additionalProperties": { "$ref": "#/$defs/JsonValue" }, "type": "object" }, { "type": "null" } ], "default": null, "description": "Optional structured context \u2014 e.g. validation error paths, the offending input value, or upstream provider response codes.", "title": "Details" }, "retryable": { "default": false, "description": "True if the caller should safely retry the same request. When true, callers should pair the retry with the same `idempotency_key` they sent on the original request.", "title": "Retryable", "type": "boolean" } }, "required": [ "code", "message" ], "title": "ProtocolSkills__Error", "type": "object" }, "JsonValue": {} }, "description": "The interview's spec: decisions with question/proposal/reason/citation/status.\n\nDesign stops BEFORE the proposal: no step list, no draft id. The decisions\npersist to the AR-724 spec store so ``workstream_spec`` can read them back\nand ``workstream_spec_answer`` can answer one open decision.", "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "decisions": { "description": "The spec's decisions \u2014 each with its question, the builder's proposal, its reason, its citation, and its status (open/answered).", "items": { "additionalProperties": true, "type": "object" }, "title": "Decisions", "type": "array" }, "spec_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Content address of the persisted spec; changes when an answer changes.", "title": "Spec Hash" }, "question": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "One material clarification to answer on the next turn.", "title": "Question" }, "frames": { "description": "Visible research, tool, and question transcript for this turn.", "items": { "additionalProperties": true, "type": "object" }, "title": "Frames", "type": "array" }, "authoring_provenance": { "additionalProperties": true, "description": "Logical role, exact provider/model and content-addressed contract version.", "title": "Authoring Provenance", "type": "object" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "deprecated": true, "title": "Error" }, "error_envelope": { "anyOf": [ { "$ref": "#/$defs/Error" }, { "type": "null" } ], "default": null, "description": "Canonical structured error. Populated on interview failure." } }, "title": "WorkstreamDesignOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/workstream.draft/invoke": { "post": { "operationId": "invokeSkill_workstream_draft", "summary": "Draft a new workstream conversationally \u2014 describe what you want and Archie produces a structured, reviewable workstream definition with typed steps, dependencies, and validation. Produces unified drafts targeting either inline or containerized execution mode. The canonical drafting entry; the legacy `playbook.creator` slug is retained only for API back-compat.", "tags": [ "authoring" ], "x-skill-name": "workstream.draft", "x-skill-slug": "workstream_draft", "x-skill-category": "authoring", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Start or continue a canonical, document-aware WorkStream draft.", "properties": { "description": { "description": "Natural-language description of the workstream to draft.", "examples": [ "Monthly close for SaaS clients with deferred revenue tracking." ], "maxLength": 4000, "minLength": 1, "title": "Description", "type": "string" }, "topic_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Topic to anchor the draft to \u2014 permakey (preferred) or UUID.", "title": "Topic Id" }, "prior_draft_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional prior draft to iterate on instead of creating a new one.", "title": "Prior Draft Id" }, "name": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional working name; context for the authoring agent, not a constraint.", "title": "Name" }, "file_ids": { "description": "Source documents the authoring agent must read completely before drafting.", "items": { "format": "uuid", "type": "string" }, "title": "File Ids", "type": "array" }, "thread": { "description": "Prior authoring frames/messages for one-question-at-a-time refinement.", "items": { "additionalProperties": true, "type": "object" }, "maxItems": 100, "title": "Thread", "type": "array" }, "draft_key": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "default": null, "description": "Stable caller identity for this conversational draft.", "title": "Draft Key" }, "target_execution_mode": { "default": "inline", "description": "Canonical authoring creates inline WorkStreams. The legacy containerized authoring destination is refused; bounded agentic work uses agent_run steps.", "enum": [ "inline", "containerized" ], "title": "Target Execution Mode", "type": "string" }, "idempotency_key": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "default": null, "description": "Caller-supplied stable token. Replaying within 24h returns the previously-created draft id rather than generating a duplicate.", "title": "Idempotency Key" } }, "required": [ "description" ], "title": "WorkstreamDraftInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "workstream_draft" }, "output": { "$defs": { "Error": { "description": "Canonical error envelope set on output models when a skill fails.\n\nUse ``error_envelope`` on any output where the bare ``error: str`` field\nis being phased out. Both fields will be populated during the migration\nwindow so SDK consumers don't break.", "properties": { "code": { "description": "Machine-readable error code in SCREAMING_SNAKE_CASE. Stable across releases \u2014 branch on this, not on `message`.", "examples": [ "WORKSTREAM_NOT_FOUND", "VALIDATION_FAILED", "RATE_LIMITED" ], "maxLength": 120, "title": "Code", "type": "string" }, "message": { "description": "Human-readable single-sentence summary suitable for surfacing to a user.", "maxLength": 500, "title": "Message", "type": "string" }, "details": { "anyOf": [ { "additionalProperties": { "$ref": "#/$defs/JsonValue" }, "type": "object" }, { "type": "null" } ], "default": null, "description": "Optional structured context \u2014 e.g. validation error paths, the offending input value, or upstream provider response codes.", "title": "Details" }, "retryable": { "default": false, "description": "True if the caller should safely retry the same request. When true, callers should pair the retry with the same `idempotency_key` they sent on the original request.", "title": "Retryable", "type": "boolean" } }, "required": [ "code", "message" ], "title": "ProtocolSkills__Error", "type": "object" }, "JsonValue": {} }, "description": "Visible draft identity or the next single material clarification.", "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "draft_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "Newly-created draft id.", "title": "Draft Id" }, "name": { "default": "", "description": "Working name the LLM gave the draft.", "title": "Name", "type": "string" }, "step_count": { "default": 0, "description": "Number of steps the LLM generated.", "minimum": 0, "title": "Step Count", "type": "integer" }, "target_execution_mode": { "default": "inline", "description": "Execution mode the draft was generated for.", "enum": [ "inline", "containerized" ], "title": "Target Execution Mode", "type": "string" }, "validation_warning_count": { "default": 0, "description": "Number of validation warnings on the draft. Non-zero is fine for drafts; commit will reject if any blocking warnings remain.", "minimum": 0, "title": "Validation Warning Count", "type": "integer" }, "version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Persisted WorkStream version.", "title": "Version" }, "status": { "anyOf": [ { "const": "draft", "type": "string" }, { "type": "null" } ], "default": null, "description": "Explicit lifecycle status; authoring never activates the WorkStream.", "title": "Status" }, "question": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "One material clarification to answer on the next turn.", "title": "Question" }, "frames": { "description": "Visible research, tool, question and proposal transcript for this turn.", "items": { "additionalProperties": true, "type": "object" }, "title": "Frames", "type": "array" }, "authoring_provenance": { "additionalProperties": true, "description": "Logical role, exact provider/model and content-addressed contract version.", "title": "Authoring Provenance", "type": "object" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "deprecated": true, "title": "Error" }, "error_envelope": { "anyOf": [ { "$ref": "#/$defs/Error" }, { "type": "null" } ], "default": null, "description": "Canonical structured error. Populated on draft generation failure." } }, "title": "WorkstreamDraftOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/workstream.duplicate/invoke": { "post": { "operationId": "invokeSkill_workstream_duplicate", "summary": "Duplicate a workstream \u2014 create a copy of its definition with a new name (defaults to 'Copy of '), reset to version 1 in draft status. The original is unchanged.", "tags": [ "WorkStreams" ], "x-skill-name": "workstream.duplicate", "x-skill-slug": "workstream_duplicate", "x-skill-category": "workstreams", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "workstream_id": { "description": "Workstream UUID, slug, or 7-char permakey to copy", "title": "Workstream Id", "type": "string" }, "new_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Name for the copy (defaults to 'Copy of ')", "title": "New Name" } }, "required": [ "workstream_id" ], "title": "WorkstreamDuplicateInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "workstream_duplicate" }, "output": { "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "workstream_id": { "default": "", "description": "The NEW copy's permakey (the public id).", "title": "Workstream Id", "type": "string" }, "permakey": { "default": "", "description": "7-char public id of the copy.", "title": "Permakey", "type": "string" }, "name": { "default": "", "title": "Name", "type": "string" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "missing_workspace | not_found on failure, else null", "title": "Error" } }, "title": "WorkstreamDuplicateOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/workstream.list/invoke": { "post": { "operationId": "invokeSkill_workstream_list", "summary": "List workstreams visible to the caller. Filter by scope (plan / user / team / firm / gallery) and lifecycle status. Returns summary rows including execution_mode so callers can distinguish inline (Temporal-native, declarative) from container (Fly.io, agentic) workstreams.", "tags": [ "WorkStreams" ], "x-skill-name": "workstream.list", "x-skill-slug": "workstream_list", "x-skill-category": "workstreams", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Filter the workstream catalogue.", "properties": { "scope": { "anyOf": [ { "enum": [ "plan", "user", "team", "firm", "gallery" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "Limit to workstreams of this authoring scope.", "title": "Scope" }, "status": { "anyOf": [ { "enum": [ "draft", "active", "archived" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "Limit to workstreams with this lifecycle status.", "title": "Status" }, "limit": { "default": 20, "description": "Maximum rows per page (1..100). Defaults to 20.", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" }, "cursor": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "default": null, "description": "Opaque pagination cursor from a previous response's `next_cursor`. Omit on the first call. The server treats the cursor as opaque \u2014 do not parse or construct it.", "title": "Cursor" } }, "title": "WorkstreamListInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "workstream_list" }, "output": { "$defs": { "WorkstreamSummary": { "description": "One row in the workstream list.", "properties": { "workstream_id": { "description": "Stable internal id.", "format": "uuid", "title": "Workstream Id", "type": "string" }, "permakey": { "description": "7-char human-friendly id; safe for URLs and Slack mentions.", "examples": [ "abc1234" ], "title": "Permakey", "type": "string" }, "name": { "description": "Display name authored by the workstream owner.", "title": "Name", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional one-paragraph overview from the workstream owner.", "title": "Description" }, "execution_mode": { "description": "`inline` (Temporal-native, declarative) or `containerized` (Fly.io, agentic).", "enum": [ "inline", "containerized" ], "title": "Execution Mode", "type": "string" }, "status": { "description": "Lifecycle state.", "enum": [ "draft", "active", "archived" ], "title": "Status", "type": "string" } }, "required": [ "workstream_id", "permakey", "name", "execution_mode", "status" ], "title": "WorkstreamSummary", "type": "object" } }, "description": "List of workstreams the caller can see, with cursor pagination.", "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "items": { "description": "Page of workstreams matching the input filters.", "items": { "$ref": "#/$defs/WorkstreamSummary" }, "title": "Items", "type": "array" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pass back as `cursor` on the next call to get the following page. `None` when there are no more pages.", "title": "Next Cursor" }, "total": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null, "description": "Total matching rows across all pages. `None` when the backend cannot count cheaply (very large datasets).", "title": "Total" } }, "title": "WorkstreamListOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/workstream.run/invoke": { "post": { "operationId": "invokeSkill_workstream_run", "summary": "Start a workstream run against the supplied client / period / runtime variables. Returns a run_id you can poll with workstream_status, events_url for live SSE progress, and detail_url to open the run in Workstream Studio. The query_id in the output is the join key for Slack\u2192Studio deep-links.", "tags": [ "WorkStreams" ], "x-skill-name": "workstream.run", "x-skill-slug": "workstream_run", "x-skill-category": "workstreams", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$defs": { "JsonValue": {} }, "description": "Start a workstream cycle.", "properties": { "workstream_id": { "description": "UUID, slug, or 7-char permakey. The adapter resolves it.", "examples": [ "7f3c8d9e-1a2b-4c5d-8e6f-901234567890", "month-end-close", "abc1234" ], "title": "Workstream Id", "type": "string" }, "client_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "Client to run against. Optional for client-agnostic workstreams.", "title": "Client Id" }, "period": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Period label (e.g., 'FY26-Q1', '2026-04').", "examples": [ "FY26-Q1", "2026-04" ], "title": "Period" }, "runtime_vars": { "additionalProperties": { "$ref": "#/$defs/JsonValue" }, "description": "Runtime overrides for the workstream's declared inputs. Keys are input names from `WorkstreamDescribeOutput.inputs_required`; values are JSON-typed (string, number, boolean, array, object, null).", "title": "Runtime Vars", "type": "object" }, "idempotency_key": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "default": null, "description": "Caller-supplied stable token (\u2264200 chars). When the same key is replayed within 24h the API returns the original cycle id rather than starting a duplicate run. Strongly recommended for any automated retry loop.", "examples": [ "close-2026-04-acme-001" ], "title": "Idempotency Key" } }, "required": [ "workstream_id" ], "title": "WorkstreamRunInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "workstream_run" }, "output": { "$defs": { "Error": { "description": "Canonical error envelope set on output models when a skill fails.\n\nUse ``error_envelope`` on any output where the bare ``error: str`` field\nis being phased out. Both fields will be populated during the migration\nwindow so SDK consumers don't break.", "properties": { "code": { "description": "Machine-readable error code in SCREAMING_SNAKE_CASE. Stable across releases \u2014 branch on this, not on `message`.", "examples": [ "WORKSTREAM_NOT_FOUND", "VALIDATION_FAILED", "RATE_LIMITED" ], "maxLength": 120, "title": "Code", "type": "string" }, "message": { "description": "Human-readable single-sentence summary suitable for surfacing to a user.", "maxLength": 500, "title": "Message", "type": "string" }, "details": { "anyOf": [ { "additionalProperties": { "$ref": "#/$defs/JsonValue" }, "type": "object" }, { "type": "null" } ], "default": null, "description": "Optional structured context \u2014 e.g. validation error paths, the offending input value, or upstream provider response codes.", "title": "Details" }, "retryable": { "default": false, "description": "True if the caller should safely retry the same request. When true, callers should pair the retry with the same `idempotency_key` they sent on the original request.", "title": "Retryable", "type": "boolean" } }, "required": [ "code", "message" ], "title": "ProtocolSkills__Error", "type": "object" }, "JsonValue": {} }, "description": "Pointer to the new cycle + URLs the caller can use to monitor / open it.\n\nThe canonical noun is ``cycle`` (Workstream \u2192 Blueprint \u2192 Cycle \u2192 Task).\nThe legacy ``run_id`` field is kept populated alongside ``cycle_id``\nfor backwards compat with SDK consumers; new code should read\n``cycle_id`` and treat ``run_id`` as deprecated.", "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "cycle_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "The cycle id of the launched workstream cycle.", "title": "Cycle Id" }, "run_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "deprecated": true, "title": "Run Id" }, "status": { "default": "pending", "enum": [ "pending", "running", "awaiting_approval" ], "title": "Status", "type": "string" }, "execution_mode": { "default": "inline", "enum": [ "inline", "containerized" ], "title": "Execution Mode", "type": "string" }, "query_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Query Id" }, "events_url": { "default": "", "title": "Events Url", "type": "string" }, "detail_url": { "default": "", "title": "Detail Url", "type": "string" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "deprecated": true, "title": "Error" }, "error_envelope": { "anyOf": [ { "$ref": "#/$defs/Error" }, { "type": "null" } ], "default": null, "description": "Canonical structured error. Set when the cycle failed to start (workstream not found, validation, FGA denied, rate limited, etc.). The legacy `error` string is populated alongside it for back-compat." } }, "title": "WorkstreamRunOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/workstream.spec.answer/invoke": { "post": { "operationId": "invokeSkill_workstream_spec_answer", "summary": "Answer one open decision on a WorkStream spec. Wraps POST /api/v1/wss/authoring/workstreams/{id}/spec/answer. Answering creates a NEW version rather than mutating one \u2014 the prior version's spec stays unchanged. Read the spec first with workstream_spec.", "tags": [ "authoring" ], "x-skill-name": "workstream.spec.answer", "x-skill-slug": "workstream_spec_answer", "x-skill-category": "authoring", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Answer one open spec decision (wraps POST .../authoring/workstreams/{id}/spec/answer).\n\nAnswering creates a NEW version rather than mutating one \u2014 the store's\nexisting behaviour, so the prior version's spec stays unchanged.", "properties": { "workstream_id": { "description": "Workstream whose spec to answer on \u2014 UUID, slug, or 7-char permakey.", "title": "Workstream Id", "type": "string" }, "decision_id": { "description": "The stable id of the decision to answer.", "maxLength": 200, "minLength": 1, "title": "Decision Id", "type": "string" }, "answer": { "description": "The chosen option value. Agreeing in one word ('yes') records the builder's proposal as the decision, not the affirmative word.", "maxLength": 4000, "minLength": 1, "title": "Answer", "type": "string" }, "provenance": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional source locator or rationale recorded with the answer.", "title": "Provenance" } }, "required": [ "workstream_id", "decision_id", "answer" ], "title": "WorkstreamSpecAnswerInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "workstream_spec_answer" }, "output": { "$defs": { "Error": { "description": "Canonical error envelope set on output models when a skill fails.\n\nUse ``error_envelope`` on any output where the bare ``error: str`` field\nis being phased out. Both fields will be populated during the migration\nwindow so SDK consumers don't break.", "properties": { "code": { "description": "Machine-readable error code in SCREAMING_SNAKE_CASE. Stable across releases \u2014 branch on this, not on `message`.", "examples": [ "WORKSTREAM_NOT_FOUND", "VALIDATION_FAILED", "RATE_LIMITED" ], "maxLength": 120, "title": "Code", "type": "string" }, "message": { "description": "Human-readable single-sentence summary suitable for surfacing to a user.", "maxLength": 500, "title": "Message", "type": "string" }, "details": { "anyOf": [ { "additionalProperties": { "$ref": "#/$defs/JsonValue" }, "type": "object" }, { "type": "null" } ], "default": null, "description": "Optional structured context \u2014 e.g. validation error paths, the offending input value, or upstream provider response codes.", "title": "Details" }, "retryable": { "default": false, "description": "True if the caller should safely retry the same request. When true, callers should pair the retry with the same `idempotency_key` they sent on the original request.", "title": "Retryable", "type": "boolean" } }, "required": [ "code", "message" ], "title": "ProtocolSkills__Error", "type": "object" }, "JsonValue": {} }, "description": "The new version carrying the answered decision.", "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "workstream_id": { "default": "", "description": "Resolved workstream UUID.", "title": "Workstream Id", "type": "string" }, "version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "The NEW version created by the answer (prior version is unchanged).", "title": "Version" }, "spec": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "The updated spec after the answer.", "title": "Spec" }, "spec_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Content address of the new spec.", "title": "Spec Hash" }, "definition_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Content address of the step graph (unchanged by an answer).", "title": "Definition Hash" }, "decision_id": { "default": "", "description": "The decision this call answered.", "title": "Decision Id", "type": "string" }, "frames": { "description": "Cowork artefact frames rendering the answered spec.", "items": { "additionalProperties": true, "type": "object" }, "title": "Frames", "type": "array" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "deprecated": true, "title": "Error" }, "error_envelope": { "anyOf": [ { "$ref": "#/$defs/Error" }, { "type": "null" } ], "default": null, "description": "Canonical structured error. Populated when the answer failed." } }, "title": "WorkstreamSpecAnswerOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/workstream.spec/invoke": { "post": { "operationId": "invokeSkill_workstream_spec", "summary": "Read a stored WorkStream spec \u2014 the decisions the design interview settled, each with its proposal, reason, citation, and status. Wraps GET /api/v1/wss/authoring/workstreams/{id}/spec. Read-only; omit `version` for the latest.", "tags": [ "authoring" ], "x-skill-name": "workstream.spec", "x-skill-slug": "workstream_spec", "x-skill-category": "authoring", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Read a stored WorkStream spec (wraps GET .../authoring/workstreams/{id}/spec).", "properties": { "workstream_id": { "description": "Workstream to read the spec for \u2014 UUID, slug, or 7-char permakey.", "title": "Workstream Id", "type": "string" }, "version": { "anyOf": [ { "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null, "description": "Optional version pin. Omit to read the latest version's spec.", "title": "Version" } }, "required": [ "workstream_id" ], "title": "WorkstreamSpecInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "workstream_spec" }, "output": { "$defs": { "Error": { "description": "Canonical error envelope set on output models when a skill fails.\n\nUse ``error_envelope`` on any output where the bare ``error: str`` field\nis being phased out. Both fields will be populated during the migration\nwindow so SDK consumers don't break.", "properties": { "code": { "description": "Machine-readable error code in SCREAMING_SNAKE_CASE. Stable across releases \u2014 branch on this, not on `message`.", "examples": [ "WORKSTREAM_NOT_FOUND", "VALIDATION_FAILED", "RATE_LIMITED" ], "maxLength": 120, "title": "Code", "type": "string" }, "message": { "description": "Human-readable single-sentence summary suitable for surfacing to a user.", "maxLength": 500, "title": "Message", "type": "string" }, "details": { "anyOf": [ { "additionalProperties": { "$ref": "#/$defs/JsonValue" }, "type": "object" }, { "type": "null" } ], "default": null, "description": "Optional structured context \u2014 e.g. validation error paths, the offending input value, or upstream provider response codes.", "title": "Details" }, "retryable": { "default": false, "description": "True if the caller should safely retry the same request. When true, callers should pair the retry with the same `idempotency_key` they sent on the original request.", "title": "Retryable", "type": "boolean" } }, "required": [ "code", "message" ], "title": "ProtocolSkills__Error", "type": "object" }, "JsonValue": {} }, "description": "The stored spec for one workstream version. Read-only.", "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "workstream_id": { "default": "", "description": "Resolved workstream UUID.", "title": "Workstream Id", "type": "string" }, "version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Version the spec belongs to.", "title": "Version" }, "spec": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "The spec: ordered decisions plus compiled bindings. Null on pre-spec versions.", "title": "Spec" }, "spec_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Content address of the spec.", "title": "Spec Hash" }, "definition_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Content address of the step graph.", "title": "Definition Hash" }, "frames": { "description": "Cowork artefact frames rendering the spec.", "items": { "additionalProperties": true, "type": "object" }, "title": "Frames", "type": "array" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "deprecated": true, "title": "Error" }, "error_envelope": { "anyOf": [ { "$ref": "#/$defs/Error" }, { "type": "null" } ], "default": null, "description": "Canonical structured error. Populated when the read failed." } }, "title": "WorkstreamSpecOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/workstream.status/invoke": { "post": { "operationId": "invokeSkill_workstream_status", "summary": "Get the current status of a workstream run \u2014 overall lifecycle state plus current/next step pointers and progress percentage. For live progress streaming, use the events_url returned by workstream_run instead.", "tags": [ "WorkStreams" ], "x-skill-name": "workstream.status", "x-skill-slug": "workstream_status", "x-skill-category": "workstreams", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Identify the cycle to inspect.\n\nThe canonical field is ``cycle_id``; ``run_id`` is accepted as a\ndeprecated alias for backwards compat with existing SDK callers.\n\n``cycle_id`` accepts either a UUID or a 7-char permakey. When the\nmodel @-mentions a run in a topic, prompt stage 4.8 (PR #10470)\ninstructs it to call ``workstream_status`` with the run's permakey\nfrom the ``run_mentions`` payload. The handler resolves the permakey\nto the cycle UUID (workspace-scoped) before querying real state.", "properties": { "cycle_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "string" } ], "description": "The cycle id returned by workstream_run, or the 7-char permakey from a run_mentions payload.", "title": "Cycle Id" } }, "required": [ "cycle_id" ], "title": "WorkstreamStatusInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "workstream_status" }, "output": { "$defs": { "Error": { "description": "Canonical error envelope set on output models when a skill fails.\n\nUse ``error_envelope`` on any output where the bare ``error: str`` field\nis being phased out. Both fields will be populated during the migration\nwindow so SDK consumers don't break.", "properties": { "code": { "description": "Machine-readable error code in SCREAMING_SNAKE_CASE. Stable across releases \u2014 branch on this, not on `message`.", "examples": [ "WORKSTREAM_NOT_FOUND", "VALIDATION_FAILED", "RATE_LIMITED" ], "maxLength": 120, "title": "Code", "type": "string" }, "message": { "description": "Human-readable single-sentence summary suitable for surfacing to a user.", "maxLength": 500, "title": "Message", "type": "string" }, "details": { "anyOf": [ { "additionalProperties": { "$ref": "#/$defs/JsonValue" }, "type": "object" }, { "type": "null" } ], "default": null, "description": "Optional structured context \u2014 e.g. validation error paths, the offending input value, or upstream provider response codes.", "title": "Details" }, "retryable": { "default": false, "description": "True if the caller should safely retry the same request. When true, callers should pair the retry with the same `idempotency_key` they sent on the original request.", "title": "Retryable", "type": "boolean" } }, "required": [ "code", "message" ], "title": "ProtocolSkills__Error", "type": "object" }, "JsonValue": {} }, "description": "Current cycle state \u2014 overall + per-step.\n\nEmits both ``cycle_id`` (canonical) and ``run_id`` (deprecated alias,\npopulated alongside ``cycle_id``) for backwards compat.", "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "cycle_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "The cycle being inspected.", "title": "Cycle Id" }, "run_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "deprecated": true, "title": "Run Id" }, "status": { "default": "pending", "description": "Lifecycle state of the cycle.", "enum": [ "pending", "running", "paused", "awaiting_approval", "completed", "cancelled", "failed" ], "title": "Status", "type": "string" }, "current_step": { "default": "", "description": "Slug of the currently-executing step (empty if not yet started).", "title": "Current Step", "type": "string" }, "next_step": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Slug of the next step the runtime will dispatch (None on terminal states).", "title": "Next Step" }, "progress_pct": { "default": 0.0, "description": "Approximate completion percentage (0..100).", "maximum": 100.0, "minimum": 0.0, "title": "Progress Pct", "type": "number" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "deprecated": true, "title": "Error" }, "error_envelope": { "anyOf": [ { "$ref": "#/$defs/Error" }, { "type": "null" } ], "default": null, "description": "Canonical structured error. Populated when `status == 'failed'`." } }, "title": "WorkstreamStatusOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/skills/workstream.update/invoke": { "post": { "operationId": "invokeSkill_workstream_update", "summary": "Update a workstream's metadata \u2014 rename (name) or change its description. Only provided fields change. Operates on the workstream definition; in-flight cycles run off a snapshot and are not affected.", "tags": [ "WorkStreams" ], "x-skill-name": "workstream.update", "x-skill-slug": "workstream_update", "x-skill-category": "workstreams", "x-skill-cluster": "", "x-skill-streaming": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "workstream_id": { "description": "Workstream UUID, slug, or 7-char permakey", "title": "Workstream Id", "type": "string" }, "name": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "New name (rename / retitle)", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "New description", "title": "Description" }, "steps": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Updated step definitions (id, name, type, depends_on, expected_outputs, requires_approval, etc.)", "title": "Steps" }, "input_schema": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Updated input schema declarations (array of InputDef: name, type, required, description).", "title": "Input Schema" }, "output_schema": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Declared outputs", "title": "Output Schema" } }, "required": [ "workstream_id" ], "title": "WorkstreamUpdateInput", "type": "object" } } } }, "responses": { "200": { "description": "Skill executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "skill", "output", "correlation_id" ], "properties": { "skill": { "type": "string", "example": "workstream_update" }, "output": { "properties": { "stub_fields": { "items": { "type": "string" }, "title": "Stub Fields", "type": "array" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" }, "workstream_id": { "default": "", "description": "The workstream's permakey (the public id).", "title": "Workstream Id", "type": "string" }, "permakey": { "default": "", "description": "7-char public workstream id.", "title": "Permakey", "type": "string" }, "name": { "default": "", "title": "Name", "type": "string" }, "status": { "default": "", "title": "Status", "type": "string" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "missing_workspace | not_found on failure, else null", "title": "Error" } }, "title": "WorkstreamUpdateOutput", "type": "object" }, "correlation_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/studio/capabilities": { "get": { "tags": [ "WorkStreams Studio" ], "summary": "Get Studio capabilities for current user", "description": "Returns the capability map and role list for the current user within\n WorkStream Studio for the active workspace.\n\n Roles are resolved via WorkOS FGA (`workstream_studio:*` relations) when\n available, falling back to workspace-admin heuristics while FGA is being\n wired up.\n\n **Authentication Required:** JWT Bearer token", "operationId": "get_studio_capabilities_api_v1_studio_capabilities_get", "responses": { "200": { "description": "Capabilities resolved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudioCapabilities" } } } }, "401": { "description": "Unauthorized" } } } }, "/api/v1/workstream-drafts": { "post": { "tags": [ "WorkStreams Drafts" ], "summary": "Create Draft", "description": "Start a new conversational workstream draft anchored to a Topic.\n\nMessage-only creation is retired; use WSS or ``workstream_draft`` so the\ncanonical document-aware authoring contract is applied.", "operationId": "create_draft_api_v1_workstream_drafts_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkstreamDraftCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkstreamDraftResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "WorkStreams Drafts" ], "summary": "List Drafts", "description": "List drafts visible to the caller's workspace.", "operationId": "list_drafts_api_v1_workstream_drafts_get", "parameters": [ { "name": "topic_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by Topic \u2014 permakey (preferred) or UUID", "title": "Topic Id" }, "description": "Filter by Topic \u2014 permakey (preferred) or UUID" }, { "name": "author_user_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by author", "title": "Author User Id" }, "description": "Filter by author" }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "drafting (default) | committed | abandoned | for all", "default": "drafting", "title": "Status" }, "description": "drafting (default) | committed | abandoned | for all" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkstreamDraftListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstream-drafts/{draft_id}": { "get": { "tags": [ "WorkStreams Drafts" ], "summary": "Get Draft", "description": "Get a single draft by ID.", "operationId": "get_draft_api_v1_workstream_drafts__draft_id__get", "parameters": [ { "name": "draft_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Draft Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkstreamDraftResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "WorkStreams Drafts" ], "summary": "Update Draft", "description": "Iterate on a workstream draft.\n\nExplicit ``draft_definition`` updates remain supported. Message-only\nregeneration is retired in favour of the canonical WSS/Cowork authoring\nservice.", "operationId": "update_draft_api_v1_workstream_drafts__draft_id__patch", "parameters": [ { "name": "draft_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Draft Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkstreamDraftUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkstreamDraftResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "WorkStreams Drafts" ], "summary": "Abandon Draft", "description": "Abandon a draft (idempotent for already-terminal drafts).", "operationId": "abandon_draft_api_v1_workstream_drafts__draft_id__delete", "parameters": [ { "name": "draft_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Draft Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstream-drafts/{draft_id}/commit": { "post": { "tags": [ "WorkStreams Drafts" ], "summary": "Commit Draft", "description": "Commit a workstream draft into an active Workstream.\n\nReturns ``{draft: {...}, workstream: {...}}``.", "operationId": "commit_draft_api_v1_workstream_drafts__draft_id__commit_post", "parameters": [ { "name": "draft_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Draft Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkstreamDraftCommit" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Commit Draft Api V1 Workstream Drafts Draft Id Commit Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/blueprints": { "get": { "tags": [ "WorkStreams" ], "summary": "List blueprints (deprecated)", "description": "Deprecated alias for the matching `/workplans` operation.\n\n**Deprecated:** renamed to the `/api/v1/workstreams/workplans/...` surface. This `/blueprints/...` path still works but will be removed in a future release. Update integrations to use `workplans`.", "operationId": "list_blueprints_api_v1_workstreams_blueprints_get", "deprecated": true, "parameters": [ { "name": "template_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Filter by template/workstream", "title": "Template Id" }, "description": "Filter by template/workstream" }, { "name": "client_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Filter by client", "title": "Client Id" }, "description": "Filter by client" }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/WorkstreamStatus", "description": "Filter by status", "default": "active" }, "description": "Filter by status" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Results per page", "default": 20, "title": "Limit" }, "description": "Results per page" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Pagination offset", "default": 0, "title": "Offset" }, "description": "Pagination offset" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkplanListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "WorkStreams" ], "summary": "Create blueprint (deprecated \u2014 use POST /workplans)", "description": "Deprecated alias for **POST /workplans**. Removed in a future release. Use POST /workstreams/jobs to create a WorkPlan (job_definition).", "operationId": "create_workplan_api_v1_workstreams_blueprints_post", "deprecated": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkplanCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobDefinitionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/blueprints/{blueprint_id}": { "get": { "tags": [ "WorkStreams" ], "summary": "Get blueprint by ID (deprecated)", "description": "Deprecated alias for the matching `/workplans` operation.\n\n**Deprecated:** renamed to the `/api/v1/workstreams/workplans/...` surface. This `/blueprints/...` path still works but will be removed in a future release. Update integrations to use `workplans`.", "operationId": "get_blueprint_api_v1_workstreams_blueprints__blueprint_id__get", "deprecated": true, "parameters": [ { "name": "blueprint_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Blueprint Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workplan" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "WorkStreams" ], "summary": "Update blueprint (deprecated)", "description": "Deprecated alias for the matching `/workplans` operation.\n\n**Deprecated:** renamed to the `/api/v1/workstreams/workplans/...` surface. This `/blueprints/...` path still works but will be removed in a future release. Update integrations to use `workplans`.", "operationId": "update_blueprint_api_v1_workstreams_blueprints__blueprint_id__put", "deprecated": true, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "blueprint_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Blueprint Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkplanUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workplan" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "WorkStreams" ], "summary": "Archive blueprint (deprecated)", "description": "Deprecated alias for the matching `/workplans` operation.\n\n**Deprecated:** renamed to the `/api/v1/workstreams/workplans/...` surface. This `/blueprints/...` path still works but will be removed in a future release. Update integrations to use `workplans`.", "operationId": "delete_blueprint_api_v1_workstreams_blueprints__blueprint_id__delete", "deprecated": true, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "blueprint_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Blueprint Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/blueprints/{blueprint_id}/disable-writes": { "post": { "tags": [ "WorkStreams" ], "summary": "Disable write operations (deprecated)", "description": "Deprecated alias for the matching `/workplans` operation.\n\n**Deprecated:** renamed to the `/api/v1/workstreams/workplans/...` surface. This `/blueprints/...` path still works but will be removed in a future release. Update integrations to use `workplans`.", "operationId": "disable_writes_api_v1_workstreams_blueprints__blueprint_id__disable_writes_post", "deprecated": true, "parameters": [ { "name": "blueprint_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Blueprint Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DisableWritesRequest" }, { "type": "null" } ], "title": "Request Body" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WriteModeTransitionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/blueprints/{blueprint_id}/enable-writes": { "post": { "tags": [ "WorkStreams" ], "summary": "Enable write operations (deprecated)", "description": "Deprecated alias for the matching `/workplans` operation.\n\n**Deprecated:** renamed to the `/api/v1/workstreams/workplans/...` surface. This `/blueprints/...` path still works but will be removed in a future release. Update integrations to use `workplans`.", "operationId": "enable_writes_api_v1_workstreams_blueprints__blueprint_id__enable_writes_post", "deprecated": true, "parameters": [ { "name": "blueprint_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Blueprint Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnableWritesRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WriteModeTransitionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/blueprints/{blueprint_id}/triggers": { "get": { "tags": [ "WorkStreams" ], "summary": "List triggers for blueprint (deprecated)", "description": "Deprecated alias for `GET /workplans/{blueprint_id}/triggers`.\n\n**Deprecated:** renamed to `/api/v1/workstreams/workplans/{blueprint_id}/triggers`. This `/blueprints/...` path still works but will be removed in a future release. Update integrations to use `workplans`.", "operationId": "list_triggers_api_v1_workstreams_blueprints__blueprint_id__triggers_get", "deprecated": true, "parameters": [ { "name": "blueprint_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Blueprint Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "WorkStreams" ], "summary": "Create trigger for blueprint (deprecated)", "description": "Deprecated alias for `POST /workplans/{blueprint_id}/triggers`.\n\n**Deprecated:** renamed to `/api/v1/workstreams/workplans/{blueprint_id}/triggers`. This `/blueprints/...` path still works but will be removed in a future release. Update integrations to use `workplans`.", "operationId": "create_trigger_api_v1_workstreams_blueprints__blueprint_id__triggers_post", "deprecated": true, "parameters": [ { "name": "blueprint_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Blueprint Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/blueprints/{blueprint_id}/write-status": { "get": { "tags": [ "WorkStreams" ], "summary": "Get write mode status (deprecated)", "description": "Deprecated alias for the matching `/workplans` operation.\n\n**Deprecated:** renamed to the `/api/v1/workstreams/workplans/...` surface. This `/blueprints/...` path still works but will be removed in a future release. Update integrations to use `workplans`.", "operationId": "get_write_status_api_v1_workstreams_blueprints__blueprint_id__write_status_get", "deprecated": true, "parameters": [ { "name": "blueprint_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Blueprint Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WriteStatusResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycle-launches/{launch_permakey}": { "get": { "tags": [ "WorkStreams" ], "summary": "Get a cycle launch (the product's Cycle) by its permakey", "description": "Card \"A launch creates one cycle record with its own permakey\": one launch\n of a plan (or a run with no plan) mints exactly one record with a fresh\n permakey of its own. This fetches that record by its permakey, returning\n its launch facts (plan when there is one, period, client count,\n started/completed) and its instances, with status derived from the\n instances' tallies (never stored ahead of them).\n\n Three things are optional on a cycle, independently: the plan\n (`job_definition_id`), the client (`client_id`), and the period. A\n WorkStream run by itself is one instance with none of the three, identified\n by its `label`.\n\n **Authentication Required:** JWT Bearer token", "operationId": "get_cycle_launch_api_v1_workstreams_cycle_launches__launch_permakey__get", "parameters": [ { "name": "launch_permakey", "in": "path", "required": true, "schema": { "type": "string", "title": "Launch Permakey" } } ], "responses": { "200": { "description": "Cycle launch retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CycleLaunchResponse" } } } }, "404": { "description": "Cycle launch not found in this workspace" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycle-slot/{identifier}": { "get": { "tags": [ "WorkStreams" ], "summary": "Resolve an id in the cycle slot to its canonical address", "description": "Card \"Cycle URLs open cycles, WorkPlan URLs open WorkPlans\": the cycle slot\n ``/workstreams/{ws}/cycles/{id}`` used to be served by TWO backend entities\n (probe job, on 404 probe cycle, ~14s retry for orphans). This is the single\n resolver that decides which entity an id canonically IS and where it lands,\n so the rendering nested cycle route resolves against ``cycle_launch`` alone\n and legacy ids REDIRECT to their canonical home.\n\n Returns ``{kind, canonical_url}``:\n - ``cycle_launch`` -> the nested cycle URL (render the launch there)\n - ``plan`` -> the workplan URL (a plan permakey arrived in the\n cycle slot under the retired scheme #173)\n - ``instance`` -> the instance URL under its backfilled cycle_launch\n - ``unknown`` -> no canonical_url; the route shows a designed not-found\n\n The frontend flat cycle route calls this and ``Navigate replace``-s (the\n SPA permanent-redirect equivalent of a 308). Workspace-scoped: a foreign id\n resolves as ``unknown`` (never a cross-tenant redirect leak).\n\n **Authentication Required:** JWT Bearer token", "operationId": "resolve_cycle_slot_endpoint_api_v1_workstreams_cycle_slot__identifier__get", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string", "title": "Identifier" } } ], "responses": { "200": { "description": "Cycle-slot resolution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CycleSlotResolutionResponse" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles": { "get": { "tags": [ "WorkStreams" ], "summary": "List cycles (fleet view)", "description": "List execution cycles with filtering options.\n\n Provides a fleet view of all workflow executions across blueprints.\n\n **Query Parameters:**\n - `workstream_id`: Filter by parent workstream (matches both the\n denormalised `cycle.workstream_id` column and, for legacy\n containerized cycles where it may be null, the workstream id\n reachable via the blueprint join)\n - `blueprint_id`: Filter by blueprint\n - `client_id`: Filter by client\n - `status`: Filter by status\n - `limit`: Results per page (1-100, default: 20)\n - `offset`: Pagination offset (default: 0)\n\n **Authentication Required:** JWT Bearer token", "operationId": "list_cycles_api_v1_workstreams_cycles_get", "parameters": [ { "name": "workstream_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Filter by parent workstream", "title": "Workstream Id" }, "description": "Filter by parent workstream" }, { "name": "blueprint_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Filter by blueprint", "title": "Blueprint Id" }, "description": "Filter by blueprint" }, { "name": "client_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Filter by client", "title": "Client Id" }, "description": "Filter by client" }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/CycleStatus" }, { "type": "null" } ], "description": "Filter by status", "title": "Status" }, "description": "Filter by status" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Results per page", "default": 20, "title": "Limit" }, "description": "Results per page" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Pagination offset", "default": 0, "title": "Offset" }, "description": "Pagination offset" } ], "responses": { "200": { "description": "Cycles retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CycleListResponse" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "WorkStreams" ], "summary": "Start new cycle", "description": "Manually start a new execution cycle for a blueprint.\n\n Creates a new cycle and queues it for execution.\n\n **Authentication Required:** JWT Bearer token", "operationId": "create_cycle_api_v1_workstreams_cycles_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CycleCreate" } } } }, "responses": { "201": { "description": "Cycle started successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CycleResponse" } } } }, "400": { "description": "Invalid request or blueprint not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles/agent": { "post": { "tags": [ "WorkStreams" ], "summary": "Start agentic cycle", "description": "Start a new agentic workstream cycle. Instead of a rigid step-based WDL,\n the agent receives a goal, tools, and context, then works autonomously\n toward producing the required deliverables.\n\n **Authentication Required:** JWT Bearer token", "operationId": "create_agent_cycle_api_v1_workstreams_cycles_agent_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCycleCreate" } } }, "required": true }, "responses": { "201": { "description": "Agentic cycle started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCycleResponse" } } } }, "401": { "description": "Unauthorized" }, "504": { "description": "Temporal timeout" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles/approve-bulk": { "post": { "tags": [ "WorkStreams" ], "summary": "Approve or reject N awaiting-approval task instances at once", "description": "Resolve a wave of approval gates in one call \u2014 the 'approve all N' triage\n button. Each (cycle, task) pair is a cycle paused at an approval gate; the\n same `decision` is fanned to every pair. Fail-soft: a bad or already-resolved\n pair returns an `error` result without failing the batch. Each successful pair\n completes a task-scoped Workflow Update that records evidence before resume.\n\n **Authentication Required:** JWT Bearer token", "operationId": "approve_bulk_api_v1_workstreams_cycles_approve_bulk_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveBulkRequestModel" } } }, "required": true }, "responses": { "200": { "description": "Per-pair results + roll-up counts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveBulkResponseModel" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles/{cycle_id}": { "get": { "tags": [ "WorkStreams" ], "summary": "Get cycle with tasks", "description": "Retrieve a cycle with all its tasks.\n\n **Run-view canon (payload-by-reference, card #505):** step rows are served\n LIGHT \u2014 each carries a one-line ``summary``, ``duration_ms``, ``tool`` and\n a ``payload_ref`` content_uri the UI lazy-fetches via\n ``GET /cycles/{cycle_id}/steps/{step_id}/payload`` \u2014 and ``output_data``\n is empty by default. Pass ``?include=payloads`` (debug only) to restore\n inline raw outputs; refused with **409** when the inlined total would\n exceed 5 MB.\n\n **Authentication Required:** JWT Bearer token", "operationId": "get_cycle_api_v1_workstreams_cycles__cycle_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cycle Id" } }, { "name": "include", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opt-in extras, comma-separated. `payloads` restores the legacy inline `output_data` per step (debug only; never the default). Refused with 409 when the inlined total would exceed 5 MB \u2014 lazy-fetch GET /cycles/{cycle_id}/steps/{step_id}/payload instead.", "title": "Include" }, "description": "Opt-in extras, comma-separated. `payloads` restores the legacy inline `output_data` per step (debug only; never the default). Refused with 409 when the inlined total would exceed 5 MB \u2014 lazy-fetch GET /cycles/{cycle_id}/steps/{step_id}/payload instead." } ], "responses": { "200": { "description": "Cycle retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CycleWithTasksResponse" } } } }, "404": { "description": "Cycle not found" }, "409": { "description": "?include=payloads refused: total payload > 5 MB (lazy-fetch instead)" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "WorkStreams" ], "summary": "Delete cycle", "description": "Delete a cycle and all associated tasks and impact ledger entries (cascade).\n\n **Authentication Required:** JWT Bearer token", "operationId": "delete_cycle_api_v1_workstreams_cycles__cycle_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cycle Id" } } ], "responses": { "204": { "description": "Cycle deleted successfully" }, "404": { "description": "Cycle not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles/{cycle_id}/abandon": { "post": { "tags": [ "WorkStreams Cycles" ], "summary": "Abandon a paused cycle", "description": "Transition a paused cycle to the terminal ``abandoned`` state. The\n cycle must currently be in ``paused`` state.\n\n Distinct from ``cancel``: cancel can be called on a running or\n paused cycle and signals the workflow to terminate. Abandon is a\n state-only transition for cycles that are no longer interesting.\n\n **Authentication Required:** JWT Bearer token", "operationId": "abandon_cycle_api_v1_workstreams_cycles__cycle_id__abandon_post", "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cycle Id" } } ], "responses": { "204": { "description": "Cycle abandoned" }, "400": { "description": "Cycle not in paused state" }, "404": { "description": "Cycle not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles/{cycle_id}/activity": { "get": { "tags": [ "WorkStreams" ], "summary": "Recent activity-feed events for a cycle", "description": "The run-detail right-sidebar activity feed (\"Archie finished step 8 \u00b7 2min\n ago\"). Returns the cycle's run/step LIFECYCLE events from\n ``workstreams.cycle_event``, newest first, as a paginated JSON list.\n High-volume telemetry rows (``thinking_step``, ``run.totals_updated``) are\n excluded so the feed stays readable.\n\n Distinct from ``GET /cycles/{cycle_id}/events`` (an SSE telemetry-span\n *stream* for the live deep-trace view) and from the deep reasoning trace at\n ``GET /api/v1/thinking-steps?query_id=ws-{cycle_id}``.\n\n **Authentication Required:** JWT Bearer token", "operationId": "list_cycle_events_api_v1_workstreams_cycles__cycle_id__activity_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cycle Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Max events (newest first)", "default": 30, "title": "Limit" }, "description": "Max events (newest first)" } ], "responses": { "200": { "description": "Events retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CycleEventListResponse" } } } }, "404": { "description": "Cycle not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles/{cycle_id}/artifacts": { "get": { "tags": [ "WorkStreams" ], "summary": "List cycle artifacts", "description": "List all artifacts produced during a cycle execution (Chain of Evidence).\n\n **Authentication Required:** JWT Bearer token", "operationId": "list_cycle_artifacts_api_v1_workstreams_cycles__cycle_id__artifacts_get", "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Cycle Id" } }, { "name": "type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" } }, { "name": "step_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Step Id" } }, { "name": "source", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source" } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "default": "created_at", "title": "Sort By" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Artifacts listed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CycleArtifactListResponse" } } } }, "404": { "description": "Cycle not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles/{cycle_id}/artifacts/{artifact_id}": { "get": { "tags": [ "WorkStreams" ], "summary": "Get artifact metadata", "description": "Get metadata for a single cycle artifact.\n\n **Authentication Required:** JWT Bearer token", "operationId": "get_cycle_artifact_api_v1_workstreams_cycles__cycle_id__artifacts__artifact_id__get", "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Cycle Id" } }, { "name": "artifact_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Artifact Id" } } ], "responses": { "200": { "description": "Artifact metadata retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CycleArtifactResponse" } } } }, "404": { "description": "Artifact not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles/{cycle_id}/artifacts/{artifact_id}/download": { "get": { "tags": [ "WorkStreams" ], "summary": "Download artifact content", "description": "Stream artifact content from blob storage.\n\n **Authentication Required:** JWT Bearer token", "operationId": "download_cycle_artifact_api_v1_workstreams_cycles__cycle_id__artifacts__artifact_id__download_get", "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Cycle Id" } }, { "name": "artifact_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Artifact Id" } } ], "responses": { "200": { "description": "Artifact content streamed", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Artifact not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles/{cycle_id}/cancel": { "post": { "tags": [ "WorkStreams" ], "summary": "Cancel cycle (emergency stop)", "description": "Cancel a running or paused cycle.\n\n This is an emergency stop operation.\n\n **Authentication Required:** JWT Bearer token", "operationId": "cancel_cycle_api_v1_workstreams_cycles__cycle_id__cancel_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cycle Id" } } ], "responses": { "200": { "description": "Cycle cancelled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CycleResponse" } } } }, "400": { "description": "Cycle cannot be cancelled" }, "404": { "description": "Cycle not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles/{cycle_id}/evidence": { "get": { "tags": [ "WorkStreams" ], "summary": "The cycle's tie register (References v1 evidence slice)", "description": "Aggregates every task's ``outputs.diagnostics.tie_register`` into the run's\n evidence register \u2014 the store the Evidence tab, the Excel sidebar, cite\n chips and PDF stamps all project. Rows are returned verbatim as the engine\n emitted them (marks are derived server-side from relations and never\n recomputed by a surface), each annotated with the emitting ``step_id``.\n ``counts`` totals the slice; ``hash_by_step`` carries the sealable\n per-step register content hashes.\n\n **Authentication Required:** JWT Bearer token", "operationId": "get_cycle_evidence_api_v1_workstreams_cycles__cycle_id__evidence_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cycle Id" } } ], "responses": { "200": { "description": "Evidence register retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CycleEvidenceResponse" } } } }, "404": { "description": "Cycle not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles/{cycle_id}/evidence/decisions": { "post": { "tags": [ "WorkStreams" ], "summary": "Record a gate decision on a tie-register reference", "description": "The review gate's write path (References v1, invariant 6): a person\n decides a \u2691 query or model-proposed reference. The decision is APPENDED\n to the cycle's decision log \u2014 the engine's register rows are never\n rewritten; ``GET /evidence`` annotates the decided reference with the\n latest decision and returns the full trail. Re-deciding appends again\n (newest wins at read time; the older rows remain on file for audit).\n\n **Authentication Required:** JWT Bearer token", "operationId": "record_evidence_decision_api_v1_workstreams_cycles__cycle_id__evidence_decisions_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cycle Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceDecisionRequest" } } } }, "responses": { "201": { "description": "Decision appended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceDecisionResponse" } } } }, "404": { "description": "Cycle or reference not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles/{cycle_id}/evidence/sign": { "post": { "tags": [ "WorkStreams" ], "summary": "Sign-and-seal the cycle's evidence register", "description": "The gate's terminal act (References v1): an identity-backed seal over the\n register. REFUSED (409, code ``open_queries``) while any \u2691 query lacks a\n gate decision \u2014 nothing is ticked without a trace. On success: appends\n the seal (signer, register content hash over the slice INCLUDING the\n decision trail, note), writes the sign-off block into a NEW copy of the\n cycle's final workbook artifact (the original is never mutated), and\n enables sheet protection on every register-marked sheet. Re-signing\n appends a new seal; older seals remain on file.\n\n Note: v1 gates on ``cycle:edit`` \u2014 a partner-specific role permission is\n an open follow-up from the gate-decisions PR.\n\n **Authentication Required:** JWT Bearer token", "operationId": "sign_cycle_evidence_api_v1_workstreams_cycles__cycle_id__evidence_sign_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cycle Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceSignRequest" } } } }, "responses": { "201": { "description": "Register sealed; signed workbook artifact created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceSignoffResponse" } } } }, "409": { "description": "Open queries without decisions, or no signable artifact" }, "404": { "description": "Cycle not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles/{cycle_id}/execute-reversal": { "post": { "tags": [ "WorkStreams" ], "summary": "Execute reversal (Phase 3)", "description": "Execute a reversal plan to undo cycle actions.\n\n **Note:** This is a Phase 3 feature. Currently returns a placeholder response.\n\n **Authentication Required:** JWT Bearer token", "operationId": "execute_reversal_api_v1_workstreams_cycles__cycle_id__execute_reversal_post", "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Cycle Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReversalExecutionRequest" } } } }, "responses": { "200": { "description": "Reversal execution started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReversalExecutionResponse" } } } }, "404": { "description": "Cycle not found" }, "400": { "description": "Invalid reversal plan" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles/{cycle_id}/fork": { "post": { "tags": [ "WorkStreams" ], "summary": "Fork a terminal inline cycle, seeding unchanged step outputs", "description": "Fork a terminal (completed/failed/cancelled) INLINE cycle into a NEW\n cycle on the same blueprint, seeding every step whose outputs are still\n valid so they don't re-pay the LLM cost (the iteration-cost killer).\n\n A donor step's outputs are seedable only if its **content key matches** \u2014\n the hash of (rendered instruction in the new cycle's snapshot) x (the file\n ids + upstream step ids it consumes). A step whose instruction or inputs\n changed is *dirty* and re-runs; dirtiness propagates transitively to every\n step that consumes a dirty step (via ``depends_on`` or ``{{ outputs.X }}``\n refs). Side-effect steps (notify/webhook/email/form/approval) are never\n seedable.\n\n The donor's ``input_data`` is preserved unless ``input_data`` overrides it.\n The new cycle records ``parent_cycle_id`` lineage and the response carries\n ``seeded_steps`` / ``dirty_steps`` so callers can see the economics.\n\n Inline cycles only; the donor must be terminal.\n\n **Authentication Required:** JWT Bearer token", "operationId": "fork_cycle_api_v1_workstreams_cycles__cycle_id__fork_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cycle Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ForkCycleRequest" }, { "type": "null" } ], "title": "Request Body" } } } }, "responses": { "200": { "description": "Cycle forked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForkCycleResponse" } } } }, "400": { "description": "Donor not forkable (running / containerized / no steps)" }, "404": { "description": "Donor cycle not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles/{cycle_id}/impact-ledger": { "get": { "tags": [ "WorkStreams" ], "summary": "Get impact ledger for cycle", "description": "Retrieve the impact ledger (audit trail) for a cycle.\n\n The impact ledger records all actions performed during cycle execution,\n enabling reversibility.\n\n **Authentication Required:** JWT Bearer token", "operationId": "get_impact_ledger_api_v1_workstreams_cycles__cycle_id__impact_ledger_get", "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Cycle Id" } }, { "name": "type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by action type", "title": "Type" }, "description": "Filter by action type" }, { "name": "source", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by target system", "title": "Source" }, "description": "Filter by target system" }, { "name": "step", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Filter by task UUID", "title": "Step" }, "description": "Filter by task UUID" }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "description": "Sort order", "default": "created_at_desc", "title": "Sort By" }, "description": "Sort order" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Max entries to return", "default": 50, "title": "Limit" }, "description": "Max entries to return" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Pagination offset", "default": 0, "title": "Offset" }, "description": "Pagination offset" } ], "responses": { "200": { "description": "Impact ledger retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImpactLedgerResponse" } } } }, "404": { "description": "Cycle not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles/{cycle_id}/pause": { "post": { "operationId": "pauseCycle", "summary": "Pause a cycle", "tags": [ "WorkStreams" ], "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cycle" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Cycle is not in a pausable state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/workstreams/cycles/{cycle_id}/resolve-payee-flag": { "post": { "tags": [ "WorkStreams" ], "summary": "Resolve a payee review flag into durable routing precedent", "description": "Resolve a bank-analysis ``uncategorised_leg`` review flag by routing a payee\n to a category. Persists the decision as durable (workspace, client)-scoped\n precedent in ``workstreams.learned_payee_precedent`` so every subsequent\n cycle auto-applies it and the engine routes the leg instead of re-flagging it.\n\n The client scope is taken from the cycle (NULL \u21d2 a workspace-wide default).\n Re-resolving the same payee updates the rule in place (upsert).", "operationId": "resolve_payee_flag_api_v1_workstreams_cycles__cycle_id__resolve_payee_flag_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cycle Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolvePayeeFlagRequest" } } } }, "responses": { "200": { "description": "Precedent persisted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolvePayeeFlagResponse" } } } }, "404": { "description": "Cycle not found" }, "422": { "description": "Unknown category or invalid direction" } } } }, "/api/v1/workstreams/cycles/{cycle_id}/restart-workflow": { "post": { "tags": [ "WorkStreams" ], "summary": "Restart workflow for cycle", "description": "Run an inactive containerized WorkPlan again as a fresh child Cycle.\n\n Use this to:\n - Retry a workflow that failed to start\n - Re-run a completed/failed/cancelled containerized Cycle\n\n The donor Cycle and its tasks remain immutable. A new Cycle, Ledger scope,\n task population and deterministic Temporal workflow identity are created.\n\n **Authentication Required:** JWT Bearer token", "operationId": "restart_cycle_workflow_api_v1_workstreams_cycles__cycle_id__restart_workflow_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cycle Id" } } ], "responses": { "200": { "description": "Workflow restarted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CycleResponse" } } } }, "400": { "description": "Cannot restart workflow for this cycle" }, "404": { "description": "Cycle not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles/{cycle_id}/resume": { "post": { "operationId": "resumeCycle", "summary": "Resume a paused cycle", "tags": [ "WorkStreams" ], "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cycle" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Cycle is not paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/workstreams/cycles/{cycle_id}/resume-from-checkpoint": { "post": { "tags": [ "WorkStreams" ], "summary": "Resume failed inline cycle from checkpoint", "description": "Resume a failed/cancelled INLINE cycle from its last good step.\n\n Completed steps' banked outputs (``workstreams.task.outputs``) are\n seeded into a fresh child Cycle and those steps are skipped \u2014 only\n unfinished steps re-execute, so the LLM cost of completed steps is\n never paid twice. The terminal donor remains immutable; new task rows\n carry the resumed execution (contrast ``restart-workflow`` on the retained\n containerized compatibility path).\n\n Distinct from ``POST /cycles/{cycle_id}/resume``, which resumes a\n PAUSED cycle's in-flight workflow via signal; this endpoint starts a\n fresh workflow for a DEAD (failed/cancelled) cycle.\n\n Inline cycles only; containerized cycles use ``restart-workflow``.\n\n **Authentication Required:** JWT Bearer token", "operationId": "resume_cycle_from_checkpoint_api_v1_workstreams_cycles__cycle_id__resume_from_checkpoint_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cycle Id" } } ], "responses": { "200": { "description": "Cycle resumed from checkpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CycleResponse" } } } }, "400": { "description": "Cycle is not resumable (wrong status/engine)" }, "404": { "description": "Cycle not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles/{cycle_id}/reversal-plan": { "post": { "tags": [ "WorkStreams" ], "summary": "Generate reversal plan (Phase 3)", "description": "Generate a reversal plan for a completed cycle.\n\n **Note:** This is a Phase 3 feature. Currently returns a placeholder response.\n\n **Authentication Required:** JWT Bearer token", "operationId": "generate_reversal_plan_api_v1_workstreams_cycles__cycle_id__reversal_plan_post", "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Cycle Id" } } ], "responses": { "200": { "description": "Reversal plan generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReversalPlanResponse" } } } }, "404": { "description": "Cycle not found" }, "400": { "description": "Cycle cannot be reversed" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles/{cycle_id}/steps/{step_id}/payload": { "get": { "tags": [ "WorkStreams" ], "summary": "Lazy-fetch a single step's raw payload", "description": "Run-view canon (card #505): raw step payloads are served by reference, not\n by value \u2014 ``GET /cycles/{cycle_id}`` ships a light step row with a\n ``payload_ref``; this endpoint dereferences it when the UI's Show-payload\n disclosure opens.\n\n Resolves the step WITHIN the caller's cycle (workspace membership already\n gated on the cycle), accepting either the task UUID or its permakey.\n Returns ``{step_id, cycle_id, size_bytes, content_uri, inline_content?,\n kind}`` \u2014 ``inline_content`` only for payloads \u2264 8 KB (the wss-bridge\n inline cap); larger payloads return an external ``content_uri``. Honest\n 404 when the step has no payload. Internal compute figures are stripped\n before serialization (same projection as the cycle fetch).\n\n **Authentication Required:** JWT Bearer token", "operationId": "get_step_payload_api_v1_workstreams_cycles__cycle_id__steps__step_id__payload_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cycle Id" } }, { "name": "step_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Step Id" } } ], "responses": { "200": { "description": "Step payload retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StepPayloadResponse" } } } }, "404": { "description": "Step / cycle not found, or step has no payload" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles/{cycle_id}/tasks": { "get": { "tags": [ "WorkStreams" ], "summary": "List tasks for cycle", "description": "List all tasks for a specific cycle.\n\n **Run-view canon (payload-by-reference, legacy card ARC-505):** task rows are served\n LIGHT. ``output_data`` is projected down to the honesty/gate flags and each\n row carries a ``payload_ref`` the UI lazy-fetches via\n ``GET /cycles/{cycle_id}/tasks/{task_id}/payload``. The sibling cycle fetch\n has served rows this way since that card; this list did not, and shipped every\n task's full payload on every poll \u2014 measured 2026-08-30 on a PAUSED cycle:\n 22 tasks, 6.57 MB, 99.95% of it ``output_data``, re-fetched every ~6s.\n\n Pass ``?include=payloads`` (debug only) to restore inline raw outputs;\n refused with **409** when the inlined total would exceed 5 MB.\n\n **Authentication Required:** JWT Bearer token", "operationId": "list_cycle_tasks_api_v1_workstreams_cycles__cycle_id__tasks_get", "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cycle Id" } }, { "name": "include", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated opt-ins. ``payloads`` restores inline raw output_data (debug only) \u2014 refused with 409 past a 5 MB inlined total.", "title": "Include" }, "description": "Comma-separated opt-ins. ``payloads`` restores inline raw output_data (debug only) \u2014 refused with 409 past a 5 MB inlined total." } ], "responses": { "200": { "description": "Tasks retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskListResponse" } } } }, "404": { "description": "Cycle not found" }, "401": { "description": "Unauthorized" }, "409": { "description": "?include=payloads refused: total payload > 5 MB (lazy-fetch instead)" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles/{cycle_id}/tasks/{task_id}": { "get": { "tags": [ "WorkStreams" ], "summary": "Get task detail", "description": "Get detailed information about a specific task.\n\n **Authentication Required:** JWT Bearer token", "operationId": "get_task_api_v1_workstreams_cycles__cycle_id__tasks__task_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cycle Id" } }, { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "200": { "description": "Task retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "404": { "description": "Task not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles/{cycle_id}/tasks/{task_id}/approve": { "post": { "tags": [ "WorkStreams" ], "summary": "Approve or reject task", "description": "Approve or reject a task that requires human approval.\n\n **Authentication Required:** JWT Bearer token", "operationId": "approve_task_api_v1_workstreams_cycles__cycle_id__tasks__task_id__approve_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cycle Id" } }, { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TaskApprovalRequest" }, { "type": "null" } ], "description": "Approval action and optional comment. Defaults to action='approve' when body is absent (MCP-friendly).", "title": "Request Body" } } } }, "responses": { "200": { "description": "Task decision recorded and the Workflow Update completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "400": { "description": "Task does not require approval or already processed" }, "404": { "description": "Task not found" }, "401": { "description": "Unauthorized" }, "502": { "description": "Temporal did not confirm the gate Update before the request deadline; retrying the same request is idempotent" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles/{cycle_id}/tasks/{task_id}/approve-with-signal": { "post": { "tags": [ "WorkStreams" ], "summary": "Approve task through a serialized Temporal Update", "description": "Approve a task that is pending approval through its Temporal workflow.\n\n This endpoint:\n 1. Validates that the task is an unresolved approval gate\n 2. Submits one task-scoped, deduplicated Workflow Update\n 3. Records approval evidence inside the Update before execution continues\n 4. Leaves lifecycle status transitions to the workflow's StateManager\n\n An ambiguous timeout returns ``workflow_signaled=false``. Retrying is safe:\n the deterministic Update ID returns the original decision and can never\n install an opposite one.\n\n **Use Case:** Human-in-the-loop approval for high-impact tasks that were\n paused by the workflow before execution.\n\n **Authentication Required:** JWT Bearer token", "operationId": "approve_task_with_signal_api_v1_workstreams_cycles__cycle_id__tasks__task_id__approve_with_signal_post", "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cycle Id" } }, { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequestModel" } } } }, "responses": { "200": { "description": "Task approved and Workflow Update completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalResponseModel" } } } }, "400": { "description": "Task is not awaiting approval" }, "404": { "description": "Task not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles/{cycle_id}/tasks/{task_id}/complete-upload": { "post": { "tags": [ "WorkStreams" ], "summary": "Signal that document upload is complete", "description": "Signal that all documents have been uploaded for a document_upload task.\n\n This endpoint:\n 1. Validates the task is in blocked/awaiting status\n 2. Counts attached files/artifacts\n 3. For inline cycles, completes the same evidence-first Workflow Update as approval\n 4. Leaves lifecycle transition to the owning workflow\n\n **Authentication Required:** JWT Bearer token", "operationId": "complete_task_upload_api_v1_workstreams_cycles__cycle_id__tasks__task_id__complete_upload_post", "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cycle Id" } }, { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "200": { "description": "Upload complete, workflow gate transport accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteUploadResponse" } } } }, "400": { "description": "Task is not awaiting upload or no files attached" }, "404": { "description": "Task not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles/{cycle_id}/tasks/{task_id}/generate-plan": { "post": { "tags": [ "WorkStreams" ], "summary": "Generate AI execution plan for task", "description": "Generate an AI-powered execution plan for a task before execution.\n\n The plan provides:\n - Step-by-step breakdown of what the task will do\n - Identification of write operations (highlighted for review)\n - Risk classification (low/medium/high) for each step\n - Estimated duration for each step\n - Expected inputs and outputs\n\n This endpoint supports the R-WS-001 specification for plan generation\n before task execution, enabling human review and approval.\n\n **Request Body Options:**\n - `include_context`: Include context from previous tasks (default: true)\n - `force_regenerate`: Regenerate even if a plan already exists (default: false)\n\n **Authentication Required:** JWT Bearer token", "operationId": "generate_task_plan_api_v1_workstreams_cycles__cycle_id__tasks__task_id__generate_plan_post", "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cycle Id" } }, { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneratePlanRequest", "default": { "include_context": true, "force_regenerate": false } } } } }, "responses": { "200": { "description": "Plan generated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneratePlanResponse" } } } }, "404": { "description": "Task or cycle not found" }, "401": { "description": "Unauthorized" }, "500": { "description": "Plan generation failed" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles/{cycle_id}/tasks/{task_id}/guide": { "post": { "tags": [ "WorkStreams Cycles" ], "summary": "Provide guidance to unblock a task", "description": "Send the provide_guidance signal to the cycle's Temporal workflow\n for a task that is waiting on human input.\n\n ``response`` is the free-text reply; ``option_value`` is the\n selected choice (when the task offered options).\n\n Backed by ``WorkstreamCycleService.send_guidance_signal`` \u2014 same backing\n path as the legacy ``provide_guidance`` endpoint.\n\n **Authentication Required:** JWT Bearer token", "operationId": "guide_cycle_task_api_v1_workstreams_cycles__cycle_id__tasks__task_id__guide_post", "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cycle Id" } }, { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvideGuidanceRequest" } } } }, "responses": { "204": { "description": "Guidance signal sent" }, "404": { "description": "Cycle or task not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles/{cycle_id}/tasks/{task_id}/hold": { "post": { "tags": [ "WorkStreams" ], "summary": "Hold a sign-off that cannot be given yet", "description": "Park a run at its approval gate because the sign-off is waiting on someone\n \u2014 typically a client question that has not been answered.\n\n **This is not a rejection.** Nothing failed, nobody is blamed, and the run\n is not swept: the gate task keeps its parked status with `approved_at`\n still NULL, so no external write can happen, and the cycle moves to\n `blocked` \u2014 resumable, not billed while it waits, and NOT reported as a\n failure. When the answer arrives the partner presses Approve on this same\n gate and the same cycle continues; there is no restart.\n\n Use `reject-with-signal` instead when the work is actually wrong.\n\n **Authentication Required:** JWT Bearer token", "operationId": "hold_task_signoff_api_v1_workstreams_cycles__cycle_id__tasks__task_id__hold_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cycle Id" } }, { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HoldRequestModel" } } } }, "responses": { "200": { "description": "Sign-off held; the run is parked and resumable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HoldResponseModel" } } } }, "400": { "description": "Task is not an approval gate, or is already resolved" }, "404": { "description": "Task not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles/{cycle_id}/tasks/{task_id}/hold/resume": { "post": { "tags": [ "WorkStreams" ], "summary": "Resume Task Hold", "description": "Reopen the exact held question; never approve or resume execution.", "operationId": "resume_task_hold_api_v1_workstreams_cycles__cycle_id__tasks__task_id__hold_resume_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cycle Id" } }, { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumeHoldRequestModel" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumeHoldResponseModel" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles/{cycle_id}/tasks/{task_id}/logs": { "get": { "tags": [ "WorkStreams" ], "summary": "Get task execution logs (Chain of Thought)", "description": "Retrieve the execution logs for a task.\n\n Provides timestamped, hierarchical log entries showing the AI's\n reasoning process during task execution. Supports filtering by\n level and category, text search, and pagination.\n\n **Query Parameters:**\n - `level`: Filter by log level (debug, info, warning, error)\n - `category`: Filter by category (planning, extraction, etc.)\n - `search`: Search text in message\n - `parent_id`: Get children of a specific log entry\n - `limit`: Results per page (1-500, default: 50)\n - `offset`: Pagination offset (default: 0)\n\n **Authentication Required:** JWT Bearer token", "operationId": "get_task_execution_logs_api_v1_workstreams_cycles__cycle_id__tasks__task_id__logs_get", "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cycle Id" } }, { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } }, { "name": "level", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/ExecutionLogLevel" }, { "type": "null" } ], "description": "Filter by log level", "title": "Level" }, "description": "Filter by log level" }, { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/ExecutionLogCategory" }, { "type": "null" } ], "description": "Filter by category", "title": "Category" }, "description": "Filter by category" }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "description": "Search in message", "title": "Search" }, "description": "Search in message" }, { "name": "parent_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by parent ID", "title": "Parent Id" }, "description": "Filter by parent ID" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "description": "Results per page", "default": 50, "title": "Limit" }, "description": "Results per page" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Pagination offset", "default": 0, "title": "Offset" }, "description": "Pagination offset" } ], "responses": { "200": { "description": "Execution logs retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionLogResponse" } } } }, "404": { "description": "Task or cycle not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles/{cycle_id}/tasks/{task_id}/logs/summary": { "get": { "tags": [ "WorkStreams" ], "summary": "Get execution log summary", "description": "Get summary statistics for task execution logs.\n\n Provides aggregated counts by level and category, timestamps,\n and duration information without returning individual entries.\n\n **Authentication Required:** JWT Bearer token", "operationId": "get_task_execution_log_summary_api_v1_workstreams_cycles__cycle_id__tasks__task_id__logs_summary_get", "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cycle Id" } }, { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "200": { "description": "Summary retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionLogSummary" } } } }, "404": { "description": "Task or cycle not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles/{cycle_id}/tasks/{task_id}/payload": { "get": { "tags": [ "WorkStreams" ], "summary": "Get task output payload by reference", "description": "Retrieve the full raw output_data payload for a specific task.", "operationId": "get_task_payload_api_v1_workstreams_cycles__cycle_id__tasks__task_id__payload_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cycle Id" } }, { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "200": { "description": "Task payload retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Task Payload Api V1 Workstreams Cycles Cycle Id Tasks Task Id Payload Get" } } } }, "404": { "description": "Task not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles/{cycle_id}/tasks/{task_id}/reject-with-signal": { "post": { "tags": [ "WorkStreams" ], "summary": "Reject task through a serialized Temporal Update", "description": "Reject a task that is pending approval through its Temporal workflow.\n\n This endpoint:\n 1. Validates that the task is an unresolved approval gate\n 2. Submits one task-scoped, deduplicated Workflow Update\n 3. Records rejection evidence inside the Update before execution continues\n 4. Leaves lifecycle status transitions to the workflow's StateManager\n\n An ambiguous timeout returns ``workflow_signaled=false``. Retrying is safe:\n the deterministic Update ID returns the original decision and can never\n install an opposite one.\n\n **Use Case:** Human-in-the-loop rejection for tasks with incorrect plans\n or parameters that need modification before re-execution.\n\n **Authentication Required:** JWT Bearer token", "operationId": "reject_task_with_signal_api_v1_workstreams_cycles__cycle_id__tasks__task_id__reject_with_signal_post", "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cycle Id" } }, { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RejectionRequestModel" } } } }, "responses": { "200": { "description": "Task rejected and Workflow Update completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalResponseModel" } } } }, "400": { "description": "Task is not awaiting approval" }, "404": { "description": "Task not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/cycles/{cycle_id}/tasks/{task_id}/upload-files": { "post": { "tags": [ "WorkStreams" ], "summary": "Link uploaded files to a document_upload task", "description": "Link files that were already uploaded via POST /files/upload to a\n document_upload task. Files are registered as cycle artifacts.\n\n This is a \"linking\" endpoint -- files are uploaded separately via the\n existing /files/upload route, then linked here.\n\n **Authentication Required:** JWT Bearer token", "operationId": "upload_task_files_api_v1_workstreams_cycles__cycle_id__tasks__task_id__upload_files_post", "parameters": [ { "name": "cycle_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cycle Id" } }, { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadFilesRequest" } } } }, "responses": { "200": { "description": "Files linked successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadFilesResponse" } } } }, "400": { "description": "Task is not a document_upload step or not in blocked status" }, "404": { "description": "Task or file not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/jobs": { "post": { "tags": [ "WorkStreams" ], "summary": "Create job definition", "description": "Create a new agentic job definition.", "operationId": "create_job_definition_api_v1_workstreams_jobs_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobDefinitionCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobDefinitionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "WorkStreams" ], "summary": "List job definitions", "description": "List job definitions for the workspace.", "operationId": "list_job_definitions_api_v1_workstreams_jobs_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "domain", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter to one domain (job_definition is domain-keyed, not workstream-bound \u2014 this is how the WorkPlans list groups recipes)", "title": "Domain" }, "description": "Filter to one domain (job_definition is domain-keyed, not workstream-bound \u2014 this is how the WorkPlans list groups recipes)" }, { "name": "workstream_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "When set, restrict to job_definitions that have at least one cycle in this workstream, and scope instance aggregates (total_runs, last_cycle_at, last_cycle_state) to that workstream.", "title": "Workstream Id" }, "description": "When set, restrict to job_definitions that have at least one cycle in this workstream, and scope instance aggregates (total_runs, last_cycle_at, last_cycle_state) to that workstream." }, { "name": "active_only", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Return only job_definitions with at least one cycle currently in flight (see ACTIVE_CYCLE_STATUSES). For live-worklist surfaces that show running work: without it the caller has to page the whole catalogue and filter client-side, and any limit then caps the wrong axis \u2014 newest jobs rather than active ones.", "default": false, "title": "Active Only" }, "description": "Return only job_definitions with at least one cycle currently in flight (see ACTIVE_CYCLE_STATUSES). For live-worklist surfaces that show running work: without it the caller has to page the whole catalogue and filter client-side, and any limit then caps the wrong axis \u2014 newest jobs rather than active ones." }, { "name": "standing_only", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Exclude per-run batch-fan-out groupings (the job_definitions a WorkPlan batch run auto-creates, marked by goal_template 'Batch fan-out \u2026'). True returns only STANDING WorkPlans/jobs \u2014 the feed for the dedicated 'my WorkPlans' surface. Default False keeps them.", "default": false, "title": "Standing Only" }, "description": "Exclude per-run batch-fan-out groupings (the job_definitions a WorkPlan batch run auto-creates, marked by goal_template 'Batch fan-out \u2026'). True returns only STANDING WorkPlans/jobs \u2014 the feed for the dedicated 'my WorkPlans' surface. Default False keeps them." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobDefinitionListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/jobs/{job_id}": { "get": { "tags": [ "WorkStreams" ], "summary": "Get job definition", "description": "Get a job definition by ID or permakey.", "operationId": "get_job_definition_api_v1_workstreams_jobs__job_id__get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobDefinitionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "WorkStreams" ], "summary": "Update job definition", "description": "Update a job definition (by ID or permakey).", "operationId": "update_job_definition_api_v1_workstreams_jobs__job_id__patch", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobDefinitionUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobDefinitionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "WorkStreams" ], "summary": "Delete (archive) job definition", "description": "Soft-delete a job definition by archiving it (status='archived',\n is_enabled=False). The row and all cycle history are retained; the job no\n longer runs on schedule and cannot be fan-out launched until restored via\n PATCH (status='active', is_enabled=true).\n\n Archiving frees the plan's NAME for reuse \u2014 `uq_job_definition_name` is\n keyed `WHERE status <> 'archived'`.\n\n Distinct from PAUSING, which is status='paused': a paused plan keeps its\n name and its place in the list, and is expected to be resumed.\n\n Idempotent \u2014 deleting an already-archived job returns 204.", "operationId": "delete_job_definition_api_v1_workstreams_jobs__job_id__delete", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "204": { "description": "Job definition archived" }, "401": { "description": "Unauthorized" }, "404": { "description": "Job definition not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/jobs/{job_id}/approve-gate": { "post": { "tags": [ "WorkStreams" ], "summary": "Approve (or reject) every awaiting gate in a cohort at once", "description": "Sweep a WorkPlan cohort's approval gates in one call \u2014 the\n 'Approve all' affordance for the swarm matrix. Auto-discovers every cohort cycle\n (by job_definition_id) currently parked at an approval gate and fans the same\n decision across them via the same fail-soft + Temporal-Update path as\n /cycles/approve-bulk. A cohort with nothing at a gate is a clean no-op\n (discovered=0). For SELECTIVE approve (some, not all) use /cycles/approve-bulk\n with explicit pairs.\n\n **Authentication Required:** JWT Bearer token.", "operationId": "approve_job_gate_api_v1_workstreams_jobs__job_id__approve_gate_post", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Job Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveGateRequestModel" } } } }, "responses": { "200": { "description": "Cohort gates swept", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveGateResponseModel" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/jobs/{job_id}/cycles": { "get": { "tags": [ "WorkStreams" ], "summary": "List cycles for a job definition", "description": "Fleet view: all cycles created by this job, optionally filtered by period.", "operationId": "list_job_cycles_api_v1_workstreams_jobs__job_id__cycles_get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "period", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by period label", "title": "Period" }, "description": "Filter by period label" }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 100, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response List Job Cycles Api V1 Workstreams Jobs Job Id Cycles Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/jobs/{job_id}/next-runs": { "get": { "tags": [ "WorkStreams" ], "summary": "Next-runs preview (rich, unshadowed jobs-scoped mount)", "description": "Same handler as GET /workplans/{id}/next-runs on the jobs router, mounted at a path the blueprints router does not shadow. Returns per-run original_at/shifted/shift_reason for holiday-shift markers; ?client_id= previews that client's schedule_override.", "operationId": "preview_next_runs_api_v1_workstreams_jobs__job_id__next_runs_get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 20, "minimum": 1, "description": "Number of upcoming runs to preview.", "default": 5, "title": "Count" }, "description": "Number of upcoming runs to preview." }, { "name": "client_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Preview a specific client's OWN cadence. When the WorkPlan has a schedule_override for this client, the preview uses that override's cron/timezone/skip_weekends/holiday_calendar; otherwise it falls back to the plan schedule (schedule_source in the response says which).", "title": "Client Id" }, "description": "Preview a specific client's OWN cadence. When the WorkPlan has a schedule_override for this client, the preview uses that override's cron/timezone/skip_weekends/holiday_calendar; otherwise it falls back to the plan schedule (schedule_source in the response says which)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NextRunPreviewResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/jobs/{job_id}/roster": { "get": { "tags": [ "WorkStreams" ], "summary": "Get job roster", "description": "All-clients cohort roster for a job_definition-backed WorkPlan.", "operationId": "get_job_roster_api_v1_workstreams_jobs__job_id__roster_get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Case-insensitive client-name substring filter", "title": "Q" }, "description": "Case-insensitive client-name substring filter" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "description": "exceptions_first | name | cycle_status | readiness", "default": "exceptions_first", "title": "Sort" }, "description": "exceptions_first | name | cycle_status | readiness" }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by derived cycle_status", "title": "Status" }, "description": "Filter by derived cycle_status" }, { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter to clients with >=1 FILE input in this source_category", "title": "Category" }, "description": "Filter to clients with >=1 FILE input in this source_category" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Page size", "default": 50, "title": "Limit" }, "description": "Page size" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Pagination offset", "default": 0, "title": "Offset" }, "description": "Pagination offset" } ], "responses": { "200": { "description": "Cohort roster", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkplanRoster" } } } }, "404": { "description": "Job definition not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/jobs/{job_id}/run": { "post": { "tags": [ "WorkStreams" ], "summary": "Run job (fan-out across clients)", "description": "Resolve the job's target_selector to a list of clients, then create\n one agentic cycle per client and start Temporal workflows.\n\n If `client_ids` is provided in the request body, it overrides the\n job's target_selector (useful for manual runs on a subset).", "operationId": "run_job_api_v1_workstreams_jobs__job_id__run_post", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/FanOutRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FanOutResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/jobs/{job_id}/versions": { "get": { "tags": [ "WorkStreams" ], "summary": "List WorkPlan version history", "description": "Return all version snapshots for a WorkPlan, newest first.", "operationId": "list_job_definition_versions_api_v1_workstreams_jobs__job_id__versions_get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/JobDefinitionVersionResponse" }, "title": "Response List Job Definition Versions Api V1 Workstreams Jobs Job Id Versions Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/jobs/{job_id}/versions/{version_num}": { "get": { "tags": [ "WorkStreams" ], "summary": "Get a specific WorkPlan version snapshot", "description": "Return one version snapshot by version number.", "operationId": "get_job_definition_version_api_v1_workstreams_jobs__job_id__versions__version_num__get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "version_num", "in": "path", "required": true, "schema": { "type": "integer", "title": "Version Num" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobDefinitionVersionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/jobs/{job_id}/versions/{version_num}/rollback": { "post": { "tags": [ "WorkStreams" ], "summary": "Rollback a WorkPlan to a prior version", "description": "Restore the WorkPlan's config to the state captured in version_num.\n\nRollback is APPEND-ONLY: it writes the prior snapshot as a NEW version\n(current_version + 1) rather than rewriting history. The permakey and all\nexternal URLs are unchanged \u2014 identity is anchored on permakey, not version.", "operationId": "rollback_job_definition_api_v1_workstreams_jobs__job_id__versions__version_num__rollback_post", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "version_num", "in": "path", "required": true, "schema": { "type": "integer", "title": "Version Num" } } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobDefinitionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/steps/describe-from-wdl": { "post": { "tags": [ "WorkStreams" ], "summary": "Describe a single workstream step in plain English", "description": "Describe a single workstream step in plain English from its WDL JSON.\n\n Reverse-direction sibling of ``/workstreams/steps/generate-from-description``.\n Use this when the caller has edited the WDL JSON directly and needs\n a refreshed description to surface in the step-card description\n textarea (the FE ``useStepWdlSync`` hook debounces ~600ms then calls\n this endpoint).\n\n **Response is always Server-Sent Events.** Each ``event: token``\n frame carries a ``text_delta`` chunk as Claude emits the\n description. A terminal ``event: complete`` frame carries a\n ``DescribeStepFromWdlResponse`` payload whose ``result.description``\n is the cap-trimmed, markdown-stripped final text. On failure an\n ``event: error`` frame is emitted before the stream closes.\n\n **Output discipline:** plain text, ~2 sentences, 120-240 chars by\n default (overridable via ``context.max_length``). No markdown / code\n blocks / inline backticks \u2014 output lands directly in a description\n textarea.\n\n **Authentication Required:** JWT Bearer token", "operationId": "describe_step_from_wdl_api_v1_workstreams_steps_describe_from_wdl_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DescribeStepFromWdlRequest" } } }, "required": true }, "responses": { "200": { "description": "Description generated successfully. Always returned as ``text/event-stream``.", "content": { "application/json": { "schema": {} }, "text/event-stream": {} } }, "400": { "description": "Invalid request data" }, "401": { "description": "Unauthorized" }, "500": { "description": "Description failed" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/steps/generate-from-description": { "post": { "tags": [ "WorkStreams" ], "summary": "Generate a single workstream step from a description", "description": "Generate a single workstream step from a natural-language description.\n\n Step-scope sibling of ``/workstreams/templates/generate-from-description``.\n Use this when the caller already has a workstream and only needs one\n step regenerated (e.g. a step-card \"improve with AI\" affordance).\n\n **Response is always Server-Sent Events.** Each ``event: token``\n frame carries an ``input_json_delta`` chunk as Claude builds the\n tool input. A terminal ``event: complete`` frame carries a\n ``GenerateStepFromDescriptionResponse`` payload. On failure an\n ``event: error`` frame is emitted before the stream closes.\n\n **Authentication Required:** JWT Bearer token", "operationId": "generate_step_from_description_api_v1_workstreams_steps_generate_from_description_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateStepFromDescriptionRequest" } } }, "required": true }, "responses": { "200": { "description": "Step generated successfully. Always returned as ``text/event-stream``.", "content": { "application/json": { "schema": {} }, "text/event-stream": {} } }, "400": { "description": "Invalid request data" }, "401": { "description": "Unauthorized" }, "500": { "description": "Generation failed" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/tasks/{task_id}/approve/": { "post": { "tags": [ "WorkStreams" ], "summary": "Approve task (frontend convenience)", "description": "Approve a task without needing cycle_id in the path. Looks up cycle_id internally and completes the Temporal Workflow Update.", "operationId": "approve_task_convenience_api_v1_workstreams_tasks__task_id__approve__post", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskApprovalRequest" } } } }, "responses": { "200": { "description": "Task approved and Workflow Update completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalResponseModel" } } } }, "400": { "description": "Task is not awaiting approval" }, "404": { "description": "Task not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/tasks/{task_id}/reject/": { "post": { "tags": [ "WorkStreams" ], "summary": "Reject task (frontend convenience)", "description": "Reject a task without needing cycle_id in the path. Looks up cycle_id internally and completes the Temporal Workflow Update.", "operationId": "reject_task_convenience_api_v1_workstreams_tasks__task_id__reject__post", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RejectionRequestModel" } } } }, "responses": { "200": { "description": "Task rejected and Workflow Update completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalResponseModel" } } } }, "400": { "description": "Task is not awaiting approval" }, "404": { "description": "Task not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/templates": { "get": { "tags": [ "WorkStreams" ], "summary": "List workflow templates", "description": "List all available workflow templates.\n\n Templates are reusable workflow definitions that can be customized into\n blueprints for specific clients.\n\n **Query Parameters:**\n - `category`: Filter by template category\n - `status`: Filter by template status (default: active)\n - `limit`: Results per page (1-100, default: 20)\n - `offset`: Pagination offset (default: 0)\n\n **Authentication Required:** JWT Bearer token", "operationId": "list_templates_api_v1_workstreams_templates_get", "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by category", "title": "Category" }, "description": "Filter by category" }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Search by name or description", "title": "Search" }, "description": "Search by name or description" }, { "name": "runnable_only", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Only include templates with at least one active linked blueprint", "default": false, "title": "Runnable Only" }, "description": "Only include templates with at least one active linked blueprint" }, { "name": "launchable_only", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Only include LAUNCHABLE recipes \u2014 workstreams with a step DAG (non-empty `steps`) or an agentic `goal_spec`. Excludes agentic CONTAINERS (the per-job and ad-hoc workstreams, which have neither and are run via /jobs/{id}/run, not @-mention). Note: `is_template` is NOT the launchability signal \u2014 the FIC catalogue and firm recipes ship `is_template=false` but are launchable.", "default": false, "title": "Launchable Only" }, "description": "Only include LAUNCHABLE recipes \u2014 workstreams with a step DAG (non-empty `steps`) or an agentic `goal_spec`. Excludes agentic CONTAINERS (the per-job and ad-hoc workstreams, which have neither and are run via /jobs/{id}/run, not @-mention). Note: `is_template` is NOT the launchability signal \u2014 the FIC catalogue and firm recipes ship `is_template=false` but are launchable." }, { "name": "is_template", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Optional filter on the `is_template` column. Default: include BOTH template and non-template workstreams. Pass `true` to restrict to flagged templates (legacy behaviour); pass `false` to restrict to non-template workstreams.", "title": "Is Template" }, "description": "Optional filter on the `is_template` column. Default: include BOTH template and non-template workstreams. Pass `true` to restrict to flagged templates (legacy behaviour); pass `false` to restrict to non-template workstreams." }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/WorkstreamStatus", "description": "Filter by status", "default": "active" }, "description": "Filter by status" }, { "name": "include_all_statuses", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Return EVERY status instead of just `?status=`. For a surface that does its own status filtering client-side \u2014 the 'My WorkStreams' list, whose Live/Drafts/Archived chips filter and COUNT over one fetched set. Default False so the @-mention picker keeps seeing only active rows.", "default": false, "title": "Include All Statuses" }, "description": "Return EVERY status instead of just `?status=`. For a surface that does its own status filtering client-side \u2014 the 'My WorkStreams' list, whose Live/Drafts/Archived chips filter and COUNT over one fetched set. Default False so the @-mention picker keeps seeing only active rows." }, { "name": "include_all_workspaces", "in": "query", "required": false, "schema": { "type": "boolean", "description": "god-mode ONLY: include workstreams from ALL workspaces (the WSS Trace/Studio cross-workspace view). Default False so the @-mention launcher picker stays scoped to the caller's workspace \u2014 it must never surface templates the caller can't launch here.", "default": false, "title": "Include All Workspaces" }, "description": "god-mode ONLY: include workstreams from ALL workspaces (the WSS Trace/Studio cross-workspace view). Default False so the @-mention launcher picker stays scoped to the caller's workspace \u2014 it must never surface templates the caller can't launch here." }, { "name": "include_internal", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include engineering/test 'plumbing' rows in the result. Default False \u2014 the recipe LIBRARY hides the internal bucket (FIC:/Demo:/Read PDF rows + the 'internal' catch-all category) so the customer-facing grid shows only curated catalog + real recipes. Pass True for the @-mention picker / eng tooling that needs them.", "default": false, "title": "Include Internal" }, "description": "Include engineering/test 'plumbing' rows in the result. Default False \u2014 the recipe LIBRARY hides the internal bucket (FIC:/Demo:/Read PDF rows + the 'internal' catch-all category) so the customer-facing grid shows only curated catalog + real recipes. Pass True for the @-mention picker / eng tooling that needs them." }, { "name": "scope", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "firm", "team", "user" ], "type": "string" }, { "type": "null" } ], "description": "Filter by distribution scope \u2014 the customer 'My WorkStreams' view is grouped firm -> team -> user (#170). When set, the firm-scoped FIC workstreams become visible (the default grid's FIC name-hide is skipped for an explicit scope view); eng plumbing stays hidden. Omit for the default catalog grid. `gallery`/`plan` scopes are not filter options (gallery is parked).", "title": "Scope" }, "description": "Filter by distribution scope \u2014 the customer 'My WorkStreams' view is grouped firm -> team -> user (#170). When set, the firm-scoped FIC workstreams become visible (the default grid's FIC name-hide is skipped for an explicit scope view); eng plumbing stays hidden. Omit for the default catalog grid. `gallery`/`plan` scopes are not filter options (gallery is parked)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "description": "Results per page", "default": 20, "title": "Limit" }, "description": "Results per page" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Pagination offset", "default": 0, "title": "Offset" }, "description": "Pagination offset" } ], "responses": { "200": { "description": "Templates retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateListResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing JWT token" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "WorkStreams" ], "summary": "Create workflow template", "description": "Create a new workflow template.\n\n Templates define reusable workflow steps that can be instantiated\n as client-specific blueprints.\n\n **Authentication Required:** JWT Bearer token", "operationId": "create_template_api_v1_workstreams_templates_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateCreate" } } } }, "responses": { "201": { "description": "Template created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateResponse" } } } }, "400": { "description": "Invalid request data" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/templates/generate-from-description": { "post": { "tags": [ "WorkStreams" ], "summary": "Generate workstream from description", "description": "Generate a complete workstream definition using AI from a natural language description.\n\n This endpoint uses Claude Haiku to analyze the description and generate\n a structured WorkStream Definition Language (WDL) workflow with appropriate\n steps, agents, and approval gates.\n\n **Response modes (content-negotiated via the ``Accept`` header):**\n\n - ``Accept: text/event-stream`` \u2014 Server-Sent Events. Each ``event: token``\n frame carries an ``input_json_delta`` chunk as Claude builds the tool\n input. A terminal ``event: complete`` frame carries the same JSON shape\n as the default mode below (``GenerateFromDescriptionResponse``). On\n failure an ``event: error`` frame is emitted before the stream closes.\n - Default (``application/json`` or any other ``Accept``) \u2014 one-shot JSON\n response matching ``GenerateFromDescriptionResponse``. Preserves the\n legacy contract for clients that haven't migrated to SSE.\n\n **Authentication Required:** JWT Bearer token", "operationId": "generate_template_from_description_api_v1_workstreams_templates_generate_from_description_post", "parameters": [ { "name": "accept", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Accept" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateFromDescriptionRequest" } } } }, "responses": { "200": { "description": "Workstream generated successfully. JSON by default; SSE when ``Accept: text/event-stream`` is sent.", "content": { "application/json": { "schema": { "$defs": { "GenerationMetadataResponse": { "description": "Metadata about the generation process.", "properties": { "model": { "title": "Model", "type": "string" }, "tokens_used": { "title": "Tokens Used", "type": "integer" }, "generation_time_ms": { "title": "Generation Time Ms", "type": "integer" } }, "required": [ "model", "tokens_used", "generation_time_ms" ], "title": "GenerationMetadataResponse", "type": "object" } }, "description": "Response containing the generated workstream.", "properties": { "name": { "title": "Name", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" }, "steps": { "items": { "additionalProperties": true, "type": "object" }, "title": "Steps", "type": "array" }, "suggested_tags": { "items": { "type": "string" }, "title": "Suggested Tags", "type": "array" }, "generation_metadata": { "$ref": "#/$defs/GenerationMetadataResponse" } }, "required": [ "name", "steps", "generation_metadata" ], "title": "GenerateFromDescriptionResponse", "type": "object" } }, "text/event-stream": {} } }, "400": { "description": "Invalid request data" }, "401": { "description": "Unauthorized" }, "500": { "description": "Generation failed" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/templates/import": { "post": { "tags": [ "WorkStreams" ], "summary": "Import a workstream definition", "description": "Create a new workstream in the caller's workspace from an exported definition payload. Provenance (source workspace, version, export timestamp) is recorded in the version snapshot's change_summary. This is the dev\u2192prod promotion path: export from one environment, import into another.", "operationId": "import_template_api_v1_workstreams_templates_import_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkstreamImportRequest" } } }, "required": true }, "responses": { "201": { "description": "Workstream imported successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateResponse" } } } }, "400": { "description": "Invalid definition payload" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/templates/{template_id}": { "get": { "tags": [ "WorkStreams" ], "summary": "Get template by ID", "description": "Retrieve a specific workflow template by ID.\n\n **Authentication Required:** JWT Bearer token", "operationId": "get_template_api_v1_workstreams_templates__template_id__get", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Template Id" } } ], "responses": { "200": { "description": "Template retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateResponse" } } } }, "404": { "description": "Template not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "WorkStreams" ], "summary": "Update template", "description": "Update an existing workflow template.\n\n Only provided fields will be updated. Omitted fields remain unchanged.\n\n **Authentication Required:** JWT Bearer token", "operationId": "update_template_api_v1_workstreams_templates__template_id__patch", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Template Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateUpdate" } } } }, "responses": { "200": { "description": "Template updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateResponse" } } } }, "404": { "description": "Template not found" }, "400": { "description": "Invalid request data" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "WorkStreams" ], "summary": "Delete template", "description": "Delete a template and cascade-delete its blueprints and cycles.\n\n **Authentication Required:** JWT Bearer token", "operationId": "delete_template_api_v1_workstreams_templates__template_id__delete", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Template Id" } } ], "responses": { "204": { "description": "Template deleted successfully" }, "404": { "description": "Template not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/templates/{template_id}/export": { "get": { "tags": [ "WorkStreams" ], "summary": "Export a workstream definition", "description": "Return the portable definition of a workstream \u2014 steps, input_schema, output_schema, goal_spec, and provenance metadata. The JSON payload can be saved to a file and later POSTed to /templates/import in any workspace or environment to create a copy.", "operationId": "export_template_api_v1_workstreams_templates__template_id__export_get", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Template Id" } } ], "responses": { "200": { "description": "Export payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkstreamExportPayload-Output" } } } }, "404": { "description": "Template not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/templates/{template_id}/fork": { "post": { "tags": [ "WorkStreams" ], "summary": "Fork a recipe into a private copy", "description": "Fork a recipe (UUID or slug) the caller can see (their workspace or the\n public catalog) into a new PRIVATE draft copy in their workspace, with\n ``parent_workstream_id`` set so the detail page can show 'forked from \u2026'.\n\n The prototype's distribution Fork affordance. Promote/Publish (scope\n widening) are a separate governance-gated endpoint.\n\n **Authentication Required:** JWT Bearer token", "operationId": "fork_template_api_v1_workstreams_templates__template_id__fork_post", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Template Id" } } ], "responses": { "201": { "description": "Recipe forked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkstreamForkResponse" } } } }, "404": { "description": "Source recipe not visible to the caller" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/templates/{template_id}/promote": { "post": { "tags": [ "WorkStreams" ], "summary": "Promote a recipe to workspace library", "description": "Promote a private draft recipe to the shared workspace library.", "operationId": "promote_template_api_v1_workstreams_templates__template_id__promote_post", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Template Id" } } ], "responses": { "200": { "description": "Recipe promoted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateResponse" } } } }, "404": { "description": "Recipe not found" }, "400": { "description": "Invalid scope promotion" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/templates/{template_id}/publish": { "post": { "tags": [ "WorkStreams" ], "summary": "Publish a recipe to the public gallery", "description": "Publish a firm recipe to the public gallery.", "operationId": "publish_template_api_v1_workstreams_templates__template_id__publish_post", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Template Id" } } ], "responses": { "200": { "description": "Recipe published", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateResponse" } } } }, "404": { "description": "Recipe not found" }, "400": { "description": "Invalid scope promotion" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/templates/{template_id}/versions": { "get": { "tags": [ "WorkStreams" ], "summary": "List template version history", "description": "List all version snapshots for a template, ordered by version descending.\n\n **Authentication Required:** JWT Bearer token", "operationId": "list_template_versions_api_v1_workstreams_templates__template_id__versions_get", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Template Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Results per page", "default": 50, "title": "Limit" }, "description": "Results per page" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Pagination offset", "default": 0, "title": "Offset" }, "description": "Pagination offset" } ], "responses": { "200": { "description": "Version history retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateVersionListResponse" } } } }, "404": { "description": "Template not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/templates/{template_id}/versions/{version}/restore": { "post": { "tags": [ "WorkStreams" ], "summary": "Restore template to a previous version", "description": "Restore a template to a previous version snapshot.\n\n This creates a new version (does not revert the version number)\n with the data from the specified snapshot.\n\n **Authentication Required:** JWT Bearer token", "operationId": "restore_template_version_api_v1_workstreams_templates__template_id__versions__version__restore_post", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Template Id" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Version number to restore", "title": "Version" }, "description": "Version number to restore" } ], "responses": { "200": { "description": "Template restored successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateResponse" } } } }, "404": { "description": "Template or version not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/tools": { "get": { "tags": [ "WorkStreams" ], "summary": "List custom tools for this workspace (AR-512)", "operationId": "list_tools_api_v1_workstreams_tools_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolListResponse" } } } } } }, "post": { "tags": [ "WorkStreams" ], "summary": "Register a custom HTTP tool (AR-512)", "description": "Register a tool at runtime that is callable from a workstream step WITHOUT a PR, merge, or deploy. The tool is scoped to the request's workspace \u2014 no other workspace can see or dispatch it.", "operationId": "register_tool_api_v1_workstreams_tools_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolRegisterRequest" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/tools/{tool_id}": { "delete": { "tags": [ "WorkStreams" ], "summary": "Delete a custom tool (AR-512)", "operationId": "delete_tool_api_v1_workstreams_tools__tool_id__delete", "parameters": [ { "name": "tool_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Tool Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/triggers/{trigger_id}": { "put": { "tags": [ "WorkStreams" ], "summary": "Update trigger", "description": "Update a trigger's configuration.\n\n **Authentication Required:** JWT Bearer token", "operationId": "update_trigger_api_v1_workstreams_triggers__trigger_id__put", "parameters": [ { "name": "trigger_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Trigger Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerUpdate" } } } }, "responses": { "200": { "description": "Trigger updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerResponse" } } } }, "404": { "description": "Trigger not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "WorkStreams" ], "summary": "Delete trigger", "description": "Delete a trigger.\n\n **Authentication Required:** JWT Bearer token", "operationId": "delete_trigger_api_v1_workstreams_triggers__trigger_id__delete", "parameters": [ { "name": "trigger_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Trigger Id" } } ], "responses": { "204": { "description": "Trigger deleted successfully" }, "404": { "description": "Trigger not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/triggers/{trigger_id}/fire": { "post": { "tags": [ "WorkStreams" ], "summary": "Fire workstream trigger via webhook", "description": "Accept an inbound webhook and launch a workstream cycle.", "operationId": "fire_trigger_webhook_api_v1_workstreams_triggers__trigger_id__fire_post", "parameters": [ { "name": "trigger_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Trigger Id" } }, { "name": "X-Webhook-Signature", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Webhook-Signature" } }, { "name": "X-Webhook-Timestamp", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Webhook-Timestamp" } }, { "name": "X-Webhook-Delivery-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Webhook-Delivery-Id" } } ], "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Fire Trigger Webhook Api V1 Workstreams Triggers Trigger Id Fire Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/workplan-domains": { "get": { "tags": [ "WorkStreams" ], "summary": "List WorkPlan-able DomainAgents (the domain-centric create picker)", "description": "Catalog of the named DomainAgents a WorkPlan can be created against.\n\nA WorkPlan runs a DOMAIN's goal across clients \u2014 recipes carry no intrinsic\ndomain (it lives on the job_definition, reachable only via a run), so the\ncreate picker is domain-centric: it lists these DomainAgents and feeds the\nchosen ``domain_key`` into ``POST /workstreams/jobs {domain}``. Static,\nregistry-backed \u2014 no DB, workspace-agnostic. Import is local to keep the\nrouter-load import graph light (mirrors ``_templates._domain_agent_key``).", "operationId": "list_workplan_domains_api_v1_workstreams_workplan_domains_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkplanDomainsResponse" } } } } } } }, "/api/v1/workstreams/workplans": { "get": { "tags": [ "WorkStreams" ], "summary": "List workplans", "description": "List workplans with optional client filter.\n\n A workplan is a client-specific workflow configuration derived from a\n template (a Workstream bound to a client + jurisdiction).\n\n **Query Parameters:**\n - `template_id`: Filter by template/workstream UUID\n - `client_id`: Filter by client UUID\n - `status`: Filter by status (default: active)\n - `limit`: Results per page (1-100, default: 20)\n - `offset`: Pagination offset (default: 0)\n\n **Authentication Required:** JWT Bearer token", "operationId": "list_blueprints_api_v1_workstreams_workplans_get", "parameters": [ { "name": "template_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Filter by template/workstream", "title": "Template Id" }, "description": "Filter by template/workstream" }, { "name": "client_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Filter by client", "title": "Client Id" }, "description": "Filter by client" }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/WorkstreamStatus", "description": "Filter by status", "default": "active" }, "description": "Filter by status" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Results per page", "default": 20, "title": "Limit" }, "description": "Results per page" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Pagination offset", "default": 0, "title": "Offset" }, "description": "Pagination offset" } ], "responses": { "200": { "description": "Workplans retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkplanListResponse" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "WorkStreams" ], "summary": "Create workplan (writes job_definition)", "description": "Create a new WorkPlan from a workstream template.\n\n **Stage-5 convergence (2026-07-02):** this endpoint now writes a\n ``job_definition`` row (the canonical WorkPlan model) instead of the\n legacy ``blueprint`` table. The request shape is unchanged; the\n response is now ``JobDefinitionResponse``.\n\n ``client_ids`` (multi-client roster) maps to\n ``target_selector.type = 'client_list'``; ``client_id`` maps to\n ``target_selector.type = 'single_client'``; neither maps to\n ``target_selector.type = 'manual'``. ``client_id`` and ``client_ids``\n are mutually exclusive.\n\n **Authentication Required:** JWT Bearer token", "operationId": "create_workplan_api_v1_workstreams_workplans_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkplanCreate" } } } }, "responses": { "201": { "description": "WorkPlan (job_definition) created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobDefinitionResponse" } } } }, "400": { "description": "Workstream template not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/workplans/{blueprint_id}": { "get": { "tags": [ "WorkStreams" ], "summary": "Get workplan by ID or permakey", "description": "Retrieve a workplan by ID or permakey. Resolves both blueprint-backed and\n job_definition-backed workplans. Blueprint rows include ws_permakey (parent\n WorkStream); job_definition rows return ws_permakey=null (no workstream FK).\n\n **Authentication Required:** JWT Bearer token", "operationId": "get_blueprint_api_v1_workstreams_workplans__blueprint_id__get", "parameters": [ { "name": "blueprint_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Blueprint Id" } } ], "responses": { "200": { "description": "Workplan retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workplan" } } } }, "404": { "description": "Workplan not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "WorkStreams" ], "summary": "Update workplan", "description": "Update a workplan's configuration.\n\n **Authentication Required:** JWT Bearer token", "operationId": "update_blueprint_api_v1_workstreams_workplans__blueprint_id__put", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "blueprint_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Blueprint Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkplanUpdate" } } } }, "responses": { "200": { "description": "Workplan updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workplan" } } } }, "404": { "description": "Workplan not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "WorkStreams" ], "summary": "Patch workplan config (partial save)", "description": "Partially update a workplan's saved configuration \u2014 the WorkPlan-detail\n Save control (two-col / S2). Every field is optional; only the fields\n present in the body are changed (omitting a field leaves the stored value\n untouched). Accepts the same plan-settings as the PUT update:\n\n - `schedule` \u2014 cron expression (validated; invalid cron \u2192 422)\n - `schedule_timezone` \u2014 IANA timezone (validated; unknown tz \u2192 422)\n - `max_duration_minutes` \u2014 guardrail, positive and \u2264 1440 (24h)\n - `human_checkpoints` \u2014 sign-off gate list ([] clears the gate)\n - `run_mode` / `default_context.autonomy` \u2014 propose|auto_run (enum-validated)\n\n Tenant-scoped: only the owning workspace may patch the workplan (a foreign\n workplan id is a 404, never a cross-firm write). Returns the updated\n Workplan in the same shape as the GET read so the FE can refresh in place.\n\n **Authentication Required:** JWT Bearer token", "operationId": "patch_blueprint_api_v1_workstreams_workplans__blueprint_id__patch", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "blueprint_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Blueprint Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkplanUpdate" } } } }, "responses": { "200": { "description": "Workplan config saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workplan" } } } }, "404": { "description": "Workplan not found" }, "422": { "description": "Invalid schedule / timezone / autonomy / guardrail" }, "401": { "description": "Unauthorized" } } }, "delete": { "tags": [ "WorkStreams" ], "summary": "Archive workplan", "description": "Archive a workplan (soft delete by setting status to 'archived').\n\n **Authentication Required:** JWT Bearer token", "operationId": "delete_blueprint_api_v1_workstreams_workplans__blueprint_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "blueprint_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Blueprint Id" } } ], "responses": { "204": { "description": "Workplan archived successfully" }, "404": { "description": "Workplan not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/workplans/{blueprint_id}/clients/{client_id}/alterations": { "get": { "tags": [ "WorkStreams" ], "summary": "Per-client alteration page", "description": "Base steps + the client's active alterations overlaid + the data sources.", "operationId": "get_client_alterations_api_v1_workstreams_workplans__blueprint_id__clients__client_id__alterations_get", "parameters": [ { "name": "blueprint_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Blueprint Id" } }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Client Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientAlterationPage" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "WorkStreams" ], "summary": "Replace the client's alteration set", "description": "Declarative all-or-nothing save of the whole patch set (S3 \u00a73a).", "operationId": "put_client_alterations_api_v1_workstreams_workplans__blueprint_id__clients__client_id__alterations_put", "parameters": [ { "name": "blueprint_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Blueprint Id" } }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Client Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlterationPutRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientAlterationPage" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "WorkStreams" ], "summary": "Clear all the client's alterations", "description": "Clear the client's alterations (status stays active, patches=[]) (S3 \u00a73d).", "operationId": "clear_client_alterations_api_v1_workstreams_workplans__blueprint_id__clients__client_id__alterations_delete", "parameters": [ { "name": "blueprint_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Blueprint Id" } }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Client Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientAlterationPage" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/workplans/{blueprint_id}/clients/{client_id}/alterations/patches": { "post": { "tags": [ "WorkStreams" ], "summary": "Add one alteration", "description": "Append one validated alteration to the client's set (S3 \u00a73b).", "operationId": "add_client_alteration_api_v1_workstreams_workplans__blueprint_id__clients__client_id__alterations_patches_post", "parameters": [ { "name": "blueprint_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Blueprint Id" } }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Client Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Patch" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlterationCountResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/workplans/{blueprint_id}/clients/{client_id}/alterations/patches/{patch_id}": { "delete": { "tags": [ "WorkStreams" ], "summary": "Remove one alteration", "description": "Remove an alteration by id (S3 \u00a73c).", "operationId": "delete_client_alteration_api_v1_workstreams_workplans__blueprint_id__clients__client_id__alterations_patches__patch_id__delete", "parameters": [ { "name": "blueprint_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Blueprint Id" } }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Client Id" } }, { "name": "patch_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Patch Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlterationCountResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/workplans/{blueprint_id}/disable-writes": { "post": { "tags": [ "WorkStreams" ], "summary": "Disable write operations", "description": "Disable write operations for a workplan.\n\n Returns the workplan to read-only mode, preventing any write\n operations to external systems.\n\n **Authentication Required:** JWT Bearer token\n\n **Security:** Logged to security audit trail.", "operationId": "disable_writes_api_v1_workstreams_workplans__blueprint_id__disable_writes_post", "parameters": [ { "name": "blueprint_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Blueprint Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DisableWritesRequest" }, { "type": "null" } ], "title": "Request Body" } } } }, "responses": { "200": { "description": "Writes disabled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WriteModeTransitionResponse" } } } }, "404": { "description": "Workplan not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/workplans/{blueprint_id}/enable-writes": { "post": { "tags": [ "WorkStreams" ], "summary": "Enable write operations", "description": "Enable write operations for a workplan.\n\n By default, workplans are in read-only mode. This endpoint enables\n write operations with explicit confirmation.\n\n **Requirements:**\n - `confirmation: true` must be set in request body\n - `reason` is required for audit trail\n\n **Authentication Required:** JWT Bearer token\n\n **Security:** Logged to security audit trail.", "operationId": "enable_writes_api_v1_workstreams_workplans__blueprint_id__enable_writes_post", "parameters": [ { "name": "blueprint_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Blueprint Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnableWritesRequest" } } } }, "responses": { "200": { "description": "Writes enabled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WriteModeTransitionResponse" } } } }, "400": { "description": "Missing confirmation or reason" }, "404": { "description": "Workplan not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/workplans/{blueprint_id}/input-resolution": { "get": { "tags": [ "WorkStreams" ], "summary": "Resolve a workplan's inputs per client (sourced vs missing)", "description": "For each requested client, report every declared input of the workplan's\n workstream as **sourced** (a matching file exists in that client's\n documents) or **missing**. Drives the Launcher's per-client readiness view.\n\n - `client_ids` (repeatable query param): the clients to resolve. When\n omitted, resolves the workplan's own bound client (if any).\n - `period` (optional query param, e.g. ``2025-01``): when supplied, each\n FILE input is ALSO resolved at level 2 (the client's period x slot file in\n ``platform.client_documents``) via ``ClientFileService.resolve_client_input``.\n A level-2 hit SUPERSEDES the level-3 conversation-discovery result\n (most-specific-wins, Ruling 1): a period-specific client document \u2192\n ``uploaded``, a standing document that carries forward \u2192 ``carried_forward``.\n When omitted (or no level-2 hit), behaviour is unchanged \u2014 level-3\n discovery stands. This is the readiness half of the AR-429 client-file-wins\n wire; the launch/run path is wired separately.\n\n **Authentication Required:** JWT Bearer token", "operationId": "resolve_workplan_inputs_api_v1_workstreams_workplans__blueprint_id__input_resolution_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "blueprint_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Blueprint Id" } }, { "name": "client_ids", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string", "format": "uuid" } }, { "type": "null" } ], "description": "Clients to resolve (repeatable). Defaults to the workplan's bound client.", "title": "Client Ids" }, "description": "Clients to resolve (repeatable). Defaults to the workplan's bound client." }, { "name": "period", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional period (e.g. 2025-01). When set, each FILE input is also resolved at level 2 (the client's period x slot file); a level-2 hit supersedes level-3 discovery (client file wins).", "title": "Period" }, "description": "Optional period (e.g. 2025-01). When set, each FILE input is also resolved at level 2 (the client's period x slot file); a level-2 hit supersedes level-3 discovery (client file wins)." } ], "responses": { "200": { "description": "Per-client input resolution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InputResolutionResponse" } } } }, "404": { "description": "Workplan not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/workplans/{blueprint_id}/roster": { "get": { "tags": [ "WorkStreams" ], "summary": "WorkPlan cohort roster (all clients, exceptions on top)", "description": "The all-clients cohort roster for a WorkPlan (S2-read \u00a72). One row per client\n in the bound cohort (explicit clients + the de-facto clients that have run\n cycles for this workstream), each carrying the derived cycle_status, input\n readiness (4-cat), alteration_count, and run-eligibility. Exceptions\n (required input missing / errored / blocked / awaiting-approval) sort to top.\n\n Workspace-scoped: only clients owned by the caller's workspace appear.\n\n **Authentication Required:** JWT Bearer token", "operationId": "get_workplan_roster_api_v1_workstreams_workplans__blueprint_id__roster_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "blueprint_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Blueprint Id" } }, { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Case-insensitive client-name substring filter", "title": "Q" }, "description": "Case-insensitive client-name substring filter" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "description": "exceptions_first | name | cycle_status | readiness", "default": "exceptions_first", "title": "Sort" }, "description": "exceptions_first | name | cycle_status | readiness" }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by derived cycle_status", "title": "Status" }, "description": "Filter by derived cycle_status" }, { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter to clients with >=1 FILE input in this source_category", "title": "Category" }, "description": "Filter to clients with >=1 FILE input in this source_category" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Page size", "default": 50, "title": "Limit" }, "description": "Page size" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Pagination offset", "default": 0, "title": "Offset" }, "description": "Pagination offset" } ], "responses": { "200": { "description": "Cohort roster", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkplanRoster" } } } }, "404": { "description": "Workplan not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/workplans/{blueprint_id}/triggers": { "get": { "tags": [ "WorkStreams" ], "summary": "List triggers for workplan", "description": "List all triggers configured for a workplan.\n\n **Authentication Required:** JWT Bearer token", "operationId": "list_triggers_api_v1_workstreams_workplans__blueprint_id__triggers_get", "parameters": [ { "name": "blueprint_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Blueprint Id" } } ], "responses": { "200": { "description": "Triggers retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerListResponse" } } } }, "404": { "description": "Workplan not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "WorkStreams" ], "summary": "Create trigger for workplan", "description": "Create a new trigger for a workplan.\n\n **Trigger Types:**\n - `time_based`: Schedule-based trigger using cron expression\n - `event_based`: Event-driven trigger\n - `manual`: Manual trigger only\n\n **Authentication Required:** JWT Bearer token", "operationId": "create_trigger_api_v1_workstreams_workplans__blueprint_id__triggers_post", "parameters": [ { "name": "blueprint_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Blueprint Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerCreate" } } } }, "responses": { "201": { "description": "Trigger created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerResponse" } } } }, "400": { "description": "Invalid trigger configuration" }, "404": { "description": "Workplan not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/workplans/{blueprint_id}/write-status": { "get": { "tags": [ "WorkStreams" ], "summary": "Get write mode status", "description": "Get the current write mode status for a workplan.\n\n Workplans are read-only by default. This endpoint returns:\n - Current write_enabled state\n - When writes were last enabled/disabled\n - Who enabled/disabled writes\n - Number of active cycles affected\n\n **Authentication Required:** JWT Bearer token", "operationId": "get_write_status_api_v1_workstreams_workplans__blueprint_id__write_status_get", "parameters": [ { "name": "blueprint_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Blueprint Id" } } ], "responses": { "200": { "description": "Write status retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WriteStatusResponse" } } } }, "404": { "description": "Workplan not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/workplans/{job_id}": { "patch": { "tags": [ "WorkStreams" ], "summary": "Update WorkPlan", "description": "Update a WorkPlan (job_definition) by ID or permakey. Canonical path is **PATCH /jobs/{job_id}** \u2014 this alias exists so callers that used POST /workplans for creation can mutate via the same prefix.", "operationId": "update_job_definition_api_v1_workstreams_workplans__job_id__patch", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobDefinitionUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobDefinitionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "WorkStreams" ], "summary": "Delete (archive) WorkPlan", "description": "Archive a WorkPlan (job_definition) by ID or permakey. Canonical path is **DELETE /jobs/{job_id}** \u2014 this alias keeps the /workplans prefix consistent with POST + PATCH.", "operationId": "delete_job_definition_api_v1_workstreams_workplans__job_id__delete", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/workplans/{job_id}/input-resolution": { "get": { "tags": [ "WorkStreams" ], "summary": "Resolve a job-backed workplan's inputs per client (sourced vs missing)", "description": "For each requested client, report every declared input of the workplan's\n workstream as **sourced** (a matching file exists in that client's\n documents or via override) or **missing**.\n\n If `client_ids` is empty, resolves the entire job cohort.", "operationId": "get_job_input_resolution_api_v1_workstreams_workplans__job_id__input_resolution_get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "client_ids", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string", "format": "uuid" } }, { "type": "null" } ], "description": "Clients to resolve (repeatable). Defaults to the entire job cohort.", "title": "Client Ids" }, "description": "Clients to resolve (repeatable). Defaults to the entire job cohort." } ], "responses": { "200": { "description": "Input resolution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InputResolutionResponse" } } } }, "404": { "description": "Workplan not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/workplans/{job_id}/next-runs": { "get": { "tags": [ "WorkStreams" ], "summary": "Preview the next N scheduled runs (holiday-adjusted)", "description": "Compute the next ``count`` cron fire times for a WorkPlan, shifted off\nweekends/holidays per the plan's ``skip_weekends`` / ``holiday_calendar``.\n\ncard #382e: pass ``?client_id=`` to preview that CLIENT's cadence when it has\na per-client ``schedule_override`` \u2014 the FE #802 ScheduleEditor renders a\nclient's own upcoming fires, not just the plan's. Without a matching\noverride the plan schedule is used (``schedule_source='plan'``).\n\nPure-functional (no DB writes); backed by\n``src.workstreams.schedule_utils.compute_next_n_run_at`` so the preview\nagrees with the dispatcher's actual fire times. Returns an empty ``runs``\nlist for an unscheduled (manual-only) WorkPlan.", "operationId": "preview_next_runs_api_v1_workstreams_workplans__job_id__next_runs_get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 20, "minimum": 1, "description": "Number of upcoming runs to preview.", "default": 5, "title": "Count" }, "description": "Number of upcoming runs to preview." }, { "name": "client_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Preview a specific client's OWN cadence. When the WorkPlan has a schedule_override for this client, the preview uses that override's cron/timezone/skip_weekends/holiday_calendar; otherwise it falls back to the plan schedule (schedule_source in the response says which).", "title": "Client Id" }, "description": "Preview a specific client's OWN cadence. When the WorkPlan has a schedule_override for this client, the preview uses that override's cron/timezone/skip_weekends/holiday_calendar; otherwise it falls back to the plan schedule (schedule_source in the response says which)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NextRunPreviewResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/workplans/{job_id}/roster": { "get": { "tags": [ "WorkStreams" ], "summary": "Get WorkPlan roster", "description": "All-clients cohort roster for a job_definition-backed WorkPlan.", "operationId": "get_job_roster_api_v1_workstreams_workplans__job_id__roster_get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Case-insensitive client-name substring filter", "title": "Q" }, "description": "Case-insensitive client-name substring filter" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "description": "exceptions_first | name | cycle_status | readiness", "default": "exceptions_first", "title": "Sort" }, "description": "exceptions_first | name | cycle_status | readiness" }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by derived cycle_status", "title": "Status" }, "description": "Filter by derived cycle_status" }, { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter to clients with >=1 FILE input in this source_category", "title": "Category" }, "description": "Filter to clients with >=1 FILE input in this source_category" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Page size", "default": 50, "title": "Limit" }, "description": "Page size" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Pagination offset", "default": 0, "title": "Offset" }, "description": "Pagination offset" } ], "responses": { "200": { "description": "Cohort roster", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkplanRoster" } } } }, "404": { "description": "WorkPlan not found" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/workstreams/{workstream_id}/triggers": { "post": { "tags": [ "WorkStreams" ], "summary": "Create workstream trigger", "description": "Create a webhook, schedule, or api trigger for a workstream.", "operationId": "create_workstream_trigger_api_v1_workstreams_workstreams__workstream_id__triggers_post", "parameters": [ { "name": "workstream_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Workstream Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkstreamTriggerCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Create Workstream Trigger Api V1 Workstreams Workstreams Workstream Id Triggers Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "WorkStreams" ], "summary": "List workstream triggers", "description": "List workstream-scoped triggers.", "operationId": "list_workstream_triggers_api_v1_workstreams_workstreams__workstream_id__triggers_get", "parameters": [ { "name": "workstream_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Workstream Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response List Workstream Triggers Api V1 Workstreams Workstreams Workstream Id Triggers Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/{blueprint_id}/run-batch": { "post": { "tags": [ "WorkStreams" ], "summary": "Run a WorkPlan as N cycles (concurrent fan-out)", "description": "Fan out a WorkPlan (blueprint) into N inline cycles concurrently.\n\n Powers the WorkPlans \"Run (xN)\" button. Each cycle is a real inline\n workstream cycle started on the playbooks task queue; creation runs\n concurrently over pooled connections (not serialised on one request\n connection), so 100-500 cycles spin up quickly. Cycles execute and\n drain asynchronously on the worker \u2014 poll the cycles list (filtered\n by the returned ``workstream_id``) to watch them complete.\n\n Inline workstreams only. Per-cycle start failures are reported in\n ``cycles`` (status=\"failed\") and never abort the rest of the batch.\n\n **Authentication Required:** JWT Bearer token", "operationId": "run_workplan_batch_api_v1_workstreams__blueprint_id__run_batch_post", "parameters": [ { "name": "blueprint_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Blueprint Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRunRequest" } } } }, "responses": { "202": { "description": "Batch accepted; per-cycle outcomes returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRunResponse" } } } }, "400": { "description": "WorkPlan (blueprint) not found or not active" }, "422": { "description": "Workstream is not inline-executable" }, "401": { "description": "Unauthorized" } } } }, "/api/v1/workstreams/{template_id}/adopt": { "post": { "tags": [ "WorkStreams" ], "summary": "Adopt upstream updates from parent playbook", "description": "Adopt the upstream updates from the parent playbook into this fork.\n\nThe steps and input/output schemas are overwritten with the parent's\nlatest versions. The fork's own metadata (name, description, status)\nand per-client alterations are preserved.", "operationId": "adopt_upstream_api_v1_workstreams__template_id__adopt_post", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Template Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workstreams/{workstream_id}/run-step": { "post": { "tags": [ "WorkStreams" ], "summary": "Run a single workstream step in isolation", "description": "Launch a synthetic single-step cycle for one step of a workstream.\n\n The endpoint materialises the workstream against the request's\n ``parameters`` (merged into runtime_vars), filters the snapshot to\n only the requested ``step_id``, then writes and starts an inline\n cycle the same way the regular cycle launch path does. Dependencies\n on other steps are stripped so the single step runs in isolation.\n\n Returns the new ``cycle_id`` and the synthesised ``task_id`` so the\n FE can navigate to ``?cycleId=`` and watch it run.\n\n **Authentication Required:** JWT Bearer token", "operationId": "run_workstream_step_api_v1_workstreams__workstream_id__run_step_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workstream_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Workstream Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunStepRequest" } } } }, "responses": { "201": { "description": "Single-step cycle started successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunStepResponse" } } } }, "404": { "description": "Workstream not found or not visible to caller" }, "422": { "description": "step_id not present in workstream steps" }, "401": { "description": "Unauthorized" } } } }, "/api/v1/workstreams/{workstream_id}/topics": { "get": { "tags": [ "WorkStreams" ], "summary": "List topics anchored to a workstream recipe", "description": "List the topics that use this workstream recipe.\n\n A topic \"uses\" a recipe when it is either:\n - directly anchored (``platform.topics.workstream_id = {workstream_id}``), or\n - its most recent execution cycle ran this recipe\n (``workstreams.cycle.workstream_id = {workstream_id}``).\n\n Each row carries the topic's latest cycle status as ``workstream_state``\n so the recipe-detail page can render a live badge. Returns an empty list\n (200) when no topic is anchored to the recipe \u2014 never 404.\n\n The ``workstream_id`` path segment accepts a UUID, a 7-char uppercase-alphanumeric\n permakey (e.g. ``D2PR8GF``), or a slug.\n\n **Authentication Required:** JWT Bearer token", "operationId": "list_topics_for_workstream_api_v1_workstreams__workstream_id__topics_get", "parameters": [ { "name": "workstream_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workstream Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 100, "title": "Limit" } } ], "responses": { "200": { "description": "Topics retrieved successfully (possibly empty)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeTopicListResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing JWT token" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/conversations": { "post": { "operationId": "createConversationTurn", "summary": "Send one turn of a conversation. Returns Archie's reply.", "tags": [ "conversations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationTurnRequest" } } } }, "responses": { "200": { "description": "Assistant reply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationTurnResponse" } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/skills": { "get": { "operationId": "listSkills", "summary": "List skills available to the caller's workspace", "tags": [ "catalogue" ], "responses": { "200": { "description": "Skill catalogue", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SkillCatalogEntry" } }, "total": { "type": "integer" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "sk_*", "description": "WorkOS-issued API key, prefixed `sk_`. Sandbox and live keys both use the same prefix. Mint, list, update, rotate, or revoke via `/api/v1/connect-keys` (see the **Connect Keys** section) or in the developers portal." } }, "schemas": { "AgentCycleCreate": { "properties": { "goal": { "type": "string", "title": "Goal", "description": "What the agent should accomplish" }, "domain": { "type": "string", "title": "Domain", "description": "Domain knowledge key (e.g. 'ita_2007_eis')" }, "client_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Client Id", "description": "Client UUID" }, "context": { "additionalProperties": true, "type": "object", "title": "Context", "description": "Client context data" }, "tools": { "items": { "type": "string" }, "type": "array", "title": "Tools", "description": "Tools the agent may use (empty = all available)" }, "deliverables": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Deliverables", "description": "Required deliverables [{name, type, description}]" }, "max_turns": { "type": "integer", "maximum": 500.0, "minimum": 1.0, "title": "Max Turns", "default": 150 }, "max_cost_usd": { "type": "number", "maximum": 50.0, "minimum": 0.1, "title": "Max Cost Usd", "default": 8.0 }, "max_duration_minutes": { "type": "integer", "maximum": 120.0, "minimum": 1.0, "title": "Max Duration Minutes", "default": 25 }, "source_tracing": { "type": "boolean", "title": "Source Tracing", "description": "Enable source tracing guardrail", "default": true } }, "type": "object", "required": [ "goal", "domain" ], "title": "AgentCycleCreate", "description": "Request to start an agentic cycle." }, "AgentCycleResponse": { "properties": { "cycle_id": { "type": "string", "title": "Cycle Id" }, "workflow_id": { "type": "string", "title": "Workflow Id" }, "status": { "type": "string", "title": "Status" } }, "type": "object", "required": [ "cycle_id", "workflow_id", "status" ], "title": "AgentCycleResponse", "description": "Response from starting an agentic cycle." }, "AgentRunStepDefinition": { "properties": { "id": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9_-]+$", "title": "Id" }, "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name" }, "type": { "type": "string", "const": "agent_run", "title": "Type", "default": "agent_run" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "depends_on": { "items": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" } ] }, "type": "array", "title": "Depends On" }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stage" }, "timeout": { "anyOf": [ { "type": "string", "pattern": "^\\d+[smhd]$" }, { "type": "null" } ], "title": "Timeout" }, "retry_policy": { "anyOf": [ { "$ref": "#/components/schemas/RetryPolicy" }, { "type": "null" } ] }, "error_handler": { "anyOf": [ { "$ref": "#/components/schemas/StepErrorHandler" }, { "type": "null" } ] }, "emit_artifact": { "anyOf": [ { "$ref": "#/components/schemas/EmitArtifactSpec" }, { "type": "null" } ] }, "optional": { "type": "boolean", "title": "Optional", "default": false }, "continue_on_error": { "type": "boolean", "title": "Continue On Error", "default": false }, "halt_conditions": { "items": { "$ref": "#/components/schemas/HaltCondition" }, "type": "array", "title": "Halt Conditions" }, "parameters": { "items": { "$ref": "#/components/schemas/StepParameter" }, "type": "array", "title": "Parameters" }, "guards": { "items": { "$ref": "#/components/schemas/StepGuard" }, "type": "array", "title": "Guards" }, "impact_level": { "$ref": "#/components/schemas/ImpactLevel", "default": "medium" }, "run_mode": { "$ref": "#/components/schemas/RunMode", "default": "propose" }, "requires_approval": { "type": "boolean", "title": "Requires Approval", "default": false }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "examples": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StepExample" }, "type": "array" }, { "type": "null" } ], "title": "Examples", "description": "Attached example files for this step. Each entry pairs a platform.file_uploads.file_id with a role + tags + notes so the runtime can shape its instruction. Bounded at 20 to keep a reasonable upper limit on the prompt preamble." }, "applies_when": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applies When", "description": "CEL predicate evaluated at MATERIALIZATION (not at step execution): the step is marked skipped when it evaluates False. Stored verbatim \u2014 the expression is parsed by celpy at launch, so any coercion here would change its meaning." }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "Categorical labels on the step itself (e.g. 'pdf-read', 'coutts', 'fy25'). Free-form; recommended tag set is documented per workstream surface." }, "goal": { "type": "string", "minLength": 1, "title": "Goal", "description": "Natural-language objective for the agentic loop (Jinja2-templated)." }, "domain": { "type": "string", "title": "Domain", "description": "Accounting/domain knowledge key carried into the agent executor.", "default": "" }, "client_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Id", "description": "Client identifier; may be a Jinja2 binding such as {{ inputs.client_id }}." }, "context": { "additionalProperties": true, "type": "object", "title": "Context", "description": "Typed WorkPlan/client context, recursively Jinja2-rendered at execution." }, "model_role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model Role", "description": "Logical runtime-model role (for example accounting_review), never a provider or concrete model id. Resolved by the central routing policy." }, "tools": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tools", "description": "Tool allowlist for the agent, passed to build_tool_router(allowed_tools=\u2026). None = all cycle tools." }, "deliverables": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Deliverables", "description": "Declared deliverables (name + type [+ description/schema]) the agent must produce." }, "max_turns": { "type": "integer", "maximum": 500.0, "minimum": 1.0, "title": "Max Turns", "description": "Tool-loop turn cap \u2014 the in-step interruptibility bound.", "default": 50 }, "max_cost_usd": { "type": "number", "exclusiveMinimum": 0.0, "title": "Max Cost Usd", "description": "Cost budget cap in USD.", "default": 10.0 }, "max_duration_minutes": { "type": "integer", "maximum": 240.0, "minimum": 1.0, "title": "Max Duration Minutes", "description": "Wall-clock cap in minutes.", "default": 30 }, "source_tracing": { "type": "boolean", "title": "Source Tracing", "description": "Require the agent loop's outputs to retain source tracing.", "default": true }, "human_checkpoints": { "items": { "type": "string" }, "type": "array", "title": "Human Checkpoints", "description": "Named checkpoints enforced by the agent guardrail contract." }, "inputs": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Inputs", "description": "Optional Jinja2 input bindings ({{ inputs.* }} / {{ outputs.* }})." }, "expected_outputs": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Expected Outputs", "description": "Output schema hints for DAG threading (name + type per entry)." } }, "additionalProperties": false, "type": "object", "required": [ "id", "name", "goal" ], "title": "AgentRunStepDefinition", "description": "Agent-run step \u2014 runs the FULL agentic loop (``WorkstreamV4Executor``) as\none node in the declarative WDL step-DAG (\"Autopilot\").\n\nDistinct from ``archie_query`` (a single orchestrator query that bypasses the\nverifier): an ``agent_run`` step works MULTI-TURN with a tool allowlist +\ndeclared deliverables until it is done or a budget cap is hit. Runs\n``RunMode.AUTO_RUN`` by default (no per-step approval); interruptible via the\ncycle's pause/resume/cancel signals BETWEEN steps + the budget caps WITHIN\nthe step (the workflow cannot pause mid-activity). The DB ``step_kind`` enum\nalready carries ``agent_run`` (migration 20260601_0220)." }, "AlterationCountResponse": { "properties": { "alteration_count": { "type": "integer", "title": "Alteration Count" } }, "type": "object", "required": [ "alteration_count" ], "title": "AlterationCountResponse" }, "AlterationPutRequest": { "properties": { "patches": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Patches" }, "applies_to_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applies To Version" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Note" } }, "type": "object", "title": "AlterationPutRequest", "description": "PUT \u2026/alterations \u2014 replace the whole patch set (S3 \u00a73a)." }, "AlterationStep": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "requires_approval": { "type": "boolean", "title": "Requires Approval", "default": false }, "instruction": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instruction" }, "tool_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tool Name" }, "alterable": { "items": { "type": "string" }, "type": "array", "title": "Alterable" }, "settable_parameters": { "items": { "type": "string" }, "type": "array", "title": "Settable Parameters" }, "settable_parameter_specs": { "items": { "$ref": "#/components/schemas/SettableParameterSpec" }, "type": "array", "title": "Settable Parameter Specs" }, "alterations": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Alterations" } }, "type": "object", "required": [ "id" ], "title": "AlterationStep" }, "ApprovalAction": { "type": "string", "enum": [ "approve", "hold", "reject" ], "title": "ApprovalAction", "description": "Approval actions \u2014 three outcomes, not two.\n\n``HOLD`` was added 2026-08-19. A partner who cannot sign off YET, because a\nclient question is unanswered, previously had to press Reject; the engine\ntreated that as terminal and recorded the whole run as ``failed``. Waiting\nis not failing, so the two are now separate verbs:\n\n* ``APPROVE`` \u2014 the run continues and external writes are authorised;\n* ``HOLD`` \u2014 the run stays parked, nothing is written, nobody is blamed,\n and the SAME cycle is signed off later (it is never restarted);\n* ``REJECT`` \u2014 the work is wrong. Terminal, red, dependents gated. Exactly\n today's behaviour, deliberately unchanged.\n\n``HOLD`` is NOT in ``approval_barrier.APPROVAL_POSITIVE_DECISIONS``, so it\nstays \"not approved\" to every external-write barrier." }, "ApprovalEscalation": { "properties": { "after": { "type": "string", "pattern": "^\\d+[smhd]$", "title": "After" }, "notify": { "items": { "type": "string" }, "type": "array", "title": "Notify" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message" } }, "additionalProperties": false, "type": "object", "required": [ "after" ], "title": "ApprovalEscalation", "description": "Escalation configuration for approval step." }, "ApprovalRequestModel": { "properties": { "comments": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ], "title": "Comments", "description": "Approval comments or notes" }, "modified_plan": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Modified Plan", "description": "Optional modifications to the execution plan" } }, "type": "object", "title": "ApprovalRequestModel", "description": "Request model for task approval with enhanced metadata.", "example": { "comments": "Verified reconciliation parameters look correct. Proceed with execution." } }, "ApprovalResponseModel": { "properties": { "task_id": { "type": "string", "format": "uuid", "title": "Task Id", "description": "Task UUID" }, "cycle_id": { "type": "string", "format": "uuid", "title": "Cycle Id", "description": "Cycle UUID" }, "status": { "$ref": "#/components/schemas/TaskStatus", "description": "New task status after approval/rejection" }, "approved_by": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Approved By", "description": "User who approved the task" }, "approved_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Approved At", "description": "Approval timestamp" }, "rejected_by": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Rejected By", "description": "User who rejected the task" }, "rejected_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Rejected At", "description": "Rejection timestamp" }, "rejection_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rejection Reason", "description": "Rejection reason if rejected" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata", "description": "Additional approval metadata" }, "workflow_signaled": { "type": "boolean", "title": "Workflow Signaled", "description": "Whether the Temporal gate transport completed (Update for inline cycles)", "default": false } }, "type": "object", "required": [ "task_id", "cycle_id", "status" ], "title": "ApprovalResponseModel", "description": "Response model for approval/rejection operations.", "example": { "approved_at": "2025-01-13T10:30:00Z", "approved_by": "user_01JAZZKGWFWTWZMDCZGE24VFC1", "cycle_id": "aa0e8400-e29b-41d4-a716-446655440000", "metadata": { "comments": "Approved after review" }, "status": "approved", "task_id": "990e8400-e29b-41d4-a716-446655440000", "workflow_signaled": true } }, "ApprovalStepDefinition": { "properties": { "id": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9_-]+$", "title": "Id" }, "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name" }, "type": { "type": "string", "const": "approval", "title": "Type", "default": "approval" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "depends_on": { "items": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" } ] }, "type": "array", "title": "Depends On" }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stage" }, "timeout": { "type": "string", "pattern": "^\\d+[smhd]$", "title": "Timeout", "default": "7d" }, "retry_policy": { "anyOf": [ { "$ref": "#/components/schemas/RetryPolicy" }, { "type": "null" } ] }, "error_handler": { "anyOf": [ { "$ref": "#/components/schemas/StepErrorHandler" }, { "type": "null" } ] }, "emit_artifact": { "anyOf": [ { "$ref": "#/components/schemas/EmitArtifactSpec" }, { "type": "null" } ] }, "optional": { "type": "boolean", "title": "Optional", "default": false }, "continue_on_error": { "type": "boolean", "title": "Continue On Error", "default": false }, "halt_conditions": { "items": { "$ref": "#/components/schemas/HaltCondition" }, "type": "array", "title": "Halt Conditions" }, "parameters": { "items": { "$ref": "#/components/schemas/StepParameter" }, "type": "array", "title": "Parameters" }, "guards": { "items": { "$ref": "#/components/schemas/StepGuard" }, "type": "array", "title": "Guards" }, "impact_level": { "$ref": "#/components/schemas/ImpactLevel", "default": "medium" }, "run_mode": { "$ref": "#/components/schemas/RunMode", "default": "propose" }, "requires_approval": { "type": "boolean", "title": "Requires Approval", "default": false }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "examples": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StepExample" }, "type": "array" }, { "type": "null" } ], "title": "Examples", "description": "Attached example files for this step. Each entry pairs a platform.file_uploads.file_id with a role + tags + notes so the runtime can shape its instruction. Bounded at 20 to keep a reasonable upper limit on the prompt preamble." }, "applies_when": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applies When", "description": "CEL predicate evaluated at MATERIALIZATION (not at step execution): the step is marked skipped when it evaluates False. Stored verbatim \u2014 the expression is parsed by celpy at launch, so any coercion here would change its meaning." }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "Categorical labels on the step itself (e.g. 'pdf-read', 'coutts', 'fy25'). Free-form; recommended tag set is documented per workstream surface." }, "instruction": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instruction", "description": "Natural-language gate prompt the runtime renders for the approver. Used in place of summary/actions for instruction-driven gates." }, "summary": { "anyOf": [ { "$ref": "#/components/schemas/ApprovalSummary" }, { "type": "null" } ] }, "actions": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/WdlApprovalAction" }, "type": "object" }, { "type": "null" } ], "title": "Actions" }, "escalation": { "anyOf": [ { "$ref": "#/components/schemas/ApprovalEscalation" }, { "type": "null" } ] }, "auto_approve": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Auto Approve" } }, "additionalProperties": false, "type": "object", "required": [ "id", "name" ], "title": "ApprovalStepDefinition", "description": "Approval step - pauses for human approval.\n\nStuart 2026-06-25: the V4 executor renders the approval gate from\n``step.get(\"instruction\")`` (inline_cycle_workflow.py \u2014 the DAG task\ndescription and the step ``query``), NOT from ``summary``/``actions``.\nThe stored shape for seeded approval gates (e.g. FIC WS3) therefore\ncarries ``instruction`` and omits ``summary``/``actions``, which the\nstrict write-model rejected (``instruction`` forbidden by\n``extra='forbid'``; ``summary``/``actions`` required). Accept\n``instruction`` and make ``summary``/``actions`` optional so the\nPATCH round-trip works for both styles. Templates that legitimately\nauthor rich ``summary``/``actions`` gates keep validating unchanged." }, "ApprovalStepResponse": { "properties": { "task_id": { "type": "string", "format": "uuid", "title": "Task Id" }, "step_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Step Id" }, "name": { "type": "string", "title": "Name" }, "type": { "type": "string", "title": "Type" }, "status": { "$ref": "#/components/schemas/TaskStatus" }, "sequence_order": { "type": "integer", "title": "Sequence Order" }, "requires_approval": { "type": "boolean", "title": "Requires Approval" }, "approved_by": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Approved By" }, "approved_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Approved At" }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Started At" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Completed At" } }, "type": "object", "required": [ "task_id", "name", "type", "status", "sequence_order", "requires_approval" ], "title": "ApiRoutersWorkstreamsModels__ApprovalStepResponse", "description": "Projected view of a task that is an approval/sign-off gate.\n\nDerived from tasks where requires_approval=True or status=awaiting_approval.\nSurfaced as a top-level array on CycleWithTasksResponse so the FE can render\napproval gate markers without filtering the full tasks list." }, "ApprovalSummary": { "properties": { "title": { "type": "string", "title": "Title" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "display": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Display" } }, "additionalProperties": false, "type": "object", "required": [ "title" ], "title": "ApprovalSummary", "description": "Summary information for approval step." }, "ApproveBulkRequestModel": { "properties": { "pairs": { "items": { "$ref": "#/components/schemas/CycleTaskPair" }, "type": "array", "maxItems": 500, "minItems": 1, "title": "Pairs", "description": "The (cycle, task) instances to resolve" }, "decision": { "type": "string", "enum": [ "approve", "reject" ], "title": "Decision", "description": "Decision applied to every pair", "default": "approve" }, "comments": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ], "title": "Comments", "description": "Optional note recorded on every resolution" } }, "type": "object", "required": [ "pairs" ], "title": "ApproveBulkRequestModel", "description": "Approve or reject N awaiting-approval task instances in one call.\n\nUsed by the wave-triage 'approve all N' button: each instance is a cycle\npaused at an approval gate; the same decision is fanned to every pair. The\nbatch is fail-soft \u2014 a bad/already-resolved pair returns an error result\nwithout failing the rest." }, "ApproveBulkResponseModel": { "properties": { "results": { "items": { "$ref": "#/components/schemas/BulkApprovalResult" }, "type": "array", "title": "Results", "description": "One result per requested pair, in order" }, "approved_count": { "type": "integer", "minimum": 0.0, "title": "Approved Count", "default": 0 }, "rejected_count": { "type": "integer", "minimum": 0.0, "title": "Rejected Count", "default": 0 }, "error_count": { "type": "integer", "minimum": 0.0, "title": "Error Count", "default": 0 } }, "type": "object", "required": [ "results" ], "title": "ApproveBulkResponseModel", "description": "Result of a bulk approval \u2014 per-pair results + roll-up counts." }, "ApproveGateRequestModel": { "properties": { "decision": { "type": "string", "enum": [ "approve", "reject" ], "title": "Decision", "description": "Decision applied to every discovered gate", "default": "approve" }, "comments": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ], "title": "Comments", "description": "Optional note recorded on every resolution" } }, "type": "object", "title": "ApproveGateRequestModel", "description": "Resolve EVERY awaiting-approval gate in a cohort (job) in one call.\n\nThe 'Approve all at the gate' affordance for the WS/WP swarm matrix: instead of\nthe FE hand-building the (cycle, task) pairs, the server auto-discovers every\ncohort cycle currently parked at an approval gate and fans the same decision\nacross them via the bulk fail-soft + Temporal-Update path. Selective approve\nstays on ``POST /cycles/approve-bulk`` with explicit pairs." }, "ApproveGateResponseModel": { "properties": { "job_definition_id": { "type": "string", "format": "uuid", "title": "Job Definition Id", "description": "The cohort whose gates were swept" }, "discovered": { "type": "integer", "minimum": 0.0, "title": "Discovered", "description": "Awaiting-approval gates found in the cohort", "default": 0 }, "results": { "items": { "$ref": "#/components/schemas/BulkApprovalResult" }, "type": "array", "title": "Results", "description": "One result per discovered gate" }, "approved_count": { "type": "integer", "minimum": 0.0, "title": "Approved Count", "default": 0 }, "rejected_count": { "type": "integer", "minimum": 0.0, "title": "Rejected Count", "default": 0 }, "error_count": { "type": "integer", "minimum": 0.0, "title": "Error Count", "default": 0 } }, "type": "object", "required": [ "job_definition_id" ], "title": "ApproveGateResponseModel", "description": "Result of a cohort gate sweep \u2014 what was discovered + the per-pair outcomes." }, "ArchieQueryStepDefinition": { "properties": { "id": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9_-]+$", "title": "Id" }, "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name" }, "type": { "type": "string", "const": "archie_query", "title": "Type", "default": "archie_query" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "depends_on": { "items": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" } ] }, "type": "array", "title": "Depends On" }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stage" }, "timeout": { "anyOf": [ { "type": "string", "pattern": "^\\d+[smhd]$" }, { "type": "null" } ], "title": "Timeout" }, "retry_policy": { "anyOf": [ { "$ref": "#/components/schemas/RetryPolicy" }, { "type": "null" } ] }, "error_handler": { "anyOf": [ { "$ref": "#/components/schemas/StepErrorHandler" }, { "type": "null" } ] }, "emit_artifact": { "anyOf": [ { "$ref": "#/components/schemas/EmitArtifactSpec" }, { "type": "null" } ] }, "optional": { "type": "boolean", "title": "Optional", "default": false }, "continue_on_error": { "type": "boolean", "title": "Continue On Error", "default": false }, "halt_conditions": { "items": { "$ref": "#/components/schemas/HaltCondition" }, "type": "array", "title": "Halt Conditions" }, "parameters": { "items": { "$ref": "#/components/schemas/StepParameter" }, "type": "array", "title": "Parameters" }, "guards": { "items": { "$ref": "#/components/schemas/StepGuard" }, "type": "array", "title": "Guards" }, "impact_level": { "$ref": "#/components/schemas/ImpactLevel", "default": "medium" }, "run_mode": { "$ref": "#/components/schemas/RunMode", "default": "propose" }, "requires_approval": { "type": "boolean", "title": "Requires Approval", "default": false }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "examples": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StepExample" }, "type": "array" }, { "type": "null" } ], "title": "Examples", "description": "Attached example files for this step. Each entry pairs a platform.file_uploads.file_id with a role + tags + notes so the runtime can shape its instruction. Bounded at 20 to keep a reasonable upper limit on the prompt preamble." }, "applies_when": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applies When", "description": "CEL predicate evaluated at MATERIALIZATION (not at step execution): the step is marked skipped when it evaluates False. Stored verbatim \u2014 the expression is parsed by celpy at launch, so any coercion here would change its meaning." }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "Categorical labels on the step itself (e.g. 'pdf-read', 'coutts', 'fy25'). Free-form; recommended tag set is documented per workstream surface." }, "instruction": { "type": "string", "minLength": 1, "title": "Instruction", "description": "Natural-language query the runtime sends to the chat orchestrator." }, "inputs": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Inputs", "description": "Optional Jinja2 input bindings ({{ inputs.* }} / {{ outputs.* }})." }, "expected_outputs": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Expected Outputs", "description": "Output schema hints (name + type per entry)." }, "skill_slugs": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Skill Slugs", "description": "Skills that should be available to the chat orchestrator for this query." }, "confidence_threshold": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Confidence Threshold", "description": "Minimum confidence the runtime should treat as acceptable before auto-continuing (drives confidence-gated review)." }, "tool_hints": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tool Hints", "description": "V4 tool slugs to bias the orchestrator toward (e.g. 'read_pdf_document')." }, "model_role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model Role", "description": "A LOGICAL ROLE from llm/routing/policy_seed.json \u2014 e.g. 'accounting_review' \u2014 never a model id. The seed binds the role to a ModelType and ModelType absorbs version churn, so promoting a model is one line in the seed rather than an edit to every workstream. This is the only way an archie_query step can request the accounting fine-tune; naming the step after a model routes nothing." }, "deterministic": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Deterministic", "description": "When true, run this step's specialist call at temperature=0 with extended thinking disabled so the same input is extracted identically every run. For structured-extraction steps only." } }, "additionalProperties": false, "type": "object", "required": [ "id", "name", "instruction" ], "title": "ArchieQueryStepDefinition", "description": "Archie-query step \u2014 runs a natural-language query through the V4\nchat orchestrator and threads its answer into the workstream.\n\nStuart 2026-05-19: 48 templates on dev use ``type='archie_query'``\ntoday (most-common step type in the DB) but the write-side schema\nrejected it as 422. Adding the model unblocks PATCH for every\nworkstream that mixes archie_query with other types \u2014 the read\nshape stored in JSONB is already what the V4 chat-orch executor\nconsumes via ``step.get(\"instruction\") / step.get(\"expected_outputs\")``." }, "ArtifactSummaryResponse": { "properties": { "total_count": { "type": "integer", "title": "Total Count", "default": 0 }, "total_size_bytes": { "type": "integer", "title": "Total Size Bytes", "default": 0 }, "total_size_human": { "type": "string", "title": "Total Size Human", "default": "0 B" }, "by_type": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "By Type" }, "by_source": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "By Source" }, "by_step": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "By Step" } }, "type": "object", "title": "ArtifactSummaryResponse", "description": "Summary statistics for artifacts in a cycle." }, "AutonomyConfig": { "properties": { "confidence_band": { "anyOf": [ { "type": "string", "enum": [ "high", "medium", "low" ] }, { "type": "null" } ], "title": "Confidence Band", "description": "Minimum confidence level Archie must reach before auto-executing. high = very conservative (rarely auto); low = permissive." }, "auto_approve_under_usd": { "anyOf": [ { "type": "number", "minimum": 0.0 }, { "type": "null" } ], "title": "Auto Approve Under Usd", "description": "Auto-approve any single action whose estimated cost is below this USD amount." }, "per_integration_limits": { "anyOf": [ { "additionalProperties": { "type": "integer" }, "type": "object" }, { "type": "null" } ], "title": "Per Integration Limits", "description": "Per-integration action caps per cycle. Key = integration slug (e.g. 'xero', 'sage'), value = max auto-approved actions." } }, "type": "object", "title": "AutonomyConfig", "description": "Stored in ``default_context.autonomy_config``. Controls how much Archie\ncan decide autonomously before surfacing a proposal to the user.\nAll fields are optional \u2014 unset means \"no limit / no preference\"." }, "BackoffStrategy": { "type": "string", "enum": [ "constant", "linear", "exponential" ], "title": "BackoffStrategy", "description": "Retry backoff strategies." }, "BatchRunRequest": { "properties": { "count": { "anyOf": [ { "type": "integer", "maximum": 500.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Count", "description": "Launch N identical cycles from the WorkPlan" }, "client_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array", "maxItems": 500 }, { "type": "null" } ], "title": "Client Ids", "description": "One cycle per client (overrides count); capped at 500" }, "all_clients": { "type": "boolean", "title": "All Clients", "description": "Fan one cycle across every active client in the workspace (overrides count)", "default": false }, "input_data": { "additionalProperties": true, "type": "object", "title": "Input Data", "description": "Shared runtime inputs (e.g. period, label)" }, "topic_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Topic Id", "description": "Bind all batch cycles to this topic. When set every cycle is created with topic_id so it emits live events to the topic channel and appears on the topic canvas (thinking, steps, artifacts). NULL cycles are invisible to the topic canvas even though they execute normally." } }, "type": "object", "title": "ApiRoutersWorkstreamsModels__BatchRunRequest", "description": "Request to fan out N cycles from a WorkPlan (blueprint).", "example": { "count": 100, "input_data": { "label": "load-test" } } }, "BatchRunResponse": { "properties": { "workstream_id": { "type": "string", "format": "uuid", "title": "Workstream Id" }, "job_definition_id": { "type": "string", "format": "uuid", "title": "Job Definition Id" }, "job_permakey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Job Permakey", "description": "Job (WorkPlan) permakey \u2014 the PLAN's stable reference. NOT the cycle address: a plan permakey in the cycle slot is the bug this card closes. Kept for the workplan deep-link / fleet grouping only." }, "cycle_launch_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Cycle Launch Id", "description": "The cycle_launch (the product's Cycle - one launch of a plan) this batch minted. The launch's OWN permakey (cycle_launch_permakey) is the canonical cycle address the launcher navigates to (/workstreams/{ws}/cycles/{launch_permakey}) \u2014 card 'Every link the app emits uses the cycle's own address'. Null only on a defensive no-mint path (the mint is the first write, so a real run has it)." }, "cycle_launch_permakey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cycle Launch Permakey", "description": "The cycle_launch's stable permakey \u2014 the canonical CYCLE address. The post-create navigation lands here DIRECTLY (no redirect): /workstreams/{ws}/cycles/{cycle_launch_permakey}. Null only on a defensive no-mint path; the launcher falls back to job_permakey (which the flat cycle-slot resolver redirects to the workplan) so a legacy/edge row never dead-ends." }, "requested": { "type": "integer", "title": "Requested" }, "started": { "type": "integer", "title": "Started" }, "failed": { "type": "integer", "title": "Failed" }, "cycles": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Cycles", "description": "Per-cycle outcomes: [{cycle_id, client_id, workflow_id, status, error?}]" } }, "type": "object", "required": [ "workstream_id", "job_definition_id", "requested", "started", "failed" ], "title": "BatchRunResponse", "description": "Result of a WorkPlan batch fan-out (cycles execute asynchronously)." }, "BranchAction": { "properties": { "goto": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Goto", "description": "Target step ID" }, "steps": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Steps", "description": "Inline steps to execute" }, "skip": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Skip", "description": "Skip to next step" }, "fail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fail", "description": "Fail with message" } }, "additionalProperties": false, "type": "object", "title": "BranchAction", "description": "Action for conditional branches." }, "BulkApprovalResult": { "properties": { "cycle_id": { "type": "string", "title": "Cycle Id", "description": "Cycle reference as supplied" }, "task_id": { "type": "string", "title": "Task Id", "description": "Task reference as supplied" }, "status": { "type": "string", "enum": [ "approved", "rejected", "error" ], "title": "Status", "description": "Per-pair outcome" }, "workflow_signaled": { "type": "boolean", "title": "Workflow Signaled", "description": "Whether the task-scoped Temporal Workflow Update completed", "default": false }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Failure reason when status='error'" } }, "type": "object", "required": [ "cycle_id", "task_id", "status" ], "title": "BulkApprovalResult", "description": "Per-pair outcome \u2014 the batch is fail-soft." }, "CategoryRollup": { "properties": { "carried_forward": { "type": "integer", "title": "Carried Forward", "default": 0 }, "synced": { "type": "integer", "title": "Synced", "default": 0 }, "uploaded": { "type": "integer", "title": "Uploaded", "default": 0 }, "missing": { "type": "integer", "title": "Missing", "default": 0 } }, "type": "object", "title": "CategoryRollup", "description": "Per-client count of FILE inputs by source_category (S2-read \u00a73)." }, "ChatMessage": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "user", "assistant", "system" ] }, "content": { "type": "string" } } }, "Citation": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "source": { "type": "string" }, "snippet": { "type": "string" } } }, "ClientAlterationPage": { "properties": { "blueprint_id": { "type": "string", "title": "Blueprint Id" }, "workstream_id": { "type": "string", "title": "Workstream Id" }, "workstream_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workstream Version" }, "client_id": { "type": "string", "title": "Client Id" }, "client_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Name" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "applies_to_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applies To Version" }, "shared_with_plans": { "items": { "$ref": "#/components/schemas/SharedPlan" }, "type": "array", "title": "Shared With Plans" }, "alteration_count": { "type": "integer", "title": "Alteration Count", "default": 0 }, "inert_alteration_count": { "type": "integer", "title": "Inert Alteration Count", "default": 0 }, "unattached_alterations": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Unattached Alterations" }, "steps": { "items": { "$ref": "#/components/schemas/AlterationStep" }, "type": "array", "title": "Steps" }, "run_wide_alterations": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Run Wide Alterations" } }, "type": "object", "required": [ "blueprint_id", "workstream_id", "client_id" ], "title": "ClientAlterationPage", "description": "GET \u2026/alterations \u2014 base steps + active alterations overlaid (S3 \u00a72)." }, "ClientInputResolution": { "properties": { "client_id": { "type": "string", "title": "Client Id" }, "client_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Name" }, "resolved_period": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resolved Period" }, "params": { "items": { "$ref": "#/components/schemas/ParamResolution" }, "type": "array", "title": "Params" }, "by_category": { "$ref": "#/components/schemas/CategoryRollup" }, "required_missing": { "type": "integer", "title": "Required Missing", "default": 0 }, "files_sourced": { "type": "integer", "title": "Files Sourced" }, "files_missing": { "type": "integer", "title": "Files Missing" }, "ready": { "type": "boolean", "title": "Ready" } }, "type": "object", "required": [ "client_id", "params", "files_sourced", "files_missing", "ready" ], "title": "ClientInputResolution", "description": "Per-client readiness: which inputs are sourced from that client's docs." }, "CompleteUploadResponse": { "properties": { "task_id": { "type": "string", "format": "uuid", "title": "Task Id" }, "cycle_id": { "type": "string", "format": "uuid", "title": "Cycle Id" }, "status": { "type": "string", "title": "Status" }, "file_count": { "type": "integer", "title": "File Count" }, "workflow_signaled": { "type": "boolean", "title": "Workflow Signaled" } }, "type": "object", "required": [ "task_id", "cycle_id", "status", "file_count", "workflow_signaled" ], "title": "CompleteUploadResponse", "description": "Response after completing document upload." }, "ConditionalStepDefinition": { "properties": { "id": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9_-]+$", "title": "Id" }, "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name" }, "type": { "type": "string", "const": "conditional", "title": "Type", "default": "conditional" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "depends_on": { "items": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" } ] }, "type": "array", "title": "Depends On" }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stage" }, "timeout": { "anyOf": [ { "type": "string", "pattern": "^\\d+[smhd]$" }, { "type": "null" } ], "title": "Timeout" }, "retry_policy": { "anyOf": [ { "$ref": "#/components/schemas/RetryPolicy" }, { "type": "null" } ] }, "error_handler": { "anyOf": [ { "$ref": "#/components/schemas/StepErrorHandler" }, { "type": "null" } ] }, "emit_artifact": { "anyOf": [ { "$ref": "#/components/schemas/EmitArtifactSpec" }, { "type": "null" } ] }, "optional": { "type": "boolean", "title": "Optional", "default": false }, "continue_on_error": { "type": "boolean", "title": "Continue On Error", "default": false }, "halt_conditions": { "items": { "$ref": "#/components/schemas/HaltCondition" }, "type": "array", "title": "Halt Conditions" }, "parameters": { "items": { "$ref": "#/components/schemas/StepParameter" }, "type": "array", "title": "Parameters" }, "guards": { "items": { "$ref": "#/components/schemas/StepGuard" }, "type": "array", "title": "Guards" }, "impact_level": { "$ref": "#/components/schemas/ImpactLevel", "default": "medium" }, "run_mode": { "$ref": "#/components/schemas/RunMode", "default": "propose" }, "requires_approval": { "type": "boolean", "title": "Requires Approval", "default": false }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "examples": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StepExample" }, "type": "array" }, { "type": "null" } ], "title": "Examples", "description": "Attached example files for this step. Each entry pairs a platform.file_uploads.file_id with a role + tags + notes so the runtime can shape its instruction. Bounded at 20 to keep a reasonable upper limit on the prompt preamble." }, "applies_when": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applies When", "description": "CEL predicate evaluated at MATERIALIZATION (not at step execution): the step is marked skipped when it evaluates False. Stored verbatim \u2014 the expression is parsed by celpy at launch, so any coercion here would change its meaning." }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "Categorical labels on the step itself (e.g. 'pdf-read', 'coutts', 'fy25'). Free-form; recommended tag set is documented per workstream surface." }, "condition": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Condition", "description": "Condition expression for if/else" }, "switch": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Switch", "description": "Switch expression for switch/case" }, "then": { "anyOf": [ { "$ref": "#/components/schemas/BranchAction" }, { "type": "null" } ] }, "else": { "anyOf": [ { "$ref": "#/components/schemas/BranchAction" }, { "type": "null" } ] }, "cases": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/BranchAction" }, "type": "object" }, { "type": "null" } ], "title": "Cases" }, "default": { "anyOf": [ { "$ref": "#/components/schemas/BranchAction" }, { "type": "null" } ] } }, "additionalProperties": false, "type": "object", "required": [ "id", "name" ], "title": "ConditionalStepDefinition", "description": "Conditional step - branches based on condition." }, "ConversationTurnRequest": { "type": "object", "description": "Provide either `messages` (full chat history, OpenAI shape) or the `message` shorthand for single-turn calls.", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessage" } }, "message": { "type": "string", "description": "Shorthand for `messages: [{role: 'user', content: ...}]`." }, "conversation_id": { "type": "string", "description": "Echo back the id from a prior reply to thread turns." }, "client_id": { "type": "string", "description": "Optional client/workspace identifier for scoped answers." }, "locale": { "type": "string", "default": "en-AU" }, "jurisdiction": { "type": "string", "default": "AU" } } }, "ConversationTurnResponse": { "type": "object", "required": [ "object", "conversation_id", "skill", "message" ], "properties": { "object": { "type": "string", "example": "conversation.turn" }, "conversation_id": { "type": "string" }, "skill": { "type": "string", "example": "ask_archie" }, "correlation_id": { "type": "string", "nullable": true }, "message": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string", "example": "assistant" }, "content": { "type": "string" }, "citations": { "type": "array", "items": { "$ref": "#/components/schemas/Citation" } } } } } }, "Cycle": { "type": "object", "description": "One execution of a Workplan. NEVER called a 'run' \u2014 workstream executions are Cycles (Stuart 2026-05-08).", "properties": { "id": { "type": "string" }, "blueprint_id": { "type": "string", "description": "Parent Workplan id. Field name kept as `blueprint_id` (deprecated alias) for back-compat." }, "status": { "type": "string", "enum": [ "pending", "running", "paused", "awaiting_approval", "completed", "failed", "cancelled" ] }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "current_task_id": { "type": "string", "nullable": true }, "progress_pct": { "type": "number" }, "inputs": { "type": "object" }, "outputs": { "type": "object", "nullable": true } } }, "CycleArtifactListResponse": { "properties": { "artifacts": { "items": { "$ref": "#/components/schemas/CycleArtifactResponse" }, "type": "array", "title": "Artifacts" }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "summary": { "$ref": "#/components/schemas/ArtifactSummaryResponse" } }, "type": "object", "required": [ "pagination" ], "title": "CycleArtifactListResponse", "description": "List response for cycle artifacts." }, "CycleArtifactResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Artifact UUID" }, "cycle_id": { "type": "string", "format": "uuid", "title": "Cycle Id", "description": "Parent cycle UUID" }, "task_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Task Id", "description": "Task that created this artifact" }, "step_id": { "type": "string", "title": "Step Id", "description": "WDL step identifier" }, "name": { "type": "string", "title": "Name", "description": "Artifact name" }, "artifact_type": { "type": "string", "title": "Artifact Type", "description": "Artifact type classification" }, "source_system": { "type": "string", "title": "Source System", "description": "Source system that produced the artifact" }, "content_type": { "type": "string", "title": "Content Type", "description": "MIME type" }, "size_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Size Bytes", "description": "Size in bytes. None for metadata-embedded artifacts with no stored blob (storage_path NULL), e.g. the FIC classification audit trail." }, "checksum": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Checksum", "description": "SHA-256 checksum" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Display Name", "description": "Human-friendly display name" }, "file_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Name", "description": "Original filename" }, "preview": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Preview", "description": "First 500 chars preview" }, "tool_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tool Name", "description": "Tool that created this artifact" }, "created_at": { "type": "string", "title": "Created At", "description": "Creation timestamp" }, "size_human": { "type": "string", "title": "Size Human", "description": "Human-readable size", "default": "" }, "download_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Download Url", "description": "Download URL" }, "file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Id", "description": "Launch-usable file reference (a platform.file_uploads id). Present when this artifact is a stored document; None for non-document artifacts. Pass straight into a cycle launch as input_data[] = file_id to bind a prior run's output as a file input. See _artifact_refs.extract_artifact_file_id." } }, "type": "object", "required": [ "id", "cycle_id", "step_id", "name", "artifact_type", "source_system", "content_type", "created_at" ], "title": "CycleArtifactResponse", "description": "Response schema for a cycle artifact." }, "CycleArtifactSummary": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Artifact UUID" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Human display name of the artifact" }, "file_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Name", "description": "Original file name, if any" }, "artifact_type": { "type": "string", "title": "Artifact Type", "description": "Artifact type (e.g. generated_doc)" }, "size_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Size Bytes", "description": "Size in bytes, if known" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "When the artifact was produced" }, "download_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Download Url", "description": "Absolute, tokenized download URL for the artifact content." }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At", "description": "When the download URL token expires (7 days from minting)" } }, "type": "object", "required": [ "id", "artifact_type", "created_at" ], "title": "ApiRoutersWorkstreamsModels__CycleArtifactSummary", "description": "One artifact produced by a cycle, with a ready-to-use download URL.\n\nWS run-detail parity (BE): the cycle-detail response carried a count\nbadge (\"1 artifact\") but no download path, so the FE could not link\nto the produced file even though a download endpoint already exists.\nThis summary closes that gap. Read from workstreams.cycle_artifact." }, "CycleCreate": { "properties": { "blueprint_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Blueprint Id", "description": "Blueprint UUID (legacy path; use job_definition_id for new WorkPlans)" }, "job_definition_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Job Definition Id", "description": "WorkPlan (job_definition) UUID \u2014 preferred for WorkPlans created via POST /workplans" }, "workstream_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Workstream Id", "description": "Run-once: launch THIS WorkStream for one client with no WorkPlan and no blueprint. Mutually exclusive with blueprint_id/job_definition_id." }, "client_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Client Id", "description": "Client to run for (job_definition path only; overrides target_selector)" }, "input_data": { "additionalProperties": true, "type": "object", "title": "Input Data", "description": "Input data for the cycle" }, "priority": { "type": "integer", "maximum": 10.0, "minimum": 1.0, "title": "Priority", "description": "Execution priority (1=highest)", "default": 5 }, "topic_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Topic Id", "description": "Optional Topic UUID this cycle belongs to. Stamped onto workstreams.cycle.topic_id so topic\u2192run linkage resolves (the reverse link of platform.topics.workstream_id). NULL for cycles launched outside a topic context \u2014 no behaviour change." } }, "type": "object", "title": "ApiRoutersWorkstreamsModels__CycleCreate", "description": "Request to start a new cycle.\n\nSupply exactly one of ``blueprint_id`` (legacy blueprint-based path),\n``job_definition_id`` (converged WorkPlan path) or ``workstream_id``\n(run-once: this WorkStream, this client, no plan). When\n``job_definition_id`` is given the cycle is created via the fan-out engine;\nthe job_definition's ``target_selector`` resolves the client unless\n``client_id`` overrides it.\n\n``workstream_id`` is AR-224's run-once. It carries the workstream/client\nbinding directly instead of reading it off a stored row, so a client with\nno blueprint and no WorkPlan can still be run. Nothing new underneath:\n``launch_inline_cycle_batch`` already takes all three ids as optional, and\n``workstreams.cycle`` has permitted a blueprint-less inline cycle since\nmigration 20260508_0600 (CHECK ``execution_mode='inline' OR blueprint_id\nIS NOT NULL``). The alternative \u2014 minting a job_definition to carry the\nrun, as the batch route does \u2014 is the \"hidden throwaway WorkPlan\" the\nepic's guardrail forbids.", "example": { "input_data": { "period": "2025-01" }, "job_definition_id": "550e8400-e29b-41d4-a716-446655440000", "priority": 5 } }, "CycleEventListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/CycleEventResponse" }, "type": "array", "title": "Items" }, "total": { "type": "integer", "minimum": 0.0, "title": "Total", "description": "Number of events returned" } }, "type": "object", "required": [ "total" ], "title": "CycleEventListResponse", "description": "Recent activity-feed entries for a cycle, newest first." }, "CycleEventResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Event id" }, "event_type": { "type": "string", "title": "Event Type", "description": "Lifecycle event type, e.g. step_run.completed" }, "occurred_at": { "type": "string", "format": "date-time", "title": "Occurred At", "description": "When the event occurred" }, "severity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Severity", "description": "Event severity (info/warning/error)" }, "actor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Actor", "description": "Who emitted it (emitted_by); null = system/Archie" }, "payload": { "additionalProperties": true, "type": "object", "title": "Payload", "description": "Event detail (step_index, step_id, status, duration_ms\u2026) for FE labelling." } }, "type": "object", "required": [ "id", "event_type", "occurred_at" ], "title": "ApiRoutersWorkstreamsModels__CycleEventResponse", "description": "One activity-feed entry for a cycle (run/step lifecycle event)." }, "CycleEvidenceResponse": { "properties": { "references": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "References", "description": "Reference payload rows in step order; each carries step_id." }, "counts": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Counts", "description": "Register totals: total / resolved / proposed / queries." }, "hash_by_step": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Hash By Step", "description": "step_id -> the register content hash the gate seals." }, "decisions": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Decisions", "description": "The gate's decision trail, newest first (append-only). The latest decision per reference is also annotated onto its reference row as `decision`." }, "signoff": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Signoff", "description": "The standing identity-backed seal (latest sign-off row), or null while unsigned. Older sign-offs remain on file server-side." }, "doc_code_map": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Doc Code Map", "description": "doc-address code -> file_id for this cycle's cited source documents (merged from each step's diagnostics.doc_code_map), so surfaces can open a doc: target at its cited page." } }, "type": "object", "title": "ApiRoutersWorkstreamsModels__CycleEvidenceResponse", "description": "The cycle's tie register (References v1) \u2014 every step's\n``diagnostics.tie_register`` aggregated into one run-scoped evidence\nslice. Rows are the engine's Reference payloads verbatim (marks derived\nserver-side, never recomputed by a surface) plus the emitting step_id." }, "CycleLaunchInstanceResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Instance (cycle) UUID" }, "permakey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Permakey", "description": "Instance permakey (workstreams.cycle.permakey)" }, "client_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Client Id", "description": "The client this instance ran for. Null for a clientless run (a WorkStream run by itself) \u2014 never a synthesised placeholder." }, "client_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Name", "description": "The client's display name. Null when the instance has no client; the launch's label identifies a clientless run, never a placeholder." }, "status": { "type": "string", "title": "Status", "description": "Instance status (created/running/completed/failed/skipped/...)" }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Started At", "description": "When the instance started" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Completed At", "description": "When the instance reached a terminal state" } }, "type": "object", "required": [ "id", "status" ], "title": "ApiRoutersWorkstreamsModels__CycleLaunchInstanceResponse", "description": "One instance (per-client cycle row) under a cycle launch.\n\nCard \"A launch creates one cycle record with its own permakey\": the launch\nis the product's Cycle; the per-client ``workstreams.cycle`` row is its\nInstance. This summary carries the instance's own identity + status so the\nlaunch fetch can list its instances without a second round-trip." }, "CycleLaunchResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Launch record UUID" }, "permakey": { "type": "string", "title": "Permakey", "description": "Fresh permakey minted for this launch (not the plan's, not any instance's)" }, "workstream_id": { "type": "string", "format": "uuid", "title": "Workstream Id", "description": "The WorkStream this launch ran" }, "job_definition_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Job Definition Id", "description": "The WorkPlan this launch ran, when there was one. Null for run-once / a WorkStream by itself." }, "client_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Client Id", "description": "The single client this launch is for, when there is exactly one (run-once single client). Null for a multi-client fan-out (the clients live on the instances) and for a clientless run." }, "label": { "type": "string", "title": "Label", "description": "Identifies the launch on name surfaces. A clientless/planless run is identified by this, never a placeholder." }, "period": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Period", "description": "The launch's period fact (YYYY-MM). Null when no period." }, "workstream_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Workstream Version", "description": "WorkStream version integer at launch. Null until the run-version card lands." }, "launched_via": { "type": "string", "title": "Launched Via", "description": "How the launch was triggered (fan_out/batch/run_once/skill/...)" }, "launched_by_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Launched By User Id", "description": "User who triggered the launch" }, "started_at": { "type": "string", "format": "date-time", "title": "Started At", "description": "When the launch was minted (the launch's own start)" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Completed At", "description": "When every instance reached a terminal state. Derived from the instances' tallies (max completed_at), never stored ahead of them." }, "status": { "type": "string", "title": "Status", "description": "Derived from the instances' tallies \u2014 pending/running/completed/failed. Never stored ahead of the instances." }, "client_count": { "type": "integer", "title": "Client Count", "description": "Number of instances in this launch (the roster size)" }, "instances": { "items": { "$ref": "#/components/schemas/CycleLaunchInstanceResponse" }, "type": "array", "title": "Instances", "description": "The per-client instance rows this launch created" } }, "type": "object", "required": [ "id", "permakey", "workstream_id", "label", "launched_via", "started_at", "status", "client_count" ], "title": "ApiRoutersWorkstreamsModels__CycleLaunchResponse", "description": "A launch record \u2014 the product's Cycle \u2014 fetchable by its permakey.\n\nCard \"A launch creates one cycle record with its own permakey\": one launch\nof a plan (or a run with no plan) mints exactly one record with a fresh\npermakey of its own. Status is NOT stored on the record; it is derived from\nthe instances' tallies (``status`` below) so it can never be stored ahead\nof them. Three things are optional independently: the plan\n(``job_definition_id``), the client (``client_id``), and the period\n(``period``); a WorkStream run by itself has none of the three and is\nidentified by its ``label``." }, "CycleListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/CycleResponse" }, "type": "array", "title": "Items" }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object", "required": [ "pagination" ], "title": "ApiRoutersWorkstreamsModels__CycleListResponse", "description": "Paginated list of cycles (fleet view)." }, "CycleResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Cycle UUID" }, "permakey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Permakey", "description": "Stable human-readable cycle key for the deep-link URL /workstreams/{ws}/cycles/{permakey}/instance/{task}. Null on legacy rows." }, "workstream_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Workstream Id", "description": "Parent workstream UUID. Populated for every cycle launched against a workstream definition; only null for legacy agentic/v2 cycles that have no workstream parent." }, "workstream_permakey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workstream Permakey", "description": "Parent workstream's stable human-readable key (workstreams.workstream.permakey), resolved by joining on the same COALESCE(cycle.workstream_id, blueprint.workstream_id) that backs workstream_id. Lets the list/detail surfaces build the permakey-prefixed deep link /workstreams/{workstream_permakey}/cycles/{permakey} without a second fetch. Null when no workstream parent resolves (legacy agentic/v2 cycles, or a workstream that no longer exists)." }, "workstream_slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workstream Slug", "description": "Parent workstream's URL slug (workstreams.workstream.slug), resolved via the same join as workstream_permakey. Null when no workstream parent resolves." }, "workstream_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Workstream Version", "description": "The WorkStream version this cycle executed \u2014 stamped at launch from workstreams.workstream.version (or the pinned version on a WorkPlan). Immutable after launch. Null on legacy cycles that predate the column or have no workstream parent." }, "cycle_launch_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Cycle Launch Id", "description": "The cycle_launch (the product's Cycle - one launch of a plan) this instance (per-client cycle row) belongs to. Card 'Cycle URLs open cycles, WorkPlan URLs open WorkPlans': an instance nests under its cycle (/workstreams/{ws}/cycles/{cycle}/instances/{instance}), and the cycle segment is the cycle_launch's permakey. Null on legacy rows that predate the backfill (20260902_0100)." }, "cycle_launch_permakey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cycle Launch Permakey", "description": "The cycle_launch's stable permakey - the canonical cycle URL segment the instance nests under. Lets the instance page build its breadcrumb cycle crumb (/workstreams/{ws}/cycles/{cycle}) without a second fetch. Null when the instance has no parent launch (a pre-backfill orphan)." }, "definition_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Definition Hash", "description": "Content-addressed definition hash \u2014 nullable placeholder for the content-addressing substrate (not yet landed). Distinct from code_sha (the launching-code git SHA used by the deploy-race guard). Always null until that design ships." }, "workplan_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Workplan Id", "description": "Workplan UUID (null for agentic cycles)" }, "workplan_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workplan Name", "description": "Workplan name (from join)" }, "client_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Client Id", "description": "Client UUID (from workplan join)" }, "client_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Name", "description": "Client name (from workplan join)" }, "status": { "$ref": "#/components/schemas/CycleStatus", "description": "Cycle status" }, "progress_pct": { "type": "number", "maximum": 100.0, "minimum": 0.0, "title": "Progress Pct", "description": "`completed_steps / total_steps * 100` \u2014 work that RAN AND FINISHED, over the whole ladder. Skipped steps are excluded from the numerator and stay in the denominator, so a run that stopped early can never reach 100%. It is a record of how far the run got, not a live fraction: pair it with `status` and `current_step_index` before rendering, and never read it alone as 'nearly done'.", "default": 0.0 }, "blueprint_snapshot": { "additionalProperties": true, "type": "object", "title": "Blueprint Snapshot", "description": "Workplan snapshot at cycle start" }, "error_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Error Context", "description": "Error context if failed" }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Started At", "description": "Start timestamp" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Completed At", "description": "Completion timestamp" }, "started_by": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Started By", "description": "Initiator user ID (started_by in DB)" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Last update timestamp" }, "current_step_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Current Step Name", "description": "Name of the ONE current step every FE view should render verbatim (banner, Steps tab, Approvals tab, batch matrix). Resolved by _compute_run_progress: the earliest in-flight/awaiting step, else (when the cycle has failed) the last failed step. Never the literal 'Unknown' \u2014 an unnamed step falls back to a humanized blueprint step id or 'Step N'. Null only when no step can be resolved at all (e.g. a cycle with zero tasks)." }, "current_step_index": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Current Step Index", "description": "1-based position of current_step_name within the cycle's steps. Null exactly when current_step_name is null \u2014 the two are always resolved together so a view never pairs a real index with a missing name (or vice versa) \u2014 see pilot run-through defect B1 ('Step 0: Unknown')." }, "failure_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Failure Reason", "description": "Human-readable reason the run is errored/blocked, populated whenever status is failed/cancelled/blocked \u2014 even when no current step could be resolved (e.g. 'The run stopped before any step could be identified.'). FE should show this INSTEAD OF a step placeholder, never alongside a fabricated 'Step ?'. Written for an accountant: no step ids, no raw floats where money is meant, no internal certification vocabulary. The engine's or the approver's own words are on failure_details." }, "failure_details": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Failure Details", "description": "The engine's or the approver's own words, verbatim and unshortened, behind the surface's Details affordance. NEVER rendered inline \u2014 failure_reason is the sentence a person reads. Null when the reason IS already the whole of what was recorded." }, "retryable": { "type": "boolean", "title": "Retryable", "description": "Whether a Retry action applies to this run (status is failed/cancelled).", "default": false }, "needs_approval": { "type": "boolean", "title": "Needs Approval", "description": "True when this run is parked on a human sign-off nobody has given yet: a task with approved_at NULL that is awaiting_approval (by status or by outputs.status), on a cycle that is not already over. Same predicate as the swarm/jobs read, so a run cannot report differently depending on which endpoint served it. The FE pairs it with `status` to choose the amber 'Needs you' pill over the grey 'Blocked' one \u2014 a blocked cycle with no open gate is genuinely just blocked.", "default": false }, "held_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Held Reason", "description": "Why this run is WAITING, composed for an accountant from the cycle's OWN measured outputs \u2014 several short lines: what is happening, whose work it is, the amount as money, where it is written down, and what un-blocks it. Populated from the HOLD STATE (an approval gate with approved_at NULL, parked at awaiting_approval, on a cycle that is not over) \u2014 never by parsing a rejection string, which a held run does not have. A hold is NOT a failure: it never populates `failure_reason` and never writes cycle.error_context." }, "held_details": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Held Details", "description": "The reviewer's own words for the hold (workstreams.task.outputs.hold_metadata.question on the parked gate), verbatim and unshortened, for a Details affordance. Never rendered inline and never mined for facts \u2014 every figure in `held_reason` comes from a step's own recorded output." }, "completed_steps": { "type": "integer", "minimum": 0.0, "title": "Completed Steps", "description": "Steps that RAN AND FINISHED (completed/approved/done). Skipped steps are NOT counted here \u2014 they never ran. Card #263: until this field was corrected, a run halted at step 7 of 18 with the remaining steps skipped reported 16 of 18 and rendered a nearly-full bar. Read together with `skipped_steps` and `current_step_index`, which say how far the run actually got and where it stopped.", "default": 0 }, "skipped_steps": { "type": "integer", "minimum": 0.0, "title": "Skipped Steps", "description": "Steps that NEVER RAN \u2014 the run stopped upstream, or a condition excluded them. Not progress and not failure: reported in its own right so a refusal reads as a refusal. `completed_steps + skipped_steps` is NOT a progress figure and must never be rendered as one; the pair exists precisely so the two are not added together again.", "default": 0 }, "total_steps": { "type": "integer", "minimum": 0.0, "title": "Total Steps", "description": "Total number of steps in cycle", "default": 0 }, "customer_cost_gbp": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Customer Cost Gbp", "description": "Customer-facing cost in GBP: \u00a319/hr x elapsed time since cycle start. NULL when the cycle has not yet started. Uses completed_at if available, otherwise current wall-clock time. The real compute cost is never served (CR-COST-01)." }, "tokens_total_input": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tokens Total Input", "description": "Total input tokens across all steps. NULL when none recorded." }, "tokens_total_output": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tokens Total Output", "description": "Total output tokens across all steps. NULL when none recorded." }, "artifacts": { "items": { "$ref": "#/components/schemas/CycleArtifactSummary" }, "type": "array", "title": "Artifacts", "description": "Artifacts produced by this cycle (workstreams.cycle_artifact, non-deleted), newest first, each with a download_url. Surfaced at CYCLE level \u2014 step\u2192artifact attribution is a follow-up. Empty when the cycle produced no artifacts." }, "workbook": { "$ref": "#/components/schemas/CycleWorkbookRef", "description": "The workbook a run produced, with its review state (card 011). Derived server-side from the latest fill/compile step's ``outputs.document_id`` and the run-level sign-off record \u2014 the frontend renders the Workbook tab from this field, not from a guess at step outputs. ``not_yet_reviewed`` makes the workbook VISIBLE (a reviewer must see it to review it) while the download stays 409-gated until the gate passes." }, "input_data": { "additionalProperties": true, "type": "object", "title": "Input Data", "description": "Launch inputs the cycle was started with (period, file refs, run_mode, etc.), read from workstreams.cycle.runtime_vars \u2014 the canonical input dict written verbatim on both the inline and containerized launch paths. Empty when the cycle has no recorded launch inputs. Within-workspace only (the endpoint is FGA- + workspace-scoped); redact file names / conversation_id before surfacing this on any cross-org surface." } }, "type": "object", "required": [ "id", "status", "created_at", "updated_at" ], "title": "ApiRoutersWorkstreamsModels__CycleResponse", "description": "Cycle response model." }, "CycleSlotResolutionResponse": { "properties": { "kind": { "type": "string", "title": "Kind", "description": "What the id canonically is: 'cycle_launch' (render the nested cycle), 'plan' (redirect to the workplan URL), 'instance' (redirect to the instance URL under its cycle), or 'unknown' (designed not-found)." }, "canonical_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Canonical Url", "description": "The canonical URL the id should land on. Null for 'unknown' (the route shows a designed not-found, never a fourteen-second retry)." }, "workstream_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workstream Ref", "description": "The workstream URL segment of the resolved entity (logging/asserts)." }, "entity_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Entity Ref", "description": "The entity's own URL segment (permakey or UUID) of the resolved entity." } }, "type": "object", "required": [ "kind" ], "title": "ApiRoutersWorkstreamsModels__CycleSlotResolutionResponse", "description": "The canonical-landing decision for an id in the cycle slot.\n\nCard \"Cycle URLs open cycles, WorkPlan URLs open WorkPlans\": the single\nresolver that decides which entity an id in the cycle slot canonically IS\n(a cycle_launch, a plan/job_definition, a legacy instance/workstreams.cycle,\nor unknown) and the URL it should land on. The frontend flat cycle route\ncalls ``GET /workstreams/cycle-slot/{identifier}`` and ``Navigate replace``-s\nto ``canonical_url`` (the SPA permanent-redirect equivalent of a 308);\n``unknown`` carries no url and the route shows a designed not-found." }, "CycleStatus": { "type": "string", "enum": [ "created", "planning", "queued", "running", "paused", "blocked", "completed", "failed", "cancelled", "skipped", "pending", "needs_guidance", "abandoned", "debug_paused" ], "title": "CycleStatus", "description": "Status for execution cycles - matches DB check constraint." }, "CycleTaskPair": { "properties": { "cycle_id": { "type": "string", "title": "Cycle Id", "description": "Cycle UUID or permakey" }, "task_id": { "type": "string", "title": "Task Id", "description": "Task UUID, permakey, or step_id within the cycle" } }, "type": "object", "required": [ "cycle_id", "task_id" ], "title": "CycleTaskPair", "description": "One (cycle, task) instance to resolve in a bulk approval." }, "CycleTimingResponse": { "properties": { "as_of": { "type": "string", "format": "date-time", "title": "As Of", "description": "Timestamp of the cycle-row read snapshot" }, "elapsed_seconds": { "anyOf": [ { "type": "number", "minimum": 0.0 }, { "type": "null" } ], "title": "Elapsed Seconds", "description": "Wall time since the recorded start" }, "working_seconds": { "anyOf": [ { "type": "number", "minimum": 0.0 }, { "type": "null" } ], "title": "Working Seconds", "description": "Recorded lifecycle running intervals, excluding paused/blocked time; null when unprovable" }, "elapsed_ticking": { "type": "boolean", "title": "Elapsed Ticking", "default": false }, "working_ticking": { "type": "boolean", "title": "Working Ticking", "default": false } }, "type": "object", "required": [ "as_of" ], "title": "CycleTimingResponse", "description": "Two clocks at one read snapshot; working time is not billable/tool time." }, "CycleWithTasksResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Cycle UUID" }, "permakey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Permakey", "description": "Stable human-readable cycle key for the deep-link URL /workstreams/{ws}/cycles/{permakey}/instance/{task}. Null on legacy rows." }, "workstream_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Workstream Id", "description": "Parent workstream UUID. Populated for every cycle launched against a workstream definition; only null for legacy agentic/v2 cycles that have no workstream parent." }, "workstream_permakey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workstream Permakey", "description": "Parent workstream's stable human-readable key (workstreams.workstream.permakey), resolved by joining on the same COALESCE(cycle.workstream_id, blueprint.workstream_id) that backs workstream_id. Lets the list/detail surfaces build the permakey-prefixed deep link /workstreams/{workstream_permakey}/cycles/{permakey} without a second fetch. Null when no workstream parent resolves (legacy agentic/v2 cycles, or a workstream that no longer exists)." }, "workstream_slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workstream Slug", "description": "Parent workstream's URL slug (workstreams.workstream.slug), resolved via the same join as workstream_permakey. Null when no workstream parent resolves." }, "workstream_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Workstream Version", "description": "The WorkStream version this cycle executed \u2014 stamped at launch from workstreams.workstream.version (or the pinned version on a WorkPlan). Immutable after launch. Null on legacy cycles that predate the column or have no workstream parent." }, "cycle_launch_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Cycle Launch Id", "description": "The cycle_launch (the product's Cycle - one launch of a plan) this instance (per-client cycle row) belongs to. Card 'Cycle URLs open cycles, WorkPlan URLs open WorkPlans': an instance nests under its cycle (/workstreams/{ws}/cycles/{cycle}/instances/{instance}), and the cycle segment is the cycle_launch's permakey. Null on legacy rows that predate the backfill (20260902_0100)." }, "cycle_launch_permakey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cycle Launch Permakey", "description": "The cycle_launch's stable permakey - the canonical cycle URL segment the instance nests under. Lets the instance page build its breadcrumb cycle crumb (/workstreams/{ws}/cycles/{cycle}) without a second fetch. Null when the instance has no parent launch (a pre-backfill orphan)." }, "definition_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Definition Hash", "description": "Content-addressed definition hash \u2014 nullable placeholder for the content-addressing substrate (not yet landed). Distinct from code_sha (the launching-code git SHA used by the deploy-race guard). Always null until that design ships." }, "workplan_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Workplan Id", "description": "Workplan UUID (null for agentic cycles)" }, "workplan_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workplan Name", "description": "Workplan name (from join)" }, "client_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Client Id", "description": "Client UUID (from workplan join)" }, "client_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Name", "description": "Client name (from workplan join)" }, "status": { "$ref": "#/components/schemas/CycleStatus", "description": "Cycle status" }, "progress_pct": { "type": "number", "maximum": 100.0, "minimum": 0.0, "title": "Progress Pct", "description": "`completed_steps / total_steps * 100` \u2014 work that RAN AND FINISHED, over the whole ladder. Skipped steps are excluded from the numerator and stay in the denominator, so a run that stopped early can never reach 100%. It is a record of how far the run got, not a live fraction: pair it with `status` and `current_step_index` before rendering, and never read it alone as 'nearly done'.", "default": 0.0 }, "blueprint_snapshot": { "additionalProperties": true, "type": "object", "title": "Blueprint Snapshot", "description": "Workplan snapshot at cycle start" }, "error_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Error Context", "description": "Error context if failed" }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Started At", "description": "Start timestamp" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Completed At", "description": "Completion timestamp" }, "started_by": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Started By", "description": "Initiator user ID (started_by in DB)" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Last update timestamp" }, "current_step_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Current Step Name", "description": "Name of the ONE current step every FE view should render verbatim (banner, Steps tab, Approvals tab, batch matrix). Resolved by _compute_run_progress: the earliest in-flight/awaiting step, else (when the cycle has failed) the last failed step. Never the literal 'Unknown' \u2014 an unnamed step falls back to a humanized blueprint step id or 'Step N'. Null only when no step can be resolved at all (e.g. a cycle with zero tasks)." }, "current_step_index": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Current Step Index", "description": "1-based position of current_step_name within the cycle's steps. Null exactly when current_step_name is null \u2014 the two are always resolved together so a view never pairs a real index with a missing name (or vice versa) \u2014 see pilot run-through defect B1 ('Step 0: Unknown')." }, "failure_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Failure Reason", "description": "Human-readable reason the run is errored/blocked, populated whenever status is failed/cancelled/blocked \u2014 even when no current step could be resolved (e.g. 'The run stopped before any step could be identified.'). FE should show this INSTEAD OF a step placeholder, never alongside a fabricated 'Step ?'. Written for an accountant: no step ids, no raw floats where money is meant, no internal certification vocabulary. The engine's or the approver's own words are on failure_details." }, "failure_details": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Failure Details", "description": "The engine's or the approver's own words, verbatim and unshortened, behind the surface's Details affordance. NEVER rendered inline \u2014 failure_reason is the sentence a person reads. Null when the reason IS already the whole of what was recorded." }, "retryable": { "type": "boolean", "title": "Retryable", "description": "Whether a Retry action applies to this run (status is failed/cancelled).", "default": false }, "needs_approval": { "type": "boolean", "title": "Needs Approval", "description": "True when this run is parked on a human sign-off nobody has given yet: a task with approved_at NULL that is awaiting_approval (by status or by outputs.status), on a cycle that is not already over. Same predicate as the swarm/jobs read, so a run cannot report differently depending on which endpoint served it. The FE pairs it with `status` to choose the amber 'Needs you' pill over the grey 'Blocked' one \u2014 a blocked cycle with no open gate is genuinely just blocked.", "default": false }, "held_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Held Reason", "description": "Why this run is WAITING, composed for an accountant from the cycle's OWN measured outputs \u2014 several short lines: what is happening, whose work it is, the amount as money, where it is written down, and what un-blocks it. Populated from the HOLD STATE (an approval gate with approved_at NULL, parked at awaiting_approval, on a cycle that is not over) \u2014 never by parsing a rejection string, which a held run does not have. A hold is NOT a failure: it never populates `failure_reason` and never writes cycle.error_context." }, "held_details": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Held Details", "description": "The reviewer's own words for the hold (workstreams.task.outputs.hold_metadata.question on the parked gate), verbatim and unshortened, for a Details affordance. Never rendered inline and never mined for facts \u2014 every figure in `held_reason` comes from a step's own recorded output." }, "completed_steps": { "type": "integer", "minimum": 0.0, "title": "Completed Steps", "description": "Steps that RAN AND FINISHED (completed/approved/done). Skipped steps are NOT counted here \u2014 they never ran. Card #263: until this field was corrected, a run halted at step 7 of 18 with the remaining steps skipped reported 16 of 18 and rendered a nearly-full bar. Read together with `skipped_steps` and `current_step_index`, which say how far the run actually got and where it stopped.", "default": 0 }, "skipped_steps": { "type": "integer", "minimum": 0.0, "title": "Skipped Steps", "description": "Steps that NEVER RAN \u2014 the run stopped upstream, or a condition excluded them. Not progress and not failure: reported in its own right so a refusal reads as a refusal. `completed_steps + skipped_steps` is NOT a progress figure and must never be rendered as one; the pair exists precisely so the two are not added together again.", "default": 0 }, "total_steps": { "type": "integer", "minimum": 0.0, "title": "Total Steps", "description": "Total number of steps in cycle", "default": 0 }, "customer_cost_gbp": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Customer Cost Gbp", "description": "Customer-facing cost in GBP: \u00a319/hr x elapsed time since cycle start. NULL when the cycle has not yet started. Uses completed_at if available, otherwise current wall-clock time. The real compute cost is never served (CR-COST-01)." }, "tokens_total_input": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tokens Total Input", "description": "Total input tokens across all steps. NULL when none recorded." }, "tokens_total_output": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tokens Total Output", "description": "Total output tokens across all steps. NULL when none recorded." }, "artifacts": { "items": { "$ref": "#/components/schemas/CycleArtifactSummary" }, "type": "array", "title": "Artifacts", "description": "Artifacts produced by this cycle (workstreams.cycle_artifact, non-deleted), newest first, each with a download_url. Surfaced at CYCLE level \u2014 step\u2192artifact attribution is a follow-up. Empty when the cycle produced no artifacts." }, "workbook": { "$ref": "#/components/schemas/CycleWorkbookRef", "description": "The workbook a run produced, with its review state (card 011). Derived server-side from the latest fill/compile step's ``outputs.document_id`` and the run-level sign-off record \u2014 the frontend renders the Workbook tab from this field, not from a guess at step outputs. ``not_yet_reviewed`` makes the workbook VISIBLE (a reviewer must see it to review it) while the download stays 409-gated until the gate passes." }, "input_data": { "additionalProperties": true, "type": "object", "title": "Input Data", "description": "Launch inputs the cycle was started with (period, file refs, run_mode, etc.), read from workstreams.cycle.runtime_vars \u2014 the canonical input dict written verbatim on both the inline and containerized launch paths. Empty when the cycle has no recorded launch inputs. Within-workspace only (the endpoint is FGA- + workspace-scoped); redact file names / conversation_id before surfacing this on any cross-org surface." }, "tasks": { "items": { "$ref": "#/components/schemas/TaskResponse" }, "type": "array", "title": "Tasks", "description": "Tasks in this cycle" }, "timing": { "anyOf": [ { "$ref": "#/components/schemas/CycleTimingResponse" }, { "type": "null" } ], "description": "Validated run-band clocks; no raw lifecycle history" }, "approval_steps": { "items": { "$ref": "#/components/schemas/ApprovalStepResponse" }, "type": "array", "title": "Approval Steps", "description": "Approval-gate tasks projected for FE approval-gate rendering. Contains tasks where requires_approval=True or status=awaiting_approval, ordered by sequence_order." } }, "type": "object", "required": [ "id", "status", "created_at", "updated_at" ], "title": "ApiRoutersWorkstreamsModels__CycleResponse", "description": "Cycle response with embedded tasks." }, "CycleWorkbookRef": { "properties": { "document_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Document Id", "description": "The file_uploads id of the workbook the latest fill/compile step wrote (``task.outputs.document_id``). Null when no such step has run." }, "state": { "$ref": "#/components/schemas/CycleWorkbookState", "description": "``reviewed`` when a run-level sign-off record exists; ``not_yet_reviewed`` when a fill/compile step wrote a workbook but no sign-off exists yet; ``none`` otherwise.", "default": "none" }, "download_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Download Url", "description": "The file download path for the workbook (``/api/v1/files/{document_id}/download``). Present whenever document_id is present. The route 409-refuses a not_yet_reviewed workbook until the gate passes \u2014 this URL is for the tab's inline render, not for downloading as final." } }, "type": "object", "title": "ApiRoutersWorkstreamsModels__CycleWorkbookRef", "description": "The workbook a run produced, with its review state (card 011).\n\nThe API does the fallback, not the frontend: the cycle GET payload carries\nthis field so the Workbook tab renders from it directly \u2014 a frontend-only\nguess at step outputs is rejected. ``document_id`` is the file_uploads id of\nthe workbook the latest fill/compile step wrote (``task.outputs.document_id``,\nwhich fill_bank_operation and its siblings return today); ``state`` is\n``reviewed`` when a run-level sign-off record exists, ``not_yet_reviewed``\nwhen that document_id exists but no sign-off does, and ``none`` otherwise." }, "CycleWorkbookState": { "type": "string", "enum": [ "reviewed", "not_yet_reviewed", "none" ], "title": "CycleWorkbookState", "description": "The review state of the workbook a run produced.\n\nA reviewer needs to SEE the workbook a fill/compile step wrote in order to\nreview it, even though the review gate has not passed (card 011). The state\ntells the frontend whether to render the \"not yet reviewed\" label and\ndisable the download \u2014 the SERVER is the control, never the FE button." }, "Decision": { "properties": { "id": { "type": "string", "title": "Id", "description": "Stable decision identifier" }, "question": { "type": "string", "title": "Question", "description": "The question this decision answers" }, "why_asked": { "type": "string", "title": "Why Asked", "description": "Provenance / rationale for why this decision exists", "default": "" }, "origin": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Origin", "description": "How the question came to be asked: probed (derived from an attached document this build), inherited (carried from a prior version/template) or hand_written (a person typed it)." }, "options": { "items": { "$ref": "#/components/schemas/DecisionOption" }, "type": "array", "title": "Options", "description": "Options considered for this decision" }, "proposal": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Proposal", "description": "The builder's proposed answer (its best reading of the documents). An affirmative one-word answer resolves to this value." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason", "description": "The builder's reason for its proposal \u2014 what turns on the answer" }, "settles": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Settles", "description": "Which of the five interview-settling concerns this decision belongs to (card 014)" }, "raised_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Raised By", "description": "Id of the answered decision whose answer raised this one; None for interview-seeded decisions" }, "document_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Document Id", "description": "The attached Input (platform.file_uploads id) this decision's question was derived from" }, "page": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page", "description": "The 1-based page within that document carrying the cited evidence; None when the extraction provides no page information" }, "answer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Answer", "description": "The chosen option value when the decision is answered" }, "answer_provenance": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Answer Provenance", "description": "Source locator or rationale for the chosen answer" }, "status": { "type": "string", "title": "Status", "description": "open | answered | deferred \u2014 lifecycle of the decision", "default": "open" }, "disposition": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Disposition", "description": "Disposition when not answered (e.g. deferred, blocked)" }, "owner": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner", "description": "Who must resolve an open or deferred decision" } }, "additionalProperties": false, "type": "object", "required": [ "id", "question" ], "title": "Decision", "description": "A single decision in a WorkStream spec.\n\nA decision may be *answered* (``answer`` set, ``status=\"answered\"``) or\n*open* (``disposition`` + ``owner`` set, ``status=\"open\"``). An answered\ndecision contributes to the compiled bindings; an open one records who\nmust resolve it and why it was deferred." }, "DecisionOption": { "properties": { "id": { "type": "string", "title": "Id", "description": "Stable option identifier within this decision" }, "label": { "type": "string", "title": "Label", "description": "Human-readable option text" }, "value": { "type": "string", "title": "Value", "description": "Machine value bound by this option" } }, "additionalProperties": false, "type": "object", "required": [ "id", "label", "value" ], "title": "DecisionOption", "description": "One option considered for a decision." }, "DescribeStepFromWdlContext": { "properties": { "workstream_id": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "title": "Workstream Id" }, "max_length": { "type": "integer", "maximum": 480.0, "minimum": 60.0, "title": "Max Length", "default": 240 } }, "type": "object", "title": "DescribeStepFromWdlContext", "description": "Optional context for describe-from-WDL streaming. Mirrors the\nservice-layer ``DescribeStepContext`` model but lives on the router\nso the OpenAPI snapshot doesn't pull a service-internal class into\nthe public schema graph." }, "DescribeStepFromWdlRequest": { "properties": { "step": { "additionalProperties": true, "type": "object", "title": "Step", "description": "The step JSON to describe. Shape matches the step config returned by /steps/generate-from-description (id / type / tool_name / tool_params / instruction / etc.)." }, "context": { "anyOf": [ { "$ref": "#/components/schemas/DescribeStepFromWdlContext" }, { "type": "null" } ] } }, "type": "object", "required": [ "step" ], "title": "DescribeStepFromWdlRequest", "description": "Request to describe a single workstream step in plain English." }, "DeterministicExtractionStepDefinition": { "properties": { "id": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9_-]+$", "title": "Id" }, "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name" }, "type": { "type": "string", "const": "deterministic_extraction", "title": "Type", "default": "deterministic_extraction" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "depends_on": { "items": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" } ] }, "type": "array", "title": "Depends On" }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stage" }, "timeout": { "anyOf": [ { "type": "string", "pattern": "^\\d+[smhd]$" }, { "type": "null" } ], "title": "Timeout" }, "retry_policy": { "anyOf": [ { "$ref": "#/components/schemas/RetryPolicy" }, { "type": "null" } ] }, "error_handler": { "anyOf": [ { "$ref": "#/components/schemas/StepErrorHandler" }, { "type": "null" } ] }, "emit_artifact": { "anyOf": [ { "$ref": "#/components/schemas/EmitArtifactSpec" }, { "type": "null" } ] }, "optional": { "type": "boolean", "title": "Optional", "default": false }, "continue_on_error": { "type": "boolean", "title": "Continue On Error", "default": false }, "halt_conditions": { "items": { "$ref": "#/components/schemas/HaltCondition" }, "type": "array", "title": "Halt Conditions" }, "parameters": { "items": { "$ref": "#/components/schemas/StepParameter" }, "type": "array", "title": "Parameters" }, "guards": { "items": { "$ref": "#/components/schemas/StepGuard" }, "type": "array", "title": "Guards" }, "impact_level": { "$ref": "#/components/schemas/ImpactLevel", "default": "medium" }, "run_mode": { "$ref": "#/components/schemas/RunMode", "default": "propose" }, "requires_approval": { "type": "boolean", "title": "Requires Approval", "default": false }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "examples": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StepExample" }, "type": "array" }, { "type": "null" } ], "title": "Examples", "description": "Attached example files for this step. Each entry pairs a platform.file_uploads.file_id with a role + tags + notes so the runtime can shape its instruction. Bounded at 20 to keep a reasonable upper limit on the prompt preamble." }, "applies_when": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applies When", "description": "CEL predicate evaluated at MATERIALIZATION (not at step execution): the step is marked skipped when it evaluates False. Stored verbatim \u2014 the expression is parsed by celpy at launch, so any coercion here would change its meaning." }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "Categorical labels on the step itself (e.g. 'pdf-read', 'coutts', 'fy25'). Free-form; recommended tag set is documented per workstream surface." }, "config": { "additionalProperties": true, "type": "object", "title": "Config", "description": "Extraction config (document_type, file_discovery, etc.)" } }, "additionalProperties": true, "type": "object", "required": [ "id", "name" ], "title": "DeterministicExtractionStepDefinition", "description": "Deterministic extraction step - parses files with Python, no LLM." }, "DisableWritesRequest": { "properties": { "reason": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "title": "Reason", "description": "Optional reason for disabling writes" } }, "type": "object", "title": "DisableWritesRequest", "description": "Request schema for disabling write operations on a blueprint.\n\nReturns the blueprint to read-only mode, preventing any write\noperations to external systems." }, "DocumentUploadStepDefinition": { "properties": { "id": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9_-]+$", "title": "Id" }, "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name" }, "type": { "type": "string", "const": "document_upload", "title": "Type", "default": "document_upload" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "depends_on": { "items": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" } ] }, "type": "array", "title": "Depends On" }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stage" }, "timeout": { "anyOf": [ { "type": "string", "pattern": "^\\d+[smhd]$" }, { "type": "null" } ], "title": "Timeout" }, "retry_policy": { "anyOf": [ { "$ref": "#/components/schemas/RetryPolicy" }, { "type": "null" } ] }, "error_handler": { "anyOf": [ { "$ref": "#/components/schemas/StepErrorHandler" }, { "type": "null" } ] }, "emit_artifact": { "anyOf": [ { "$ref": "#/components/schemas/EmitArtifactSpec" }, { "type": "null" } ] }, "optional": { "type": "boolean", "title": "Optional", "default": false }, "continue_on_error": { "type": "boolean", "title": "Continue On Error", "default": false }, "halt_conditions": { "items": { "$ref": "#/components/schemas/HaltCondition" }, "type": "array", "title": "Halt Conditions" }, "parameters": { "items": { "$ref": "#/components/schemas/StepParameter" }, "type": "array", "title": "Parameters" }, "guards": { "items": { "$ref": "#/components/schemas/StepGuard" }, "type": "array", "title": "Guards" }, "impact_level": { "$ref": "#/components/schemas/ImpactLevel", "default": "medium" }, "run_mode": { "$ref": "#/components/schemas/RunMode", "default": "propose" }, "requires_approval": { "type": "boolean", "title": "Requires Approval", "default": false }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "examples": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StepExample" }, "type": "array" }, { "type": "null" } ], "title": "Examples", "description": "Attached example files for this step. Each entry pairs a platform.file_uploads.file_id with a role + tags + notes so the runtime can shape its instruction. Bounded at 20 to keep a reasonable upper limit on the prompt preamble." }, "applies_when": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applies When", "description": "CEL predicate evaluated at MATERIALIZATION (not at step execution): the step is marked skipped when it evaluates False. Stored verbatim \u2014 the expression is parsed by celpy at launch, so any coercion here would change its meaning." }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "Categorical labels on the step itself (e.g. 'pdf-read', 'coutts', 'fy25'). Free-form; recommended tag set is documented per workstream surface." }, "upload_config": { "$ref": "#/components/schemas/UploadConfig" }, "on_complete": { "anyOf": [ { "$ref": "#/components/schemas/OnCompleteAction" }, { "type": "null" } ] } }, "additionalProperties": false, "type": "object", "required": [ "id", "name" ], "title": "DocumentUploadStepDefinition", "description": "Document upload step - pauses for human file upload." }, "DraftConversationMessage": { "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ], "title": "Role" }, "message": { "type": "string", "title": "Message" }, "ts": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Ts" } }, "type": "object", "required": [ "role", "message" ], "title": "DraftConversationMessage", "description": "One turn in the user\u2194Archie draft conversation." }, "EmailSendStepDefinition": { "properties": { "id": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9_-]+$", "title": "Id" }, "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name" }, "type": { "type": "string", "const": "email_send", "title": "Type", "default": "email_send" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "depends_on": { "items": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" } ] }, "type": "array", "title": "Depends On" }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stage" }, "timeout": { "anyOf": [ { "type": "string", "pattern": "^\\d+[smhd]$" }, { "type": "null" } ], "title": "Timeout" }, "retry_policy": { "anyOf": [ { "$ref": "#/components/schemas/RetryPolicy" }, { "type": "null" } ] }, "error_handler": { "anyOf": [ { "$ref": "#/components/schemas/StepErrorHandler" }, { "type": "null" } ] }, "emit_artifact": { "anyOf": [ { "$ref": "#/components/schemas/EmitArtifactSpec" }, { "type": "null" } ] }, "optional": { "type": "boolean", "title": "Optional", "default": false }, "continue_on_error": { "type": "boolean", "title": "Continue On Error", "default": false }, "halt_conditions": { "items": { "$ref": "#/components/schemas/HaltCondition" }, "type": "array", "title": "Halt Conditions" }, "parameters": { "items": { "$ref": "#/components/schemas/StepParameter" }, "type": "array", "title": "Parameters" }, "guards": { "items": { "$ref": "#/components/schemas/StepGuard" }, "type": "array", "title": "Guards" }, "impact_level": { "$ref": "#/components/schemas/ImpactLevel", "default": "medium" }, "run_mode": { "$ref": "#/components/schemas/RunMode", "default": "propose" }, "requires_approval": { "type": "boolean", "title": "Requires Approval", "default": false }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "examples": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StepExample" }, "type": "array" }, { "type": "null" } ], "title": "Examples", "description": "Attached example files for this step. Each entry pairs a platform.file_uploads.file_id with a role + tags + notes so the runtime can shape its instruction. Bounded at 20 to keep a reasonable upper limit on the prompt preamble." }, "applies_when": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applies When", "description": "CEL predicate evaluated at MATERIALIZATION (not at step execution): the step is marked skipped when it evaluates False. Stored verbatim \u2014 the expression is parsed by celpy at launch, so any coercion here would change its meaning." }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "Categorical labels on the step itself (e.g. 'pdf-read', 'coutts', 'fy25'). Free-form; recommended tag set is documented per workstream surface." }, "recipient": { "type": "string", "title": "Recipient", "description": "Recipient email address or template expression (e.g., '{{ context.parameters.client_email }}')" }, "subject_template": { "type": "string", "title": "Subject Template", "description": "Jinja2 template for the email subject" }, "body_template": { "type": "string", "title": "Body Template", "description": "Jinja2 template for the email body (plain text)" }, "send_as": { "type": "string", "title": "Send As", "description": "'archie' to send from AI inbox, 'user' to send from user's connected email", "default": "archie" }, "store_message_id_in": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Store Message Id In", "description": "Context variable path to store the sent message ID (for threading)" } }, "additionalProperties": false, "type": "object", "required": [ "id", "name", "recipient", "subject_template", "body_template" ], "title": "EmailSendStepDefinition", "description": "Email send step \u2014 sends an email via Nylas or Agentmail.\n\nUsed in Chase workflows to send follow-up emails. The recipient,\nsubject, and body support Jinja2 templates with access to the\nworkflow context (parameters, variables, prior step outputs)." }, "EmitArtifactSpec": { "properties": { "output_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Output Key", "description": "Persist only this outputs key; None \u21d2 whole outputs." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Artifact display/file name; defaults to the step id." }, "artifact_type": { "type": "string", "title": "Artifact Type", "default": "step_output" }, "content_type": { "type": "string", "title": "Content Type", "default": "application/json" }, "downloadable": { "type": "boolean", "title": "Downloadable", "default": true } }, "additionalProperties": false, "type": "object", "title": "EmitArtifactSpec", "description": "Opt-in: persist a step's declared output as a downloadable\n``workstreams.cycle_artifact`` after the step succeeds.\n\n``output_key`` selects a single key from the step's outputs; when omitted\nthe whole outputs object (minus ``_``-prefixed scratch keys) is persisted.\nA step WITHOUT ``emit_artifact`` emits nothing \u2014 byte-identical to prior\nbehaviour." }, "EnableWritesRequest": { "properties": { "confirmation": { "type": "boolean", "title": "Confirmation", "description": "Explicit confirmation that writes should be enabled", "default": true }, "reason": { "type": "string", "maxLength": 1000, "minLength": 1, "title": "Reason", "description": "Reason for enabling writes (required for audit trail)" } }, "type": "object", "required": [ "reason" ], "title": "EnableWritesRequest", "description": "Request schema for enabling write operations on a blueprint.\n\nWrite mode is disabled by default (read-only). This request enables\nwrite operations with explicit user confirmation." }, "ErrorAction": { "properties": { "action": { "type": "string", "title": "Action", "description": "Action type: retry, goto, pause, fail, skip" }, "target": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target", "description": "Target step for goto action" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message", "description": "Message for pause/fail actions" }, "wait": { "anyOf": [ { "type": "string", "pattern": "^\\d+[smh]$" }, { "type": "null" } ], "title": "Wait", "description": "Wait duration" }, "max_attempts": { "anyOf": [ { "type": "integer", "minimum": 1.0 }, { "type": "null" } ], "title": "Max Attempts" }, "pass_error": { "type": "boolean", "title": "Pass Error", "default": false } }, "additionalProperties": false, "type": "object", "required": [ "action" ], "title": "ErrorAction", "description": "Action to take on error." }, "ErrorEnvelope": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "code", "message" ], "properties": { "type": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string", "nullable": true }, "retry_after_seconds": { "type": "integer", "nullable": true } } } } }, "EvidenceDecisionRequest": { "properties": { "reference_id": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Reference Id" }, "step_id": { "type": "string", "maxLength": 200, "title": "Step Id", "description": "The emitting step (as returned on the evidence slice).", "default": "" }, "decision": { "type": "string", "enum": [ "accepted", "query_source", "superseded", "resolved_no_change" ], "title": "Decision" }, "note": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Note", "description": "The human 'why' \u2014 recorded verbatim on the decision trail." } }, "type": "object", "required": [ "reference_id", "decision" ], "title": "ApiRoutersWorkstreamsModels__EvidenceDecisionRequest", "description": "A person's gate decision on one tie-register row (References v1\ninvariant 6: 'agreed' is written only by a person via the gate). The\ndecision APPENDS to the decision log; the engine's register row is\nnever rewritten.", "example": { "decision": "accepted", "note": "Rely on the custodian's pooled book cost; basis noted on file.", "reference_id": "ref-1a2b3c4d5e", "step_id": "fill_chargeable_gains" } }, "EvidenceDecisionResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "step_id": { "type": "string", "title": "Step Id" }, "reference_id": { "type": "string", "title": "Reference Id" }, "decision": { "type": "string", "title": "Decision" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Note" }, "decided_by": { "type": "string", "title": "Decided By" }, "decided_by_name": { "type": "string", "title": "Decided By Name", "default": "" }, "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "At" } }, "type": "object", "required": [ "id", "step_id", "reference_id", "decision", "decided_by" ], "title": "ApiRoutersWorkstreamsModels__EvidenceDecisionResponse", "description": "The appended decision, as it now rides on the evidence slice." }, "EvidenceSignRequest": { "properties": { "note": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Note", "description": "Optional signing note \u2014 recorded verbatim on the seal." } }, "type": "object", "title": "ApiRoutersWorkstreamsModels__EvidenceSignRequest", "description": "Sign-and-seal the cycle's evidence register (References v1). Refused\n(409) while any \u2691 query lacks a gate decision \u2014 nothing is ticked\nwithout a trace. Signing appends an identity-backed seal (the register\ncontent hash over the slice INCLUDING the decision trail) and writes the\nsign-off block into a NEW copy of the cycle's final workbook artifact.", "example": { "note": "Reviewed with the D Ltd file \u2014 numbers rec." } }, "EvidenceSignoffResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "signed_by": { "type": "string", "title": "Signed By" }, "signed_by_name": { "type": "string", "title": "Signed By Name", "default": "" }, "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "At" }, "register_hash": { "type": "string", "title": "Register Hash" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Note" }, "source_artifact_file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Artifact File Id" }, "signed_artifact_file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signed Artifact File Id" }, "sealed_line": { "type": "string", "title": "Sealed Line", "default": "" }, "block_sheet": { "type": "string", "title": "Block Sheet", "default": "" }, "block_rows": { "prefixItems": [ { "type": "integer" }, { "type": "integer" } ], "type": "array", "maxItems": 2, "minItems": 2, "title": "Block Rows", "default": [ 0, 0 ] }, "protected_sheets": { "items": { "type": "string" }, "type": "array", "title": "Protected Sheets" } }, "type": "object", "required": [ "id", "signed_by", "register_hash" ], "title": "ApiRoutersWorkstreamsModels__EvidenceSignoffResponse", "description": "The appended seal, as `GET /evidence` now reports it in `signoff`." }, "ExecutionLogCategory": { "type": "string", "enum": [ "planning", "extraction", "validation", "transformation", "integration", "approval", "checkpoint", "rollback", "system" ], "title": "ExecutionLogCategory", "description": "Category of execution log entry." }, "ExecutionLogEntry": { "properties": { "id": { "type": "string", "title": "Id", "description": "Log entry ID" }, "timestamp": { "type": "string", "format": "date-time", "title": "Timestamp", "description": "When the entry was created" }, "level": { "$ref": "#/components/schemas/ExecutionLogLevel", "description": "Log level" }, "category": { "$ref": "#/components/schemas/ExecutionLogCategory", "description": "Log category" }, "message": { "type": "string", "title": "Message", "description": "Log message" }, "parent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Id", "description": "Parent entry ID for nested structure" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata", "description": "Additional context" }, "progress": { "anyOf": [ { "$ref": "#/components/schemas/ProgressInfoResponse" }, { "type": "null" } ], "description": "Progress info for batch ops" }, "actor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Actor", "description": "Agent/component that generated this" } }, "type": "object", "required": [ "id", "timestamp", "level", "category", "message" ], "title": "ExecutionLogEntry", "description": "A single execution log entry (Chain of Thought)." }, "ExecutionLogLevel": { "type": "string", "enum": [ "debug", "info", "warning", "error" ], "title": "ExecutionLogLevel", "description": "Log level for execution entries." }, "ExecutionLogResponse": { "properties": { "cycle_id": { "type": "string", "format": "uuid", "title": "Cycle Id", "description": "Cycle UUID" }, "task_id": { "type": "string", "format": "uuid", "title": "Task Id", "description": "Task UUID" }, "entries": { "items": { "$ref": "#/components/schemas/ExecutionLogEntry" }, "type": "array", "title": "Entries", "description": "Log entries" }, "total": { "type": "integer", "minimum": 0.0, "title": "Total", "description": "Total entries matching query" }, "limit": { "type": "integer", "title": "Limit", "description": "Requested limit" }, "offset": { "type": "integer", "title": "Offset", "description": "Requested offset" }, "has_more": { "type": "boolean", "title": "Has More", "description": "Whether more entries exist" } }, "type": "object", "required": [ "cycle_id", "task_id", "total", "limit", "offset", "has_more" ], "title": "ExecutionLogResponse", "description": "Response model for execution log queries." }, "ExecutionLogSummary": { "properties": { "cycle_id": { "type": "string", "format": "uuid", "title": "Cycle Id", "description": "Cycle UUID" }, "task_id": { "type": "string", "format": "uuid", "title": "Task Id", "description": "Task UUID" }, "total_entries": { "type": "integer", "minimum": 0.0, "title": "Total Entries", "description": "Total log entries" }, "by_level": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "By Level", "description": "Counts by level" }, "by_category": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "By Category", "description": "Counts by category" }, "first_entry_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "First Entry At", "description": "First entry timestamp" }, "last_entry_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Entry At", "description": "Last entry timestamp" }, "duration_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Duration Ms", "description": "Duration from first to last entry" }, "error_count": { "type": "integer", "minimum": 0.0, "title": "Error Count", "description": "Error count", "default": 0 }, "warning_count": { "type": "integer", "minimum": 0.0, "title": "Warning Count", "description": "Warning count", "default": 0 } }, "type": "object", "required": [ "cycle_id", "task_id", "total_entries" ], "title": "ExecutionLogSummary", "description": "Summary statistics for execution logs." }, "FanOutRequest": { "properties": { "period": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Period", "description": "Period label (e.g. '2026-01')" }, "client_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Client Ids", "description": "Override target_selector with specific client IDs" }, "input_data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Input Data", "description": "Declared-input parameter values (e.g. a file input's platform.file_uploads id, or a plain text/number param). Applies identically to every fanned-out client \u2014 merged into each cycle's context at the highest precedence, above the job's default_context and per-client overrides." } }, "type": "object", "title": "FanOutRequest", "description": "Request to fan out a job across clients." }, "FanOutResponse": { "properties": { "job_definition_id": { "type": "string", "title": "Job Definition Id" }, "job_permakey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Job Permakey", "description": "Job (WorkPlan) permakey - the PLAN's stable reference. NOT the cycle address: a plan permakey in the cycle slot is the bug this card closes. Kept for the workplan deep-link / fleet grouping only." }, "cycle_launch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cycle Launch Id", "description": "The cycle_launch (the product's Cycle - one launch of a plan) this fan-out minted. The launch's OWN permakey (cycle_launch_permakey) is the canonical cycle address the launcher navigates to directly (/workstreams/{ws}/cycles/{launch_permakey}), with NO redirect - card 'Every link the app emits uses the cycle's own address'. Null on the early-return path that never mints (no clients / job not found)." }, "cycle_launch_permakey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cycle Launch Permakey", "description": "The cycle_launch's stable permakey - the canonical CYCLE address. The post-create navigation lands here DIRECTLY (no redirect). Null only when no launch was minted; the launcher then falls back to job_permakey, which the flat cycle-slot resolver redirects to the workplan URL so the row never dead-ends." }, "total_clients": { "type": "integer", "title": "Total Clients" }, "cycles_created": { "type": "integer", "title": "Cycles Created" }, "cycles_failed": { "type": "integer", "title": "Cycles Failed" }, "cycles": { "items": { "additionalProperties": { "type": "string" }, "type": "object" }, "type": "array", "title": "Cycles" }, "errors": { "items": { "additionalProperties": { "type": "string" }, "type": "object" }, "type": "array", "title": "Errors" } }, "type": "object", "required": [ "job_definition_id", "total_clients", "cycles_created", "cycles_failed", "cycles", "errors" ], "title": "FanOutResponse", "description": "Fan-out result." }, "FileStepDefinition": { "properties": { "id": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9_-]+$", "title": "Id" }, "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name" }, "type": { "type": "string", "const": "file", "title": "Type", "default": "file" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "depends_on": { "items": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" } ] }, "type": "array", "title": "Depends On" }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stage" }, "timeout": { "anyOf": [ { "type": "string", "pattern": "^\\d+[smhd]$" }, { "type": "null" } ], "title": "Timeout" }, "retry_policy": { "anyOf": [ { "$ref": "#/components/schemas/RetryPolicy" }, { "type": "null" } ] }, "error_handler": { "anyOf": [ { "$ref": "#/components/schemas/StepErrorHandler" }, { "type": "null" } ] }, "emit_artifact": { "anyOf": [ { "$ref": "#/components/schemas/EmitArtifactSpec" }, { "type": "null" } ] }, "optional": { "type": "boolean", "title": "Optional", "default": false }, "continue_on_error": { "type": "boolean", "title": "Continue On Error", "default": false }, "halt_conditions": { "items": { "$ref": "#/components/schemas/HaltCondition" }, "type": "array", "title": "Halt Conditions" }, "parameters": { "items": { "$ref": "#/components/schemas/StepParameter" }, "type": "array", "title": "Parameters" }, "guards": { "items": { "$ref": "#/components/schemas/StepGuard" }, "type": "array", "title": "Guards" }, "impact_level": { "$ref": "#/components/schemas/ImpactLevel", "default": "medium" }, "run_mode": { "$ref": "#/components/schemas/RunMode", "default": "propose" }, "requires_approval": { "type": "boolean", "title": "Requires Approval", "default": false }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "examples": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StepExample" }, "type": "array" }, { "type": "null" } ], "title": "Examples", "description": "Attached example files for this step. Each entry pairs a platform.file_uploads.file_id with a role + tags + notes so the runtime can shape its instruction. Bounded at 20 to keep a reasonable upper limit on the prompt preamble." }, "applies_when": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applies When", "description": "CEL predicate evaluated at MATERIALIZATION (not at step execution): the step is marked skipped when it evaluates False. Stored verbatim \u2014 the expression is parsed by celpy at launch, so any coercion here would change its meaning." }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "Categorical labels on the step itself (e.g. 'pdf-read', 'coutts', 'fy25'). Free-form; recommended tag set is documented per workstream surface." }, "instruction": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instruction", "description": "Natural-language instruction, Jinja2-rendered before execution" }, "expected_outputs": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Expected Outputs", "description": "Declared output shape, used by the lint's output-reference checks" }, "file_op": { "type": "string", "enum": [ "write", "download_url", "read_artifact", "read_upload", "transform" ], "title": "File Op", "description": "Which file operation to perform" }, "file_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Url", "description": "Source URL for file_op=download_url" }, "from_artifact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From Artifact Id", "description": "cycle_artifact id \u2014 a workflow-GENERATED output (read_artifact)" }, "file_upload_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Upload Id", "description": "platform.file_uploads id \u2014 a HUMAN-uploaded file (read_upload)" }, "artifact_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Artifact Name", "description": "Name for a written artifact" }, "artifact_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Artifact Type", "description": "Artifact type tag" }, "transform": { "anyOf": [ { "type": "string", "enum": [ "base64_encode", "csv_to_json", "json_to_csv" ] }, { "type": "null" } ], "title": "Transform", "description": "Transformation to apply for file_op=transform" } }, "additionalProperties": false, "type": "object", "required": [ "id", "name", "file_op" ], "title": "FileStepDefinition", "description": "File step \u2014 artifact-aware file operations.\n\n``file_op`` selects the sub-mode, and the operands differ per mode, which is\nwhy they are all optional here and validated per-mode below rather than by\ndeclaring five near-identical step types.\n\nNote ``from_artifact_id`` and ``file_upload_id`` are NOT interchangeable:\nthe former is a ``workstreams.cycle_artifact`` (something a cycle produced),\nthe latter a ``platform.file_uploads`` id (something a human uploaded).\nConfusing them is a documented past defect (issue f96491b9)." }, "ForkCycleRequest": { "properties": { "input_data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Input Data", "description": "Optional override of the new cycle's runtime_vars. When omitted, the donor's input_data is preserved verbatim. Any key changed here that a step's instruction substitutes via Jinja flips that step's content key, so it (and its dependents) re-run instead of seeding." } }, "type": "object", "title": "ApiRoutersWorkstreamsModels__ForkCycleRequest", "description": "Request to fork an existing terminal cycle into a new one.", "example": { "input_data": { "period": "2026-02" } } }, "ForkCycleResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Cycle UUID" }, "permakey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Permakey", "description": "Stable human-readable cycle key for the deep-link URL /workstreams/{ws}/cycles/{permakey}/instance/{task}. Null on legacy rows." }, "workstream_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Workstream Id", "description": "Parent workstream UUID. Populated for every cycle launched against a workstream definition; only null for legacy agentic/v2 cycles that have no workstream parent." }, "workstream_permakey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workstream Permakey", "description": "Parent workstream's stable human-readable key (workstreams.workstream.permakey), resolved by joining on the same COALESCE(cycle.workstream_id, blueprint.workstream_id) that backs workstream_id. Lets the list/detail surfaces build the permakey-prefixed deep link /workstreams/{workstream_permakey}/cycles/{permakey} without a second fetch. Null when no workstream parent resolves (legacy agentic/v2 cycles, or a workstream that no longer exists)." }, "workstream_slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workstream Slug", "description": "Parent workstream's URL slug (workstreams.workstream.slug), resolved via the same join as workstream_permakey. Null when no workstream parent resolves." }, "workstream_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Workstream Version", "description": "The WorkStream version this cycle executed \u2014 stamped at launch from workstreams.workstream.version (or the pinned version on a WorkPlan). Immutable after launch. Null on legacy cycles that predate the column or have no workstream parent." }, "cycle_launch_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Cycle Launch Id", "description": "The cycle_launch (the product's Cycle - one launch of a plan) this instance (per-client cycle row) belongs to. Card 'Cycle URLs open cycles, WorkPlan URLs open WorkPlans': an instance nests under its cycle (/workstreams/{ws}/cycles/{cycle}/instances/{instance}), and the cycle segment is the cycle_launch's permakey. Null on legacy rows that predate the backfill (20260902_0100)." }, "cycle_launch_permakey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cycle Launch Permakey", "description": "The cycle_launch's stable permakey - the canonical cycle URL segment the instance nests under. Lets the instance page build its breadcrumb cycle crumb (/workstreams/{ws}/cycles/{cycle}) without a second fetch. Null when the instance has no parent launch (a pre-backfill orphan)." }, "definition_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Definition Hash", "description": "Content-addressed definition hash \u2014 nullable placeholder for the content-addressing substrate (not yet landed). Distinct from code_sha (the launching-code git SHA used by the deploy-race guard). Always null until that design ships." }, "workplan_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Workplan Id", "description": "Workplan UUID (null for agentic cycles)" }, "workplan_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workplan Name", "description": "Workplan name (from join)" }, "client_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Client Id", "description": "Client UUID (from workplan join)" }, "client_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Name", "description": "Client name (from workplan join)" }, "status": { "$ref": "#/components/schemas/CycleStatus", "description": "Cycle status" }, "progress_pct": { "type": "number", "maximum": 100.0, "minimum": 0.0, "title": "Progress Pct", "description": "`completed_steps / total_steps * 100` \u2014 work that RAN AND FINISHED, over the whole ladder. Skipped steps are excluded from the numerator and stay in the denominator, so a run that stopped early can never reach 100%. It is a record of how far the run got, not a live fraction: pair it with `status` and `current_step_index` before rendering, and never read it alone as 'nearly done'.", "default": 0.0 }, "blueprint_snapshot": { "additionalProperties": true, "type": "object", "title": "Blueprint Snapshot", "description": "Workplan snapshot at cycle start" }, "error_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Error Context", "description": "Error context if failed" }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Started At", "description": "Start timestamp" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Completed At", "description": "Completion timestamp" }, "started_by": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Started By", "description": "Initiator user ID (started_by in DB)" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Last update timestamp" }, "current_step_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Current Step Name", "description": "Name of the ONE current step every FE view should render verbatim (banner, Steps tab, Approvals tab, batch matrix). Resolved by _compute_run_progress: the earliest in-flight/awaiting step, else (when the cycle has failed) the last failed step. Never the literal 'Unknown' \u2014 an unnamed step falls back to a humanized blueprint step id or 'Step N'. Null only when no step can be resolved at all (e.g. a cycle with zero tasks)." }, "current_step_index": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Current Step Index", "description": "1-based position of current_step_name within the cycle's steps. Null exactly when current_step_name is null \u2014 the two are always resolved together so a view never pairs a real index with a missing name (or vice versa) \u2014 see pilot run-through defect B1 ('Step 0: Unknown')." }, "failure_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Failure Reason", "description": "Human-readable reason the run is errored/blocked, populated whenever status is failed/cancelled/blocked \u2014 even when no current step could be resolved (e.g. 'The run stopped before any step could be identified.'). FE should show this INSTEAD OF a step placeholder, never alongside a fabricated 'Step ?'. Written for an accountant: no step ids, no raw floats where money is meant, no internal certification vocabulary. The engine's or the approver's own words are on failure_details." }, "failure_details": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Failure Details", "description": "The engine's or the approver's own words, verbatim and unshortened, behind the surface's Details affordance. NEVER rendered inline \u2014 failure_reason is the sentence a person reads. Null when the reason IS already the whole of what was recorded." }, "retryable": { "type": "boolean", "title": "Retryable", "description": "Whether a Retry action applies to this run (status is failed/cancelled).", "default": false }, "needs_approval": { "type": "boolean", "title": "Needs Approval", "description": "True when this run is parked on a human sign-off nobody has given yet: a task with approved_at NULL that is awaiting_approval (by status or by outputs.status), on a cycle that is not already over. Same predicate as the swarm/jobs read, so a run cannot report differently depending on which endpoint served it. The FE pairs it with `status` to choose the amber 'Needs you' pill over the grey 'Blocked' one \u2014 a blocked cycle with no open gate is genuinely just blocked.", "default": false }, "held_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Held Reason", "description": "Why this run is WAITING, composed for an accountant from the cycle's OWN measured outputs \u2014 several short lines: what is happening, whose work it is, the amount as money, where it is written down, and what un-blocks it. Populated from the HOLD STATE (an approval gate with approved_at NULL, parked at awaiting_approval, on a cycle that is not over) \u2014 never by parsing a rejection string, which a held run does not have. A hold is NOT a failure: it never populates `failure_reason` and never writes cycle.error_context." }, "held_details": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Held Details", "description": "The reviewer's own words for the hold (workstreams.task.outputs.hold_metadata.question on the parked gate), verbatim and unshortened, for a Details affordance. Never rendered inline and never mined for facts \u2014 every figure in `held_reason` comes from a step's own recorded output." }, "completed_steps": { "type": "integer", "minimum": 0.0, "title": "Completed Steps", "description": "Steps that RAN AND FINISHED (completed/approved/done). Skipped steps are NOT counted here \u2014 they never ran. Card #263: until this field was corrected, a run halted at step 7 of 18 with the remaining steps skipped reported 16 of 18 and rendered a nearly-full bar. Read together with `skipped_steps` and `current_step_index`, which say how far the run actually got and where it stopped.", "default": 0 }, "skipped_steps": { "type": "integer", "minimum": 0.0, "title": "Skipped Steps", "description": "Steps that NEVER RAN \u2014 the run stopped upstream, or a condition excluded them. Not progress and not failure: reported in its own right so a refusal reads as a refusal. `completed_steps + skipped_steps` is NOT a progress figure and must never be rendered as one; the pair exists precisely so the two are not added together again.", "default": 0 }, "total_steps": { "type": "integer", "minimum": 0.0, "title": "Total Steps", "description": "Total number of steps in cycle", "default": 0 }, "customer_cost_gbp": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Customer Cost Gbp", "description": "Customer-facing cost in GBP: \u00a319/hr x elapsed time since cycle start. NULL when the cycle has not yet started. Uses completed_at if available, otherwise current wall-clock time. The real compute cost is never served (CR-COST-01)." }, "tokens_total_input": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tokens Total Input", "description": "Total input tokens across all steps. NULL when none recorded." }, "tokens_total_output": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tokens Total Output", "description": "Total output tokens across all steps. NULL when none recorded." }, "artifacts": { "items": { "$ref": "#/components/schemas/CycleArtifactSummary" }, "type": "array", "title": "Artifacts", "description": "Artifacts produced by this cycle (workstreams.cycle_artifact, non-deleted), newest first, each with a download_url. Surfaced at CYCLE level \u2014 step\u2192artifact attribution is a follow-up. Empty when the cycle produced no artifacts." }, "workbook": { "$ref": "#/components/schemas/CycleWorkbookRef", "description": "The workbook a run produced, with its review state (card 011). Derived server-side from the latest fill/compile step's ``outputs.document_id`` and the run-level sign-off record \u2014 the frontend renders the Workbook tab from this field, not from a guess at step outputs. ``not_yet_reviewed`` makes the workbook VISIBLE (a reviewer must see it to review it) while the download stays 409-gated until the gate passes." }, "input_data": { "additionalProperties": true, "type": "object", "title": "Input Data", "description": "Launch inputs the cycle was started with (period, file refs, run_mode, etc.), read from workstreams.cycle.runtime_vars \u2014 the canonical input dict written verbatim on both the inline and containerized launch paths. Empty when the cycle has no recorded launch inputs. Within-workspace only (the endpoint is FGA- + workspace-scoped); redact file names / conversation_id before surfacing this on any cross-org surface." }, "parent_cycle_id": { "type": "string", "format": "uuid", "title": "Parent Cycle Id", "description": "The donor cycle this was forked from" }, "seeded_steps": { "items": { "type": "string" }, "type": "array", "title": "Seeded Steps", "description": "Step ids whose outputs were seeded from the donor (skipped, no cost)." }, "dirty_steps": { "items": { "type": "string" }, "type": "array", "title": "Dirty Steps", "description": "Step ids that will re-execute (changed/side-effect/transitively dirty)." } }, "type": "object", "required": [ "id", "status", "created_at", "updated_at", "parent_cycle_id" ], "title": "ApiRoutersWorkstreamsModels__ForkCycleResponse", "description": "Fork response: the new cycle plus the seedability economics.\n\n``seeded_steps`` re-used the donor's banked outputs (no LLM cost paid);\n``dirty_steps`` will re-execute (content-key mismatch, side-effect type,\nor transitive dirtiness from a dirty upstream). Callers read the split to\nsee exactly how much of the run the fork saved." }, "FormStepDefinition": { "properties": { "id": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9_-]+$", "title": "Id" }, "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name" }, "type": { "type": "string", "const": "form", "title": "Type", "default": "form" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "depends_on": { "items": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" } ] }, "type": "array", "title": "Depends On" }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stage" }, "timeout": { "anyOf": [ { "type": "string", "pattern": "^\\d+[smhd]$" }, { "type": "null" } ], "title": "Timeout" }, "retry_policy": { "anyOf": [ { "$ref": "#/components/schemas/RetryPolicy" }, { "type": "null" } ] }, "error_handler": { "anyOf": [ { "$ref": "#/components/schemas/StepErrorHandler" }, { "type": "null" } ] }, "emit_artifact": { "anyOf": [ { "$ref": "#/components/schemas/EmitArtifactSpec" }, { "type": "null" } ] }, "optional": { "type": "boolean", "title": "Optional", "default": false }, "continue_on_error": { "type": "boolean", "title": "Continue On Error", "default": false }, "halt_conditions": { "items": { "$ref": "#/components/schemas/HaltCondition" }, "type": "array", "title": "Halt Conditions" }, "parameters": { "items": { "$ref": "#/components/schemas/StepParameter" }, "type": "array", "title": "Parameters" }, "guards": { "items": { "$ref": "#/components/schemas/StepGuard" }, "type": "array", "title": "Guards" }, "impact_level": { "$ref": "#/components/schemas/ImpactLevel", "default": "medium" }, "run_mode": { "$ref": "#/components/schemas/RunMode", "default": "propose" }, "requires_approval": { "type": "boolean", "title": "Requires Approval", "default": false }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "examples": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StepExample" }, "type": "array" }, { "type": "null" } ], "title": "Examples", "description": "Attached example files for this step. Each entry pairs a platform.file_uploads.file_id with a role + tags + notes so the runtime can shape its instruction. Bounded at 20 to keep a reasonable upper limit on the prompt preamble." }, "applies_when": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applies When", "description": "CEL predicate evaluated at MATERIALIZATION (not at step execution): the step is marked skipped when it evaluates False. Stored verbatim \u2014 the expression is parsed by celpy at launch, so any coercion here would change its meaning." }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "Categorical labels on the step itself (e.g. 'pdf-read', 'coutts', 'fy25'). Free-form; recommended tag set is documented per workstream surface." }, "instruction": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instruction", "description": "Natural-language instruction, Jinja2-rendered before execution" }, "expected_outputs": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Expected Outputs", "description": "Declared output shape, used by the lint's output-reference checks" }, "form_schema": { "additionalProperties": true, "type": "object", "title": "Form Schema", "description": "JSON Schema for the requested input (object with properties)" }, "form_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Form Title", "description": "Title shown above the form" }, "form_description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Form Description", "description": "Explanatory copy for the reviewer" }, "form_recipients": { "items": { "type": "string" }, "type": "array", "title": "Form Recipients", "description": "Who may complete it. Empty = any authorised reviewer." } }, "additionalProperties": false, "type": "object", "required": [ "id", "name", "form_schema" ], "title": "FormStepDefinition", "description": "Form step \u2014 pause for structured human input.\n\nWrites a ``workstreams.cycle_pending_form`` row and holds the workflow until\na ``submit_form`` signal arrives, so this is a genuine human-in-the-loop\ngate rather than a notification. ``form_schema`` is JSON Schema; the native\nrenderer walks its nested properties." }, "GateEvent": { "properties": { "action": { "type": "string", "enum": [ "approve", "reject", "hold", "resume" ], "title": "Action" }, "actor_id": { "type": "string", "title": "Actor Id" }, "actor_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Actor Name" }, "at": { "type": "string", "format": "date-time", "title": "At" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Note" }, "held_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Held At" } }, "type": "object", "required": [ "action", "actor_id", "at" ], "title": "GateEvent" }, "GenerateFromDescriptionRequest": { "properties": { "description": { "type": "string", "maxLength": 2000, "minLength": 10, "title": "Description" }, "category_hint": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ], "title": "Category Hint" } }, "type": "object", "required": [ "description" ], "title": "GenerateFromDescriptionRequest", "description": "Request to generate a workstream from natural language." }, "GeneratePlanRequest": { "properties": { "include_context": { "type": "boolean", "title": "Include Context", "description": "Whether to include additional context from previous cycles", "default": true }, "force_regenerate": { "type": "boolean", "title": "Force Regenerate", "description": "Whether to regenerate plan even if one already exists", "default": false } }, "type": "object", "title": "GeneratePlanRequest", "description": "Request schema for generating a task execution plan." }, "GeneratePlanResponse": { "properties": { "success": { "type": "boolean", "title": "Success", "description": "Whether plan generation succeeded" }, "plan": { "anyOf": [ { "$ref": "#/components/schemas/TaskPlan" }, { "type": "null" } ], "description": "Generated task plan" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Error message if generation failed" }, "cached": { "type": "boolean", "title": "Cached", "description": "Whether this plan was retrieved from cache rather than generated", "default": false }, "generation_time_ms": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Generation Time Ms", "description": "Time taken to generate the plan in milliseconds" } }, "type": "object", "required": [ "success" ], "title": "GeneratePlanResponse", "description": "Response schema for plan generation endpoint." }, "GenerateStepFromDescriptionContext": { "properties": { "workstream_id": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "title": "Workstream Id" }, "step_id": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "title": "Step Id" }, "preceding_step_ids": { "items": { "type": "string" }, "type": "array", "maxItems": 32, "title": "Preceding Step Ids" }, "available_tools": { "items": { "type": "string" }, "type": "array", "maxItems": 64, "title": "Available Tools" }, "existing_step": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Existing Step", "description": "Current step definition \u2014 lets the LLM modify incrementally rather than generating from scratch (preserves type, tool_name, etc.)." } }, "type": "object", "title": "GenerateStepFromDescriptionContext", "description": "Optional context for step-scope generation. Mirrors the service-\nlayer ``GenerateStepContext`` model but lives on the router so the\nOpenAPI snapshot doesn't pull a service-internal class into the\npublic schema graph." }, "GenerateStepFromDescriptionRequest": { "properties": { "step_description": { "type": "string", "maxLength": 2000, "minLength": 5, "title": "Step Description" }, "context": { "anyOf": [ { "$ref": "#/components/schemas/GenerateStepFromDescriptionContext" }, { "type": "null" } ] } }, "type": "object", "required": [ "step_description" ], "title": "GenerateStepFromDescriptionRequest", "description": "Request to (re)generate a single workstream step from natural language." }, "GoalCell": { "properties": { "key": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Key", "description": "Stable cell identifier" }, "path": { "type": "string", "maxLength": 500, "minLength": 1, "title": "Path", "description": "Dotted path resolved as .[.\u2026] \u2014 the FIRST segment is the step id, not a field. 'vat_reconciliation.control_balance' means field control_balance of step vat_reconciliation. Getting this wrong yields got=None and delta=None rather than an error, so the cell simply never passes." }, "expected": { "type": "number", "title": "Expected", "description": "The gold value this cell must reproduce" }, "tolerance_abs": { "anyOf": [ { "type": "number", "minimum": 0.0 }, { "type": "null" } ], "title": "Tolerance Abs", "description": "Absolute tolerance. Takes precedence over tolerance_pct." }, "tolerance_pct": { "anyOf": [ { "type": "number", "minimum": 0.0 }, { "type": "null" } ], "title": "Tolerance Pct", "description": "Tolerance in PERCENT units (0.5 means 0.5%)" } }, "additionalProperties": false, "type": "object", "required": [ "key", "path", "expected" ], "title": "GoalCell", "description": "One numeric target the deterministic goal gate checks.\n\nField-for-field the contract ``evaluate_goal_gate`` already reads\n(``apps/api/src/wss/authoring/goal_gate.py``) \u2014 this model exists to make\nthat contract authorable over HTTP, NOT to restate it. Two details are\nload-bearing and easy to get wrong:\n\n* ``tolerance_pct`` is in PERCENT units: ``0.5`` means 0.5%, not 0.5.\n* declaring NEITHER tolerance means exact-to-the-penny, which the gate\n enforces with its own epsilon. That is a real choice, so it is allowed.\n\n``tolerance_abs`` wins when both are given \u2014 the same precedence the gate\napplies, kept here so the API cannot promise something the gate ignores.\n\n``extra=\"forbid\"`` belongs HERE, not only on the enclosing payload: a\nmisspelled ``tolerence_abs`` inside a cell is otherwise dropped in silence\nand the cell falls back to exact-to-the-penny, so the author's declared\ntolerance vanishes without an error. Caught doing exactly that during the\nE2E for this change (PATCH returned 200 and persisted a tolerance-free\ncell), which is the \"never silently widened\" guardrail failing closed in\nthe wrong direction." }, "GoalSpecPayload": { "properties": { "intent": { "type": "string", "maxLength": 2000, "minLength": 1, "title": "Intent", "description": "What reaching this goal means, in prose" }, "target": { "$ref": "#/components/schemas/GoalTarget", "description": "The cells that must match, plus invariants" }, "success_threshold": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Success Threshold", "description": "Fraction of cells that must pass. Omitted/null means 1.0 (all cells). 0 is honoured as an informational gate, matching the gate's own reading." }, "source": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Source", "description": "Provenance of the expected values \u2014 which document/sheet they were extracted from, when, and by whom. Never invented." } }, "additionalProperties": false, "type": "object", "required": [ "intent", "target" ], "title": "GoalSpecPayload", "description": "An authorable goal contract for ``workstreams.workstream.goal_spec``.\n\nThe column, three readers and a copier shipped in June (migration\n20260613_0200); nothing could WRITE it, so the only way to set a goal was\nraw SQL and the sole HTTP-level run-report test asserts ``no_goal``. This\npayload closes that gap.\n\n``extra=\"forbid\"`` deliberately: a typo'd tolerance key that silently\ndropped would widen a tolerance without anyone seeing it, which is exactly\nwhat the card's \"never silently widened\" guardrail forbids." }, "GoalSpecPayload-Output": { "properties": { "intent": { "type": "string", "maxLength": 2000, "minLength": 1, "title": "Intent", "description": "What reaching this goal means, in prose" }, "target": { "$ref": "#/components/schemas/GoalTarget", "description": "The cells that must match, plus invariants" }, "success_threshold": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Success Threshold", "description": "Fraction of cells that must pass. Omitted/null means 1.0 (all cells). 0 is honoured as an informational gate, matching the gate's own reading." }, "source": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Source", "description": "Provenance of the expected values \u2014 which document/sheet they were extracted from, when, and by whom. Never invented." } }, "additionalProperties": false, "type": "object", "required": [ "intent", "target" ], "title": "GoalSpecPayload", "description": "An authorable goal contract for ``workstreams.workstream.goal_spec``.\n\nThe column, three readers and a copier shipped in June (migration\n20260613_0200); nothing could WRITE it, so the only way to set a goal was\nraw SQL and the sole HTTP-level run-report test asserts ``no_goal``. This\npayload closes that gap.\n\n``extra=\"forbid\"`` deliberately: a typo'd tolerance key that silently\ndropped would widen a tolerance without anyone seeing it, which is exactly\nwhat the card's \"never silently widened\" guardrail forbids." }, "GoalTarget": { "properties": { "cells": { "items": { "$ref": "#/components/schemas/GoalCell" }, "type": "array", "minItems": 1, "title": "Cells", "description": "At least one target cell \u2014 a goal with no cells is no goal" }, "invariants": { "items": { "type": "string" }, "type": "array", "title": "Invariants", "description": "Narrative invariants for the human reviewer" } }, "additionalProperties": false, "type": "object", "required": [ "cells" ], "title": "GoalTarget", "description": "The cells and invariants that define 'achieved'." }, "GotoStepDefinition": { "properties": { "id": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9_-]+$", "title": "Id" }, "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name" }, "type": { "type": "string", "const": "goto", "title": "Type", "default": "goto" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "depends_on": { "items": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" } ] }, "type": "array", "title": "Depends On" }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stage" }, "timeout": { "anyOf": [ { "type": "string", "pattern": "^\\d+[smhd]$" }, { "type": "null" } ], "title": "Timeout" }, "retry_policy": { "anyOf": [ { "$ref": "#/components/schemas/RetryPolicy" }, { "type": "null" } ] }, "error_handler": { "anyOf": [ { "$ref": "#/components/schemas/StepErrorHandler" }, { "type": "null" } ] }, "emit_artifact": { "anyOf": [ { "$ref": "#/components/schemas/EmitArtifactSpec" }, { "type": "null" } ] }, "optional": { "type": "boolean", "title": "Optional", "default": false }, "continue_on_error": { "type": "boolean", "title": "Continue On Error", "default": false }, "halt_conditions": { "items": { "$ref": "#/components/schemas/HaltCondition" }, "type": "array", "title": "Halt Conditions" }, "parameters": { "items": { "$ref": "#/components/schemas/StepParameter" }, "type": "array", "title": "Parameters" }, "guards": { "items": { "$ref": "#/components/schemas/StepGuard" }, "type": "array", "title": "Guards" }, "impact_level": { "$ref": "#/components/schemas/ImpactLevel", "default": "medium" }, "run_mode": { "$ref": "#/components/schemas/RunMode", "default": "propose" }, "requires_approval": { "type": "boolean", "title": "Requires Approval", "default": false }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "examples": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StepExample" }, "type": "array" }, { "type": "null" } ], "title": "Examples", "description": "Attached example files for this step. Each entry pairs a platform.file_uploads.file_id with a role + tags + notes so the runtime can shape its instruction. Bounded at 20 to keep a reasonable upper limit on the prompt preamble." }, "applies_when": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applies When", "description": "CEL predicate evaluated at MATERIALIZATION (not at step execution): the step is marked skipped when it evaluates False. Stored verbatim \u2014 the expression is parsed by celpy at launch, so any coercion here would change its meaning." }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "Categorical labels on the step itself (e.g. 'pdf-read', 'coutts', 'fy25'). Free-form; recommended tag set is documented per workstream surface." }, "target": { "type": "string", "title": "Target", "description": "Target step ID" }, "condition": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Condition", "description": "Optional condition for jump" } }, "additionalProperties": false, "type": "object", "required": [ "id", "name", "target" ], "title": "GotoStepDefinition", "description": "Goto step - jumps to another step." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "HaltCondition": { "properties": { "output_key": { "type": "string", "title": "Output Key", "description": "Dotted path into the step's outputs to test (e.g. 'all_passed')." }, "equals": { "anyOf": [ {}, { "type": "null" } ], "title": "Equals", "description": "Halt unless the value equals this. Mutually exclusive with in_." }, "in": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "In", "description": "Halt unless the value is in this list." }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message", "description": "Human halt reason; surfaced as the step's error_message." } }, "additionalProperties": false, "type": "object", "required": [ "output_key" ], "title": "HaltCondition", "description": "Opt-in RUNTIME halt gate (#6). When a step's declared ``output_key``\n(a dotted path into the step's outputs) fails its check, the step is\ndowngraded to ``success=False`` / ``disposition=\"halted\"`` and the cycle\nSTOPS via the existing failure path \u2014 even though the step \"ran\".\n\nThis closes the gap where a tool step's envelope hardcodes ``status=\"ok\"``\nand lifts ``all_passed`` to the top level, so an ``all_passed=False``\nverification reads as a green success and the cycle proceeds to post a\njournal that FAILED verification.\n\nCheck semantics (first that applies):\n * ``equals`` present \u2192 unmet iff ``value != equals``;\n * ``in_`` present \u2192 unmet iff ``value not in in_``;\n * else \u2192 require-truthy (unmet iff ``not value``).\n\nFAIL-CLOSED: a missing ``output_key`` or any evaluation error is treated\nas UNMET \u2192 the cycle halts. This is the deliberate INVERSE of\n``applies_when``'s materialize-time fail-OPEN (a bad ``applies_when``\nkeeps a step; a bad ``halt_condition`` stops the cycle) \u2014 a verification\ngate must never silently pass because its own signal went missing." }, "HoldRequestModel": { "properties": { "question": { "type": "string", "maxLength": 5000, "minLength": 1, "title": "Question", "description": "What the sign-off is waiting for, in plain language (e.g. 'Waiting on the client to confirm the VAT on the September purchase invoices')." } }, "type": "object", "required": [ "question" ], "title": "HoldRequestModel", "description": "Request model for holding a sign-off that cannot be given yet.\n\n``question`` is the ONE thing the reviewer is waiting for, in the words a\nclient-facing accountant would use. It is stored verbatim under\n``workstreams.task.outputs.hold_metadata`` and read back by the run view,\nso it must be plain language \u2014 never internal reasoning.", "example": { "question": "Waiting on ABC Limited to confirm the \u00a32,857.19 difference between the VAT returns and the ledger." } }, "HoldResponseModel": { "properties": { "task_id": { "type": "string", "format": "uuid", "title": "Task Id", "description": "Task UUID" }, "cycle_id": { "type": "string", "format": "uuid", "title": "Cycle Id", "description": "Cycle UUID" }, "task_status": { "type": "string", "title": "Task Status", "description": "The gate task's status, unchanged by the hold \u2014 it stays parked awaiting the sign-off that has not been given." }, "cycle_status": { "$ref": "#/components/schemas/CycleStatus", "description": "The cycle's status after the hold. `blocked` \u2014 waiting on a person, resumable, not billed, and NOT a failure." }, "held_by": { "type": "string", "format": "uuid", "title": "Held By", "description": "User who held the sign-off" }, "held_at": { "type": "string", "format": "date-time", "title": "Held At", "description": "When the sign-off was held" }, "question": { "type": "string", "title": "Question", "description": "What the sign-off is waiting for" }, "gate_record": { "anyOf": [ { "$ref": "#/components/schemas/RunGateRecord" }, { "type": "null" } ] } }, "type": "object", "required": [ "task_id", "cycle_id", "task_status", "cycle_status", "held_by", "held_at", "question" ], "title": "HoldResponseModel", "description": "Response model for a held sign-off.\n\nDeliberately NOT ``ApprovalResponseModel``: a hold has no approver and no\nrejecter, and reusing the rejection shape is how the two got conflated in\nthe first place." }, "ImpactEntry": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Entry UUID" }, "cycle_id": { "type": "string", "format": "uuid", "title": "Cycle Id", "description": "Cycle UUID" }, "task_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Task Id", "description": "Task UUID (optional)" }, "action_type": { "type": "string", "title": "Action Type", "description": "Type of action performed (operation_type)" }, "target_entity": { "type": "string", "title": "Target Entity", "description": "Target entity identifier (target_system)" }, "target_system": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target System", "description": "Target system name" }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Id", "description": "External system identifier" }, "external_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Ref", "description": "External reference (e.g., URL)" }, "attributes": { "additionalProperties": true, "type": "object", "title": "Attributes", "description": "Additional attributes" }, "is_reversible": { "type": "boolean", "title": "Is Reversible", "description": "Whether action is reversible", "default": true }, "performed_at": { "type": "string", "format": "date-time", "title": "Performed At", "description": "When action was performed (created_at)" }, "entity_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Entity Type", "description": "Entity type (e.g., journal_entry, invoice)" }, "before_state": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Before State", "description": "State before operation" }, "after_state": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "After State", "description": "State after operation" }, "reversal_instructions": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Reversal Instructions", "description": "Instructions for reversal" }, "reversal_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reversal Status", "description": "Reversal status (pending/reversed/failed)" }, "tool_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tool Name", "description": "Tool that performed this action" }, "success": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Success", "description": "Whether the operation succeeded" } }, "type": "object", "required": [ "id", "cycle_id", "action_type", "target_entity", "performed_at" ], "title": "ImpactEntry", "description": "Single entry in the impact ledger." }, "ImpactLedgerResponse": { "properties": { "cycle_id": { "type": "string", "format": "uuid", "title": "Cycle Id", "description": "Cycle UUID" }, "entries": { "items": { "$ref": "#/components/schemas/ImpactEntry" }, "type": "array", "title": "Entries", "description": "Ledger entries" }, "total_entries": { "type": "integer", "minimum": 0.0, "title": "Total Entries", "description": "Total entry count" }, "reversible_count": { "type": "integer", "minimum": 0.0, "title": "Reversible Count", "description": "Count of reversible entries" }, "summary": { "anyOf": [ { "$ref": "#/components/schemas/ImpactSummaryResponse" }, { "type": "null" } ], "description": "Aggregated summary stats" } }, "type": "object", "required": [ "cycle_id", "total_entries", "reversible_count" ], "title": "ImpactLedgerResponse", "description": "Impact ledger for a cycle." }, "ImpactLevel": { "type": "string", "enum": [ "low", "medium", "high", "critical" ], "title": "ImpactLevel", "description": "Impact classification for steps." }, "ImpactSummaryResponse": { "properties": { "by_action_type": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "By Action Type", "description": "Counts by action type" }, "by_target_system": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "By Target System", "description": "Counts by target system" }, "by_entity_type": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "By Entity Type", "description": "Counts by entity type" } }, "type": "object", "title": "ImpactSummaryResponse", "description": "Aggregated impact summary stats." }, "InputBindingDef": { "properties": { "input_name": { "type": "string", "title": "Input Name", "description": "The declared input name this binding targets (matches an InputDef.name)." }, "source_workplan_id": { "type": "string", "title": "Source Workplan Id", "description": "The upstream WorkPlan whose output feeds this input." }, "source_output_name": { "type": "string", "title": "Source Output Name", "description": "The named output on the upstream WorkPlan to bind." } }, "type": "object", "required": [ "input_name", "source_workplan_id", "source_output_name" ], "title": "InputBindingDef", "description": "Cross-WorkPlan input binding definition." }, "InputResolutionResponse": { "properties": { "workplan_id": { "type": "string", "title": "Workplan Id" }, "workstream_id": { "type": "string", "title": "Workstream Id" }, "clients": { "items": { "$ref": "#/components/schemas/ClientInputResolution" }, "type": "array", "title": "Clients" } }, "type": "object", "required": [ "workplan_id", "workstream_id", "clients" ], "title": "InputResolutionResponse", "description": "GET /workplans/{id}/input-resolution \u2014 one entry per requested client." }, "JobDefinitionCreate": { "properties": { "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name" }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Description" }, "domain": { "type": "string", "title": "Domain", "description": "Domain knowledge key (e.g. 'ita_2007_eis')" }, "goal_template": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Goal Template", "description": "Goal template with {{variable}} placeholders. OPTIONAL: when omitted (or null), it is defaulted server-side from the domain's DomainAgent persona goal_template (PERSONA_REGISTRY.for_workstream(domain)). A domain with no registered persona falls back to the DEFAULT persona's '{{ goal }}'. An explicit value is stored verbatim (back-compat)." }, "tools": { "items": { "type": "string" }, "type": "array", "title": "Tools" }, "deliverables": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Deliverables" }, "max_turns": { "type": "integer", "maximum": 500.0, "minimum": 1.0, "title": "Max Turns", "default": 150 }, "max_cost_usd": { "type": "number", "maximum": 50.0, "minimum": 0.1, "title": "Max Cost Usd", "default": 8.0 }, "max_duration_minutes": { "type": "integer", "maximum": 120.0, "minimum": 1.0, "title": "Max Duration Minutes", "default": 25 }, "target_selector": { "$ref": "#/components/schemas/TargetSelector" }, "per_client_overrides": { "additionalProperties": { "additionalProperties": true, "type": "object" }, "type": "object", "title": "Per Client Overrides" }, "input_bindings": { "additionalProperties": { "additionalProperties": { "type": "string" }, "type": "object" }, "type": "object", "title": "Input Bindings", "description": "Cross-cycle input bindings." }, "default_context": { "additionalProperties": true, "type": "object", "title": "Default Context" }, "source_tracing": { "type": "boolean", "title": "Source Tracing", "default": true }, "human_checkpoints": { "items": { "type": "string" }, "type": "array", "title": "Human Checkpoints" }, "schedule": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Schedule", "description": "Cron expression" }, "schedule_timezone": { "type": "string", "title": "Schedule Timezone", "default": "UTC" }, "skip_weekends": { "type": "boolean", "title": "Skip Weekends", "description": "Shift a fire time that lands on Sat/Sun to the next business day", "default": false }, "holiday_calendar": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Holiday Calendar", "description": "Shift a fire time landing on a holiday to the next business day: 'UK', 'US', or 'AU'" }, "not_ready_policy": { "type": "string", "title": "Not Ready Policy", "description": "Fan-out ready-gating policy for a client whose inputs are not ready at a scheduled fire: 'hold_and_wait' (skip that client, retry next cycle), 'run_and_flag' (fire anyway, flag the cycle \u2014 legacy default), or 'skip_cycle' (write a terminal skipped-cycle tombstone).", "default": "run_and_flag" }, "schedule_overrides": { "additionalProperties": true, "type": "object", "title": "Schedule Overrides", "description": "Per-client schedule override map (clientId -> {cron_expr, timezone, skip_weekends, holiday_calendar}). An entry REPLACES the plan-level schedule for that client at fan-out; absent clients use the plan schedule." }, "trigger_type": { "anyOf": [ { "type": "string", "enum": [ "manual", "schedule", "webhook", "email", "api" ] }, { "type": "null" } ], "title": "Trigger Type", "description": "Persisted 'How it runs' trigger choice (card #826 AC-1). Default: 'schedule' when a cron is supplied, else 'manual'." }, "schedule_spec": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Schedule Spec", "description": "Structured six-frequency ScheduleEditor spec (round-trip source of truth; the cron column is lossy for re-editing). Opaque JSONB." } }, "type": "object", "required": [ "name", "domain" ], "title": "JobDefinitionCreate", "description": "Request to create a job definition." }, "JobDefinitionListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/JobDefinitionResponse" }, "type": "array", "title": "Items" }, "pagination": { "title": "Pagination" } }, "type": "object", "required": [ "items", "pagination" ], "title": "JobDefinitionListResponse", "description": "Paginated list of job definitions." }, "JobDefinitionResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "permakey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Permakey", "description": "Stable human-readable key for the batch/fan-out deep-link URL /workstreams/{ws}/cycles/{permakey}/\u2026 (#173). Null on legacy rows." }, "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "domain": { "type": "string", "title": "Domain" }, "goal_template": { "type": "string", "title": "Goal Template" }, "tools": { "items": { "type": "string" }, "type": "array", "title": "Tools" }, "deliverables": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Deliverables" }, "max_turns": { "type": "integer", "title": "Max Turns" }, "max_cost_usd": { "type": "number", "title": "Max Cost Usd" }, "max_duration_minutes": { "type": "integer", "title": "Max Duration Minutes" }, "target_selector": { "additionalProperties": true, "type": "object", "title": "Target Selector" }, "per_client_overrides": { "additionalProperties": true, "type": "object", "title": "Per Client Overrides" }, "input_bindings": { "additionalProperties": true, "type": "object", "title": "Input Bindings" }, "default_context": { "additionalProperties": true, "type": "object", "title": "Default Context" }, "source_tracing": { "type": "boolean", "title": "Source Tracing" }, "human_checkpoints": { "items": { "type": "string" }, "type": "array", "title": "Human Checkpoints" }, "schedule": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Schedule" }, "schedule_timezone": { "type": "string", "title": "Schedule Timezone" }, "skip_weekends": { "type": "boolean", "title": "Skip Weekends", "default": false }, "holiday_calendar": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Holiday Calendar" }, "not_ready_policy": { "type": "string", "title": "Not Ready Policy", "description": "Fan-out ready-gating policy for a not-ready client at a scheduled fire.", "default": "run_and_flag" }, "schedule_overrides": { "additionalProperties": true, "type": "object", "title": "Schedule Overrides", "description": "Per-client schedule override map (clientId -> override spec)." }, "trigger_type": { "type": "string", "title": "Trigger Type", "description": "Persisted 'How it runs' trigger choice (manual/schedule/webhook/email/api).", "default": "manual" }, "schedule_spec": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Schedule Spec", "description": "Structured ScheduleEditor spec (opaque JSONB round-trip; cron stays the execution shape)." }, "is_enabled": { "type": "boolean", "title": "Is Enabled" }, "next_run_at": { "anyOf": [ {}, { "type": "null" } ], "title": "Next Run At" }, "last_run_at": { "anyOf": [ {}, { "type": "null" } ], "title": "Last Run At" }, "status": { "type": "string", "title": "Status" }, "created_by": { "type": "string", "title": "Created By" }, "created_by_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created By Name", "description": "Display name behind created_by, for the detail header's 'Created by '. Null when the id no longer resolves to a user \u2014 render the date alone rather than an id." }, "created_at": { "title": "Created At" }, "updated_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated By", "description": "User id of whoever last edited this WorkPlan. Null for edits predating the column." }, "updated_by_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated By Name", "description": "Display name behind updated_by, for 'Edited by '." }, "updated_at": { "title": "Updated At" }, "current_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Current Version", "description": "Latest version number in job_definition_version; null if no history yet." }, "pinned_workstream_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Pinned Workstream Version", "description": "Pinned config-history version; null = float to latest." }, "upstream_update_available": { "type": "boolean", "title": "Upstream Update Available", "description": "True when pinned_workstream_version is set AND current_version has advanced beyond it \u2014 a newer config version exists.", "default": false }, "cost_so_far_gbp": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Cost So Far Gbp", "description": "Sum of customer-facing GBP cost (hourly_rate_gbp x elapsed) across all cycles for this job definition. Null when no cycles exist." }, "hourly_rate_gbp": { "type": "number", "title": "Hourly Rate Gbp", "description": "This customer's WorkStream hourly rate in GBP (platform.organizations.workstream_hourly_rate_gbp). Their cost, our revenue \u2014 never our compute cost. Serialized because the client RENDERS the rate beside the total ('\u00a3X total \u00b7 \u00a3Y avg / client \u00b7 \u00a3Z/hr rate'); without it the frontend had to hardcode 19, which silently disagrees with a total computed at any other rate.", "default": 19.0 }, "total_runs": { "type": "integer", "title": "Total Runs", "description": "Count of cycles launched from this job definition. When the list was filtered by workstream_id, this count is scoped to that workstream.", "default": 0 }, "active_runs": { "type": "integer", "title": "Active Runs", "description": "Count of cycles currently in flight (see ACTIVE_CYCLE_STATUSES). Same scoping rule as total_runs. Exists so a caller that only needs 'how many are running' does not have to fetch every cycle of every job to count them client-side \u2014 the shell rail did exactly that, at one request per job on every authenticated page load.", "default": 0 }, "last_cycle_at": { "anyOf": [ {}, { "type": "null" } ], "title": "Last Cycle At", "description": "Start timestamp of the most recent cycle (scoped to the requested workstream if filtered)." }, "last_cycle_state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Cycle State", "description": "Status of the most recent cycle (scoped to the requested workstream if filtered)." }, "latest_cycle_launch_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Latest Cycle Launch Id", "description": "The most recent cycle_launch (the product's Cycle - one launch of a plan) for this job_definition, so list consumers (the shell rail 'Running cycles', the @ 'cycle' picker, the TopicLivePage cycle mention) can link the plan's latest cycle directly. Card 'Every link the app emits uses the cycle's own address': emitting the plan's job id in the cycle slot redirected to the WorkPlan, not the cycle. Null when the plan has no cycle_launch yet." }, "latest_cycle_launch_permakey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Latest Cycle Launch Permakey", "description": "The permakey of the most recent cycle_launch - the canonical CYCLE address (/workstreams/{ws}/cycles/{permakey}). List consumers link THIS (not the plan's job permakey) for the cycle slot. Card 'Every link the app emits uses the cycle's own address'." }, "latest_cycle_launch_workstream_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Latest Cycle Launch Workstream Id", "description": "The workstream id of the most recent cycle_launch - the parent WorkStream for the nested cycle URL. Null when the launch has none (should not happen; cycle_launch.workstream_id is NOT NULL)." }, "latest_cycle_launch_workstream_permakey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Latest Cycle Launch Workstream Permakey", "description": "The workstream permakey of the most recent cycle_launch - the canonical WorkStream segment for the nested cycle URL, so a list consumer can build /workstreams/{ws_permakey}/cycles/{launch_permakey} without a second fetch." }, "run_mode": { "$ref": "#/components/schemas/WorkplanRunMode", "description": "Effective autonomy posture \u2014 derived from default_context.run_mode. Same shape as BlueprintResponse.run_mode for FE compat (S2-READ \u00a71a)." }, "autonomy_config": { "anyOf": [ { "$ref": "#/components/schemas/AutonomyConfig" }, { "type": "null" } ], "description": "Fine-grained autonomy controls from default_context.autonomy_config, or null if unset." }, "cohort": { "$ref": "#/components/schemas/WorkplanCohort", "description": "Cohort shape derived from target_selector. Same shape as BlueprintResponse.cohort for FE compat (S2-READ \u00a71b)." } }, "type": "object", "required": [ "id", "name", "domain", "goal_template", "tools", "deliverables", "max_turns", "max_cost_usd", "max_duration_minutes", "target_selector", "per_client_overrides", "input_bindings", "default_context", "source_tracing", "human_checkpoints", "schedule_timezone", "is_enabled", "status", "created_by", "created_at", "updated_at" ], "title": "JobDefinitionResponse", "description": "Job definition response." }, "JobDefinitionUpdate": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 200, "minLength": 1 }, { "type": "null" } ], "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "goal_template": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Goal Template" }, "tools": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tools" }, "deliverables": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Deliverables" }, "max_turns": { "anyOf": [ { "type": "integer", "maximum": 500.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Max Turns" }, "max_cost_usd": { "anyOf": [ { "type": "number", "maximum": 50.0, "minimum": 0.1 }, { "type": "null" } ], "title": "Max Cost Usd" }, "max_duration_minutes": { "anyOf": [ { "type": "integer", "maximum": 120.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Max Duration Minutes" }, "target_selector": { "anyOf": [ { "$ref": "#/components/schemas/TargetSelector" }, { "type": "null" } ] }, "per_client_overrides": { "anyOf": [ { "additionalProperties": { "additionalProperties": true, "type": "object" }, "type": "object" }, { "type": "null" } ], "title": "Per Client Overrides" }, "default_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Default Context" }, "source_tracing": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Source Tracing" }, "human_checkpoints": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Human Checkpoints" }, "schedule": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Schedule" }, "schedule_timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Schedule Timezone" }, "skip_weekends": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Skip Weekends", "description": "Shift a fire time that lands on Sat/Sun to the next business day" }, "holiday_calendar": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Holiday Calendar", "description": "Shift a fire time landing on a holiday to the next business day: 'UK', 'US', or 'AU'" }, "not_ready_policy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Not Ready Policy", "description": "Fan-out ready-gating policy for a not-ready client at a scheduled fire: 'hold_and_wait', 'run_and_flag', or 'skip_cycle'. None = leave unchanged." }, "schedule_overrides": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Schedule Overrides", "description": "Per-client schedule override map (clientId -> override spec). None = leave unchanged; pass {} to clear all overrides (fall back to the plan schedule)." }, "is_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Enabled" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "input_bindings": { "anyOf": [ { "items": { "$ref": "#/components/schemas/InputBindingDef" }, "type": "array" }, { "type": "null" } ], "title": "Input Bindings", "description": "Cross-WorkPlan or external input bindings applying to all cohort instances" }, "pinned_workstream_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Pinned Workstream Version", "description": "Pin this WorkPlan to a specific config-history version. NULL (default) = float to latest. Set to a version number from job_definition_version to lock execution to that snapshot. Use PATCH with pinned_workstream_version=null to unpin." }, "run_mode": { "anyOf": [ { "type": "string", "enum": [ "propose", "auto_run" ] }, { "type": "null" } ], "title": "Run Mode", "description": "Autonomy posture shorthand \u2014 written into default_context.run_mode. propose = always surface proposals; auto_run = execute without requiring approval." }, "trigger_type": { "anyOf": [ { "type": "string", "enum": [ "manual", "schedule", "webhook", "email", "api" ] }, { "type": "null" } ], "title": "Trigger Type", "description": "Persisted 'How it runs' trigger choice (card #826 AC-1). None = leave unchanged." }, "schedule_spec": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Schedule Spec", "description": "Structured six-frequency ScheduleEditor spec (source of truth for re-editing \u2014 the cron `schedule` column is lossy for shapes like 'last day of month' / 'N business days after period-end'). Opaque JSONB; the FE owns the shape. None = leave unchanged." }, "autonomy_config": { "anyOf": [ { "$ref": "#/components/schemas/AutonomyConfig" }, { "type": "null" } ], "description": "Fine-grained autonomy controls \u2014 stored in default_context.autonomy_config. Partial updates are merged with the existing config (unset fields are preserved)." } }, "type": "object", "title": "JobDefinitionUpdate", "description": "Request to update a job definition." }, "JobDefinitionVersionResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "job_definition_id": { "type": "string", "format": "uuid", "title": "Job Definition Id" }, "version": { "type": "integer", "title": "Version" }, "snapshot": { "additionalProperties": true, "type": "object", "title": "Snapshot" }, "change_summary": { "type": "string", "title": "Change Summary" }, "created_by": { "type": "string", "title": "Created By" }, "created_at": { "title": "Created At" } }, "type": "object", "required": [ "id", "job_definition_id", "version", "snapshot", "change_summary", "created_by", "created_at" ], "title": "JobDefinitionVersionResponse", "description": "One immutable version snapshot of a WorkPlan." }, "LoopStepDefinition": { "properties": { "id": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9_-]+$", "title": "Id" }, "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name" }, "type": { "type": "string", "const": "loop", "title": "Type", "default": "loop" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "depends_on": { "items": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" } ] }, "type": "array", "title": "Depends On" }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stage" }, "timeout": { "anyOf": [ { "type": "string", "pattern": "^\\d+[smhd]$" }, { "type": "null" } ], "title": "Timeout" }, "retry_policy": { "anyOf": [ { "$ref": "#/components/schemas/RetryPolicy" }, { "type": "null" } ] }, "error_handler": { "anyOf": [ { "$ref": "#/components/schemas/StepErrorHandler" }, { "type": "null" } ] }, "emit_artifact": { "anyOf": [ { "$ref": "#/components/schemas/EmitArtifactSpec" }, { "type": "null" } ] }, "optional": { "type": "boolean", "title": "Optional", "default": false }, "continue_on_error": { "type": "boolean", "title": "Continue On Error", "default": false }, "halt_conditions": { "items": { "$ref": "#/components/schemas/HaltCondition" }, "type": "array", "title": "Halt Conditions" }, "parameters": { "items": { "$ref": "#/components/schemas/StepParameter" }, "type": "array", "title": "Parameters" }, "guards": { "items": { "$ref": "#/components/schemas/StepGuard" }, "type": "array", "title": "Guards" }, "impact_level": { "$ref": "#/components/schemas/ImpactLevel", "default": "medium" }, "run_mode": { "$ref": "#/components/schemas/RunMode", "default": "propose" }, "requires_approval": { "type": "boolean", "title": "Requires Approval", "default": false }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "examples": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StepExample" }, "type": "array" }, { "type": "null" } ], "title": "Examples", "description": "Attached example files for this step. Each entry pairs a platform.file_uploads.file_id with a role + tags + notes so the runtime can shape its instruction. Bounded at 20 to keep a reasonable upper limit on the prompt preamble." }, "applies_when": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applies When", "description": "CEL predicate evaluated at MATERIALIZATION (not at step execution): the step is marked skipped when it evaluates False. Stored verbatim \u2014 the expression is parsed by celpy at launch, so any coercion here would change its meaning." }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "Categorical labels on the step itself (e.g. 'pdf-read', 'coutts', 'fy25'). Free-form; recommended tag set is documented per workstream surface." }, "over": { "type": "string", "title": "Over", "description": "Expression for collection to iterate" }, "as": { "type": "string", "title": "As", "description": "Variable name for current item" }, "index_as": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Index As", "description": "Variable name for index" }, "parallel": { "type": "boolean", "title": "Parallel", "default": false }, "max_concurrent": { "type": "integer", "maximum": 20.0, "minimum": 1.0, "title": "Max Concurrent", "description": "Bounded iteration concurrency when parallel=true. Ignored for sequential loops; never permit unbounded fan-out.", "default": 4 }, "max_iterations": { "type": "integer", "minimum": 1.0, "title": "Max Iterations", "default": 1000 }, "steps": { "items": {}, "type": "array", "title": "Steps", "description": "Steps to execute per iteration" }, "on_complete": { "anyOf": [ { "$ref": "#/components/schemas/OnCompleteAction" }, { "type": "null" } ] } }, "additionalProperties": false, "type": "object", "required": [ "id", "name", "over", "as", "steps" ], "title": "LoopStepDefinition", "description": "Loop step - iterates over a collection." }, "NextRunPreviewItem": { "properties": { "run_at": { "type": "string", "format": "date-time", "title": "Run At", "description": "Effective (possibly shifted) fire time, UTC ISO-8601." }, "original_at": { "type": "string", "format": "date-time", "title": "Original At", "description": "Raw cron occurrence before any weekend/holiday shift, UTC ISO-8601." }, "shifted": { "type": "boolean", "title": "Shifted", "description": "True when the fire was moved off a weekend/holiday." }, "shift_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Shift Reason", "description": "Plain-English shift reason, e.g. \"weekend\" or \"holiday:Independence Day\"." }, "timezone": { "type": "string", "title": "Timezone", "description": "The timezone the schedule is evaluated in (IANA)." } }, "type": "object", "required": [ "run_at", "original_at", "shifted", "timezone" ], "title": "NextRunPreviewItem", "description": "One upcoming fire time in the next-N preview." }, "NextRunPreviewResponse": { "properties": { "workplan_id": { "type": "string", "title": "Workplan Id" }, "schedule": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Schedule" }, "timezone": { "type": "string", "title": "Timezone" }, "runs": { "items": { "$ref": "#/components/schemas/NextRunPreviewItem" }, "type": "array", "title": "Runs" }, "schedule_source": { "type": "string", "title": "Schedule Source", "description": "'plan' (plan-level schedule) or 'override' (per-client schedule_override).", "default": "plan" }, "client_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Id", "description": "The client the preview is scoped to (echoes the ?client_id= query param)." } }, "type": "object", "required": [ "workplan_id", "schedule", "timezone", "runs" ], "title": "NextRunPreviewResponse", "description": "GET /workplans/{id}/next-runs \u2014 the upcoming-fire preview." }, "NotifyStepDefinition": { "properties": { "id": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9_-]+$", "title": "Id" }, "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name" }, "type": { "type": "string", "const": "notify", "title": "Type", "default": "notify" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "depends_on": { "items": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" } ] }, "type": "array", "title": "Depends On" }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stage" }, "timeout": { "anyOf": [ { "type": "string", "pattern": "^\\d+[smhd]$" }, { "type": "null" } ], "title": "Timeout" }, "retry_policy": { "anyOf": [ { "$ref": "#/components/schemas/RetryPolicy" }, { "type": "null" } ] }, "error_handler": { "anyOf": [ { "$ref": "#/components/schemas/StepErrorHandler" }, { "type": "null" } ] }, "emit_artifact": { "anyOf": [ { "$ref": "#/components/schemas/EmitArtifactSpec" }, { "type": "null" } ] }, "optional": { "type": "boolean", "title": "Optional", "default": false }, "continue_on_error": { "type": "boolean", "title": "Continue On Error", "default": false }, "halt_conditions": { "items": { "$ref": "#/components/schemas/HaltCondition" }, "type": "array", "title": "Halt Conditions" }, "parameters": { "items": { "$ref": "#/components/schemas/StepParameter" }, "type": "array", "title": "Parameters" }, "guards": { "items": { "$ref": "#/components/schemas/StepGuard" }, "type": "array", "title": "Guards" }, "impact_level": { "$ref": "#/components/schemas/ImpactLevel", "default": "medium" }, "run_mode": { "$ref": "#/components/schemas/RunMode", "default": "propose" }, "requires_approval": { "type": "boolean", "title": "Requires Approval", "default": false }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "examples": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StepExample" }, "type": "array" }, { "type": "null" } ], "title": "Examples", "description": "Attached example files for this step. Each entry pairs a platform.file_uploads.file_id with a role + tags + notes so the runtime can shape its instruction. Bounded at 20 to keep a reasonable upper limit on the prompt preamble." }, "applies_when": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applies When", "description": "CEL predicate evaluated at MATERIALIZATION (not at step execution): the step is marked skipped when it evaluates False. Stored verbatim \u2014 the expression is parsed by celpy at launch, so any coercion here would change its meaning." }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "Categorical labels on the step itself (e.g. 'pdf-read', 'coutts', 'fy25'). Free-form; recommended tag set is documented per workstream surface." }, "channel": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Channel", "description": "Notification channel slug (e.g. 'slack:#close-team', 'email:auditor@firm.com')." }, "message": { "type": "string", "minLength": 1, "title": "Message", "description": "Message body \u2014 supports {{ outputs.* }} Jinja2 placeholders." }, "inputs": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Inputs", "description": "Optional Jinja2 input bindings." } }, "additionalProperties": false, "type": "object", "required": [ "id", "name", "channel", "message" ], "title": "NotifyStepDefinition", "description": "Notify step \u2014 sends a notification (Slack, Teams, email) without\ndispatching a tool. Stuart 2026-05-19: 1 template on dev uses\n``type='notify'`` (the FIC reconciliation step); same schema-gap\nfix as archie_query." }, "OnCompleteAction": { "properties": { "set": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Set", "description": "Variables to set" }, "goto": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Goto", "description": "Step to jump to" } }, "additionalProperties": false, "type": "object", "title": "OnCompleteAction", "description": "Action to perform on step completion." }, "OutputDefinition": { "properties": { "type": { "type": "string", "title": "Type", "default": "object" }, "store_in": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Store In", "description": "Context path to store output" }, "append_to": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Append To", "description": "Context array to append to" }, "merge_from": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Merge From", "description": "Paths to merge outputs from" } }, "additionalProperties": false, "type": "object", "title": "OutputDefinition", "description": "Output definition for a step." }, "Pagination": { "properties": { "total": { "type": "integer", "minimum": 0.0, "title": "Total", "description": "Total items" }, "limit": { "type": "integer", "minimum": 1.0, "title": "Limit", "description": "Items per page" }, "offset": { "type": "integer", "minimum": 0.0, "title": "Offset", "description": "Offset" }, "has_more": { "type": "boolean", "title": "Has More", "description": "More items available" } }, "type": "object", "required": [ "total", "limit", "offset", "has_more" ], "title": "Pagination", "description": "Pagination information", "example": { "has_more": true, "limit": 20, "offset": 0, "total": 142 } }, "ParallelStepDefinition": { "properties": { "id": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9_-]+$", "title": "Id" }, "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name" }, "type": { "type": "string", "const": "parallel", "title": "Type", "default": "parallel" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "depends_on": { "items": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" } ] }, "type": "array", "title": "Depends On" }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stage" }, "timeout": { "anyOf": [ { "type": "string", "pattern": "^\\d+[smhd]$" }, { "type": "null" } ], "title": "Timeout" }, "retry_policy": { "anyOf": [ { "$ref": "#/components/schemas/RetryPolicy" }, { "type": "null" } ] }, "error_handler": { "anyOf": [ { "$ref": "#/components/schemas/StepErrorHandler" }, { "type": "null" } ] }, "emit_artifact": { "anyOf": [ { "$ref": "#/components/schemas/EmitArtifactSpec" }, { "type": "null" } ] }, "optional": { "type": "boolean", "title": "Optional", "default": false }, "continue_on_error": { "type": "boolean", "title": "Continue On Error", "default": false }, "halt_conditions": { "items": { "$ref": "#/components/schemas/HaltCondition" }, "type": "array", "title": "Halt Conditions" }, "parameters": { "items": { "$ref": "#/components/schemas/StepParameter" }, "type": "array", "title": "Parameters" }, "guards": { "items": { "$ref": "#/components/schemas/StepGuard" }, "type": "array", "title": "Guards" }, "impact_level": { "$ref": "#/components/schemas/ImpactLevel", "default": "medium" }, "run_mode": { "$ref": "#/components/schemas/RunMode", "default": "propose" }, "requires_approval": { "type": "boolean", "title": "Requires Approval", "default": false }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "examples": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StepExample" }, "type": "array" }, { "type": "null" } ], "title": "Examples", "description": "Attached example files for this step. Each entry pairs a platform.file_uploads.file_id with a role + tags + notes so the runtime can shape its instruction. Bounded at 20 to keep a reasonable upper limit on the prompt preamble." }, "applies_when": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applies When", "description": "CEL predicate evaluated at MATERIALIZATION (not at step execution): the step is marked skipped when it evaluates False. Stored verbatim \u2014 the expression is parsed by celpy at launch, so any coercion here would change its meaning." }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "Categorical labels on the step itself (e.g. 'pdf-read', 'coutts', 'fy25'). Free-form; recommended tag set is documented per workstream surface." }, "max_concurrent": { "type": "integer", "minimum": 1.0, "title": "Max Concurrent", "default": 10 }, "wait_for": { "anyOf": [ { "type": "string", "enum": [ "all", "any" ] }, { "type": "integer" } ], "title": "Wait For", "default": "all" }, "fail_fast": { "type": "boolean", "title": "Fail Fast", "default": false }, "steps": { "items": {}, "type": "array", "title": "Steps", "description": "Steps to execute in parallel" }, "outputs": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/OutputDefinition" }, "type": "object" }, { "type": "null" } ], "title": "Outputs" } }, "additionalProperties": false, "type": "object", "required": [ "id", "name", "steps" ], "title": "ParallelStepDefinition", "description": "Parallel step - executes steps concurrently." }, "ParamResolution": { "properties": { "name": { "type": "string", "title": "Name" }, "type": { "type": "string", "title": "Type" }, "required": { "type": "boolean", "title": "Required" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" }, "scope": { "type": "string", "enum": [ "workstream", "client", "run" ], "title": "Scope", "default": "workstream" }, "binding_orphaned": { "type": "boolean", "title": "Binding Orphaned", "default": false }, "loaded_by": { "type": "string", "enum": [ "auto", "provide", "connector", "upstream", "rollforward" ], "title": "Loaded By", "default": "auto" }, "client_file_supported": { "type": "boolean", "title": "Client File Supported", "default": false }, "source_category": { "anyOf": [ { "type": "string", "enum": [ "carried_forward", "synced", "uploaded", "missing" ] }, { "type": "null" } ], "title": "Source Category" }, "status": { "type": "string", "enum": [ "sourced", "missing" ], "title": "Status" }, "source": { "anyOf": [ { "$ref": "#/components/schemas/ParamSource" }, { "type": "null" } ] }, "sources": { "items": { "$ref": "#/components/schemas/ParamSource" }, "type": "array", "title": "Sources" }, "problem": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Problem" } }, "type": "object", "required": [ "name", "type", "required", "status" ], "title": "ParamResolution", "description": "One declared input, resolved for one client.\n\n``source_category`` (S2-read \u00a73) is the authoritative 4-way classification for\nFILE inputs (``carried_forward|synced|uploaded|missing``) and ``null`` for\nscalar inputs (resolved at launch, never client-sourced). ``status``\n(``sourced``/``missing``) is a back-compat shim: ``missing`` iff\n``source_category`` is ``missing``, else ``sourced``; scalars report\n``missing`` with a null ``source``.\n\n``sources`` (AR-653) carries one entry per document when the slot is declared\n``type: \"files\"`` \u2014 a list input holding N documents yields N entries so a row\ncan render N chips. A single-document input (``type: \"file\"``) carries one\nentry (or none when missing). ``source`` is the first entry for back-compat." }, "ParamSource": { "properties": { "file_id": { "type": "string", "title": "File Id" }, "filename": { "type": "string", "title": "Filename" }, "origin": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Origin" }, "client_file_binding_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client File Binding Id" }, "client_file_period": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client File Period" }, "is_standing": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Standing" }, "broker_status": { "anyOf": [ { "type": "string", "enum": [ "family", "unknown" ] }, { "type": "null" } ], "title": "Broker Status" }, "family": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Family" } }, "type": "object", "required": [ "file_id", "filename" ], "title": "ParamSource", "description": "The file that sources one input for one client." }, "ParameterType": { "type": "string", "enum": [ "string", "number", "boolean", "uuid", "date", "datetime", "array", "object" ], "title": "ParameterType", "description": "Parameter types for context parameters." }, "PlanStep": { "properties": { "order": { "type": "integer", "minimum": 1.0, "title": "Order", "description": "Execution order of this step (1-indexed)" }, "action": { "type": "string", "maxLength": 1000, "minLength": 1, "title": "Action", "description": "Plain English description of the action to be performed" }, "inputs": { "items": { "type": "string" }, "type": "array", "title": "Inputs", "description": "List of input data/resources this step will use" }, "expected_outputs": { "items": { "type": "string" }, "type": "array", "title": "Expected Outputs", "description": "List of expected outputs/artifacts from this step" }, "is_write_operation": { "type": "boolean", "title": "Is Write Operation", "description": "Whether this step performs write operations to external systems", "default": false }, "estimated_duration_seconds": { "anyOf": [ { "type": "integer", "maximum": 86400.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Estimated Duration Seconds", "description": "Estimated time to complete this step in seconds" }, "risk_level": { "$ref": "#/components/schemas/RiskLevel", "description": "Risk classification for this step (low, medium, high)", "default": "low" }, "target_system": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Target System", "description": "External system this step interacts with (e.g., 'xero', 'quickbooks', 'email')" }, "requires_confirmation": { "type": "boolean", "title": "Requires Confirmation", "description": "Whether this specific step requires user confirmation before proceeding", "default": false } }, "type": "object", "required": [ "order", "action" ], "title": "PlanStep", "description": "Individual step in an AI-generated execution plan.\n\nEach step describes a discrete action the task will perform,\nwith enough detail for human review before approval." }, "ProgressInfoResponse": { "properties": { "current": { "type": "integer", "minimum": 0.0, "title": "Current", "description": "Current item number" }, "total": { "type": "integer", "minimum": 0.0, "title": "Total", "description": "Total items" }, "unit": { "type": "string", "title": "Unit", "description": "Unit of progress (e.g., 'transactions')" }, "percent": { "type": "number", "maximum": 100.0, "minimum": 0.0, "title": "Percent", "description": "Percentage complete" } }, "type": "object", "required": [ "current", "total", "unit", "percent" ], "title": "ProgressInfoResponse", "description": "Progress information for batch operations." }, "ProvideGuidanceRequest": { "properties": { "response": { "type": "string", "title": "Response" }, "option_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Option Value" } }, "type": "object", "required": [ "response" ], "title": "ProvideGuidanceRequest" }, "RecipeTopicListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/RecipeTopicRow" }, "type": "array", "title": "Items" }, "total": { "type": "integer", "title": "Total", "description": "Total topics anchored to this recipe.", "default": 0 } }, "type": "object", "title": "RecipeTopicListResponse", "description": "Topics anchored to one workstream recipe." }, "RecipeTopicRow": { "properties": { "topic_id": { "type": "string", "format": "uuid", "title": "Topic Id", "description": "Topic UUID (links to /topics/{id})." }, "permakey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Permakey", "description": "Topic permakey for canonical routing." }, "title": { "type": "string", "title": "Title", "description": "Topic name." }, "theme_color": { "type": "string", "title": "Theme Color", "description": "Hex/CSS tint for the left colour bar." }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type", "description": "Topic type chip value." }, "client_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Client Id", "description": "Linked client UUID, if any." }, "client_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Code", "description": "Linked client short code, if any." }, "client_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Name", "description": "Linked client display name, if any." }, "workstream_state": { "anyOf": [ { "$ref": "#/components/schemas/CycleStatus" }, { "type": "null" } ], "description": "Status of the topic's most recent execution cycle (running/completed/blocked/...). NULL if no cycle has run." }, "workstream_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workstream Label", "description": "Optional human label for the attached workstream state." }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Last update timestamp." } }, "type": "object", "required": [ "topic_id", "title", "theme_color", "updated_at" ], "title": "RecipeTopicRow", "description": "One topic anchored to a workstream recipe.\n\nPowers the V2 recipe-detail \"Topics using this workstream\" section\n(``WorkStreamDetailV2Page``). A topic is \"using\" a recipe when it is\neither directly anchored (``platform.topics.workstream_id``) or its most\nrecent execution cycle ran that recipe (``workstreams.cycle.workstream_id``)." }, "RejectionRequestModel": { "properties": { "reason": { "type": "string", "maxLength": 5000, "minLength": 1, "title": "Reason", "description": "Reason for rejection" }, "suggested_changes": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ], "title": "Suggested Changes", "description": "Suggested changes for resubmission" } }, "type": "object", "required": [ "reason" ], "title": "RejectionRequestModel", "description": "Request model for task rejection.", "example": { "reason": "Reconciliation threshold is too high for this account. Please reduce to 0.01.", "suggested_changes": "Set tolerance_amount to 0.01 instead of 0.05" } }, "RequiredDocument": { "properties": { "label": { "type": "string", "title": "Label", "description": "Display label for the required document" }, "accepted_types": { "items": { "type": "string" }, "type": "array", "title": "Accepted Types", "description": "Accepted file extensions (e.g. ['.xlsx', '.pdf'])" }, "required": { "type": "boolean", "title": "Required", "default": true }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" } }, "additionalProperties": false, "type": "object", "required": [ "label" ], "title": "RequiredDocument", "description": "Definition of a required document for upload steps." }, "ResolvePayeeFlagRequest": { "properties": { "payee_token": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Payee Token", "description": "Distinctive payee token to route (e.g. 'GRAVITA'); upper-cased on store." }, "category": { "type": "string", "minLength": 1, "title": "Category", "description": "Engine category key the payee's legs route to (e.g. 'acct', 'mgmt')." }, "direction": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Direction", "description": "'dr' (payments only), 'cr' (receipts only), or null (either direction)." } }, "type": "object", "required": [ "payee_token", "category" ], "title": "ApiRoutersWorkstreamsModels__ResolvePayeeFlagRequest", "description": "Resolve a bank-analysis ``uncategorised_leg`` review flag: route a payee\nto a category. Persisted as durable (workspace, client)-scoped precedent so\nthe next cycle auto-applies it and re-emits zero flags for that payee.", "example": { "category": "acct", "direction": "dr", "payee_token": "GRAVITA" } }, "ResolvePayeeFlagResponse": { "properties": { "success": { "type": "boolean", "title": "Success", "default": true }, "precedent_id": { "type": "string", "format": "uuid", "title": "Precedent Id", "description": "The persisted learned_payee_precedent row id" }, "rule": { "type": "string", "title": "Rule", "description": "The stored rule string, e.g. 'acct:dr'" } }, "type": "object", "required": [ "precedent_id", "rule" ], "title": "ApiRoutersWorkstreamsModels__ResolvePayeeFlagResponse", "description": "Result of resolving a payee flag." }, "ResumeHoldRequestModel": { "properties": { "held_at": { "type": "string", "format": "date-time", "title": "Held At" } }, "type": "object", "required": [ "held_at" ], "title": "ResumeHoldRequestModel" }, "ResumeHoldResponseModel": { "properties": { "task_id": { "type": "string", "format": "uuid", "title": "Task Id" }, "cycle_id": { "type": "string", "format": "uuid", "title": "Cycle Id" }, "task_status": { "type": "string", "title": "Task Status" }, "cycle_status": { "$ref": "#/components/schemas/CycleStatus" }, "gate_record": { "$ref": "#/components/schemas/RunGateRecord" } }, "type": "object", "required": [ "task_id", "cycle_id", "task_status", "cycle_status", "gate_record" ], "title": "ResumeHoldResponseModel" }, "RetryPolicy": { "properties": { "max_attempts": { "type": "integer", "maximum": 10.0, "minimum": 1.0, "title": "Max Attempts", "default": 3 }, "backoff": { "$ref": "#/components/schemas/BackoffStrategy", "default": "exponential" }, "initial_delay": { "type": "string", "pattern": "^\\d+[smh]$", "title": "Initial Delay", "default": "1s" }, "max_delay": { "type": "string", "pattern": "^\\d+[smh]$", "title": "Max Delay", "default": "5m" }, "multiplier": { "type": "number", "minimum": 1.0, "title": "Multiplier", "default": 2.0 }, "jitter": { "type": "boolean", "title": "Jitter", "default": true }, "retryable_errors": { "items": { "type": "string" }, "type": "array", "title": "Retryable Errors" }, "non_retryable_errors": { "items": { "type": "string" }, "type": "array", "title": "Non Retryable Errors" } }, "additionalProperties": false, "type": "object", "title": "RetryPolicy", "description": "Retry policy configuration." }, "ReversalExecutionRequest": { "properties": { "plan_id": { "type": "string", "format": "uuid", "title": "Plan Id", "description": "Reversal plan UUID to execute" }, "confirm": { "type": "boolean", "title": "Confirm", "description": "Confirmation flag", "default": false } }, "type": "object", "required": [ "plan_id" ], "title": "ReversalExecutionRequest", "description": "Request to execute a reversal plan.", "example": { "confirm": true, "plan_id": "550e8400-e29b-41d4-a716-446655440000" } }, "ReversalExecutionResponse": { "properties": { "cycle_id": { "type": "string", "format": "uuid", "title": "Cycle Id", "description": "Original cycle UUID" }, "reversal_cycle_id": { "type": "string", "format": "uuid", "title": "Reversal Cycle Id", "description": "New reversal cycle UUID" }, "status": { "type": "string", "title": "Status", "description": "Execution status" }, "message": { "type": "string", "title": "Message", "description": "Status message" } }, "type": "object", "required": [ "cycle_id", "reversal_cycle_id", "status", "message" ], "title": "ReversalExecutionResponse", "description": "Response from reversal execution." }, "ReversalPlanResponse": { "properties": { "cycle_id": { "type": "string", "format": "uuid", "title": "Cycle Id", "description": "Cycle UUID" }, "plan_id": { "type": "string", "format": "uuid", "title": "Plan Id", "description": "Reversal plan UUID" }, "steps": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Steps", "description": "Reversal steps" }, "estimated_duration_seconds": { "type": "integer", "minimum": 0.0, "title": "Estimated Duration Seconds", "description": "Estimated duration" }, "requires_approval": { "type": "boolean", "title": "Requires Approval", "description": "Whether reversal requires approval", "default": true }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Plan creation timestamp" } }, "type": "object", "required": [ "cycle_id", "plan_id", "estimated_duration_seconds", "created_at" ], "title": "ReversalPlanResponse", "description": "Generated reversal plan for a cycle." }, "RiskLevel": { "type": "string", "enum": [ "low", "medium", "high" ], "title": "RiskLevel", "description": "Risk level classification for plan steps.\n\nUsed to communicate the potential impact of each step to users,\nespecially for write operations that modify external systems." }, "RosterClient": { "properties": { "client_id": { "type": "string", "title": "Client Id" }, "client_permakey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Permakey" }, "client_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Name" }, "resolved_period": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resolved Period" }, "initials": { "type": "string", "title": "Initials" }, "is_exception": { "type": "boolean", "title": "Is Exception" }, "exception_reasons": { "items": { "type": "string" }, "type": "array", "title": "Exception Reasons" }, "readiness": { "$ref": "#/components/schemas/RosterReadiness" }, "alteration_count": { "type": "integer", "title": "Alteration Count", "default": 0 }, "alteration_inert_count": { "type": "integer", "title": "Alteration Inert Count", "default": 0 }, "cycle_status": { "type": "string", "title": "Cycle Status" }, "last_cycle_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Cycle Id" }, "last_cycle_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Cycle At" }, "run_eligible": { "type": "boolean", "title": "Run Eligible" }, "skip_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Skip Reason" } }, "type": "object", "required": [ "client_id", "initials", "is_exception", "readiness", "cycle_status", "run_eligible" ], "title": "RosterClient", "description": "One client in the WorkPlan's cohort roster (maps onto the S1 ItemRow)." }, "RosterReadiness": { "properties": { "ready": { "type": "boolean", "title": "Ready" }, "required_missing": { "type": "integer", "title": "Required Missing", "default": 0 }, "by_category": { "$ref": "#/components/schemas/CategoryRollup" } }, "type": "object", "required": [ "ready" ], "title": "RosterReadiness", "description": "A roster row's input readiness (FILE inputs)." }, "RosterSummary": { "properties": { "total_clients": { "type": "integer", "title": "Total Clients" }, "exceptions": { "type": "integer", "title": "Exceptions" }, "ready": { "type": "integer", "title": "Ready" }, "by_cycle_status": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "By Cycle Status" }, "by_readiness": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "By Readiness" } }, "type": "object", "required": [ "total_clients", "exceptions", "ready" ], "title": "RosterSummary", "description": "Cohort-wide rollup \u2014 computed from the SAME snapshot as the rows." }, "RunGateRecord": { "properties": { "state": { "type": "string", "enum": [ "open", "held", "decided" ], "title": "State" }, "decision": { "anyOf": [ { "$ref": "#/components/schemas/GateEvent" }, { "type": "null" } ] }, "hold": { "anyOf": [ { "$ref": "#/components/schemas/GateEvent" }, { "type": "null" } ] }, "history": { "items": { "$ref": "#/components/schemas/GateEvent" }, "type": "array", "title": "History" } }, "type": "object", "required": [ "state" ], "title": "RunGateRecord" }, "RunMode": { "type": "string", "enum": [ "propose", "auto_run" ], "title": "RunMode", "description": "Execution mode for steps." }, "RunStepRequest": { "properties": { "step_id": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Step Id", "description": "ID of the step to run (must match `steps[].id` on the workstream)" }, "parameters": { "additionalProperties": true, "type": "object", "title": "Parameters", "description": "Optional runtime parameters merged into the synthesised single-step cycle's runtime_vars (e.g. period, file references). Equivalent to the `input_data` field on `POST /cycles`." } }, "type": "object", "required": [ "step_id" ], "title": "ApiRoutersWorkstreamsModels__RunStepRequest", "description": "Request to run a single workstream step in isolation.", "example": { "parameters": { "period": "2026-01" }, "step_id": "extract" } }, "RunStepResponse": { "properties": { "cycle_id": { "type": "string", "format": "uuid", "title": "Cycle Id", "description": "UUID of the synthesised single-step cycle" }, "task_id": { "type": "string", "format": "uuid", "title": "Task Id", "description": "UUID of the pre-created task row for the requested step. FE may navigate to ?cycleId= and watch this task progress." } }, "type": "object", "required": [ "cycle_id", "task_id" ], "title": "ApiRoutersWorkstreamsModels__RunStepResponse", "description": "Response from running a single step in isolation." }, "SettableParameterOption": { "properties": { "value": { "title": "Value" }, "label": { "type": "string", "title": "Label" } }, "type": "object", "required": [ "value", "label" ], "title": "SettableParameterOption", "description": "One legal value for a settable parameter, with its display label." }, "SettableParameterSpec": { "properties": { "key": { "type": "string", "title": "Key" }, "label": { "type": "string", "title": "Label" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "value_type": { "type": "string", "title": "Value Type", "default": "string" }, "minimum": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Minimum" }, "maximum": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Maximum" }, "step": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Step" }, "options": { "items": { "$ref": "#/components/schemas/SettableParameterOption" }, "type": "array", "title": "Options" }, "default": { "anyOf": [ {}, { "type": "null" } ], "title": "Default" }, "default_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default Label" } }, "type": "object", "required": [ "key", "label" ], "title": "SettableParameterSpec", "description": "How to render, and constrain, one `set_parameter` key.\n\nAdditive to `settable_parameters` (which stays a bare `list[str]` so no\nexisting consumer breaks). `options == []` means there is no fixed choice\nlist \u2014 render a plain input, not a picker." }, "SharedPlan": { "properties": { "blueprint_id": { "type": "string", "title": "Blueprint Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" } }, "type": "object", "required": [ "blueprint_id" ], "title": "SharedPlan" }, "SkillCatalogEntry": { "type": "object", "required": [ "slug", "description" ], "properties": { "slug": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "streaming": { "type": "boolean" } } }, "SkillStepDefinition": { "properties": { "id": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9_-]+$", "title": "Id" }, "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name" }, "type": { "type": "string", "const": "skill", "title": "Type", "default": "skill" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "depends_on": { "items": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" } ] }, "type": "array", "title": "Depends On" }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stage" }, "timeout": { "anyOf": [ { "type": "string", "pattern": "^\\d+[smhd]$" }, { "type": "null" } ], "title": "Timeout" }, "retry_policy": { "anyOf": [ { "$ref": "#/components/schemas/RetryPolicy" }, { "type": "null" } ] }, "error_handler": { "anyOf": [ { "$ref": "#/components/schemas/StepErrorHandler" }, { "type": "null" } ] }, "emit_artifact": { "anyOf": [ { "$ref": "#/components/schemas/EmitArtifactSpec" }, { "type": "null" } ] }, "optional": { "type": "boolean", "title": "Optional", "default": false }, "continue_on_error": { "type": "boolean", "title": "Continue On Error", "default": false }, "halt_conditions": { "items": { "$ref": "#/components/schemas/HaltCondition" }, "type": "array", "title": "Halt Conditions" }, "parameters": { "items": { "$ref": "#/components/schemas/StepParameter" }, "type": "array", "title": "Parameters" }, "guards": { "items": { "$ref": "#/components/schemas/StepGuard" }, "type": "array", "title": "Guards" }, "impact_level": { "$ref": "#/components/schemas/ImpactLevel", "default": "medium" }, "run_mode": { "$ref": "#/components/schemas/RunMode", "default": "propose" }, "requires_approval": { "type": "boolean", "title": "Requires Approval", "default": false }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "examples": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StepExample" }, "type": "array" }, { "type": "null" } ], "title": "Examples", "description": "Attached example files for this step. Each entry pairs a platform.file_uploads.file_id with a role + tags + notes so the runtime can shape its instruction. Bounded at 20 to keep a reasonable upper limit on the prompt preamble." }, "applies_when": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applies When", "description": "CEL predicate evaluated at MATERIALIZATION (not at step execution): the step is marked skipped when it evaluates False. Stored verbatim \u2014 the expression is parsed by celpy at launch, so any coercion here would change its meaning." }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "Categorical labels on the step itself (e.g. 'pdf-read', 'coutts', 'fy25'). Free-form; recommended tag set is documented per workstream surface." }, "ref": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Ref", "description": "Skill slug to invoke (e.g. 'derive_period', 'prepare_financial_report')." }, "inputs": { "additionalProperties": true, "type": "object", "title": "Inputs", "description": "Input mapping passed to the skill's typed input model after Jinja2 render." }, "response_format": { "type": "string", "enum": [ "flat", "envelope", "conversational_output" ], "title": "Response Format", "description": "Surface response shape. 'flat' returns the skill output dict; 'envelope' includes the full envelope; 'conversational_output' returns the typed ConversationalOutput shape (conversational skills only).", "default": "flat" } }, "additionalProperties": false, "type": "object", "required": [ "id", "name", "ref" ], "title": "SkillStepDefinition", "description": "Skill step \u2014 invokes a registered system or workspace-authored skill.\n\nDispatches the named skill through the same ``engine_bridge.handle_send``\nused by Connect / MCP / Slack / Teams, so a workstream calling\n``derive_period`` produces byte-identical behaviour to a direct Connect\ninvocation of the same slug. Inputs are Jinja2-rendered against\nruntime_vars + prior_outputs + client_context before being validated\nagainst the skill's typed Pydantic input model." }, "Spec": { "properties": { "decisions": { "items": { "$ref": "#/components/schemas/Decision" }, "type": "array", "title": "Decisions", "description": "Ordered decisions in this spec" }, "bindings": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Bindings", "description": "Compiled bindings keyed by target path" } }, "additionalProperties": false, "type": "object", "title": "Spec", "description": "The full spec for one WorkStream version.\n\nComprises the list of ``decisions`` and the ``bindings`` compiled from the\nanswered ones. This is the object persisted as jsonb and hashed by\n:func:`src.wss.authoring.spec_hash.hash_spec`." }, "StageApproval": { "properties": { "required": { "type": "boolean", "title": "Required", "default": false }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message" }, "show_summary": { "type": "boolean", "title": "Show Summary", "default": true }, "auto_approve_if": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Auto Approve If", "description": "Expression for auto-approval" } }, "additionalProperties": false, "type": "object", "title": "StageApproval", "description": "Approval configuration for a stage." }, "StageStepDefinition": { "properties": { "id": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9_-]+$", "title": "Id" }, "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name" }, "type": { "type": "string", "const": "stage", "title": "Type", "default": "stage" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "depends_on": { "items": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" } ] }, "type": "array", "title": "Depends On" }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stage" }, "timeout": { "anyOf": [ { "type": "string", "pattern": "^\\d+[smhd]$" }, { "type": "null" } ], "title": "Timeout" }, "retry_policy": { "anyOf": [ { "$ref": "#/components/schemas/RetryPolicy" }, { "type": "null" } ] }, "error_handler": { "anyOf": [ { "$ref": "#/components/schemas/StepErrorHandler" }, { "type": "null" } ] }, "emit_artifact": { "anyOf": [ { "$ref": "#/components/schemas/EmitArtifactSpec" }, { "type": "null" } ] }, "optional": { "type": "boolean", "title": "Optional", "default": false }, "continue_on_error": { "type": "boolean", "title": "Continue On Error", "default": false }, "halt_conditions": { "items": { "$ref": "#/components/schemas/HaltCondition" }, "type": "array", "title": "Halt Conditions" }, "parameters": { "items": { "$ref": "#/components/schemas/StepParameter" }, "type": "array", "title": "Parameters" }, "guards": { "items": { "$ref": "#/components/schemas/StepGuard" }, "type": "array", "title": "Guards" }, "impact_level": { "$ref": "#/components/schemas/ImpactLevel", "default": "medium" }, "run_mode": { "$ref": "#/components/schemas/RunMode", "default": "propose" }, "requires_approval": { "type": "boolean", "title": "Requires Approval", "default": false }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "examples": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StepExample" }, "type": "array" }, { "type": "null" } ], "title": "Examples", "description": "Attached example files for this step. Each entry pairs a platform.file_uploads.file_id with a role + tags + notes so the runtime can shape its instruction. Bounded at 20 to keep a reasonable upper limit on the prompt preamble." }, "applies_when": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applies When", "description": "CEL predicate evaluated at MATERIALIZATION (not at step execution): the step is marked skipped when it evaluates False. Stored verbatim \u2014 the expression is parsed by celpy at launch, so any coercion here would change its meaning." }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "Categorical labels on the step itself (e.g. 'pdf-read', 'coutts', 'fy25'). Free-form; recommended tag set is documented per workstream surface." }, "order": { "type": "integer", "minimum": 1.0, "title": "Order" }, "approval": { "anyOf": [ { "$ref": "#/components/schemas/StageApproval" }, { "type": "null" } ] }, "steps": { "items": { "type": "string" }, "type": "array", "title": "Steps" } }, "additionalProperties": false, "type": "object", "required": [ "id", "name", "order" ], "title": "StageStepDefinition", "description": "Stage step - groups steps into a logical phase." }, "StepErrorHandler": { "properties": { "on_error": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "On Error" }, "on_timeout": { "anyOf": [ { "$ref": "#/components/schemas/ErrorAction" }, { "type": "null" } ] }, "catch": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/ErrorAction" }, "type": "object" }, { "type": "null" } ], "title": "Catch", "description": "Error type to action mapping" } }, "additionalProperties": false, "type": "object", "title": "StepErrorHandler", "description": "Per-step error handling configuration." }, "StepExample": { "properties": { "file_id": { "type": "string", "format": "uuid", "title": "File Id", "description": "platform.file_uploads.file_id reference" }, "filename": { "type": "string", "maxLength": 512, "title": "Filename", "description": "Cached filename for UI" }, "size": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Size", "description": "Cached file size in bytes" }, "role": { "$ref": "#/components/schemas/StepExampleRole", "description": "Why this example is attached \u2014 drives runtime injection.", "default": "reference" }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags", "description": "Per-attachment tags (e.g. 'coutts', 'valuation-report', 'fy25')." }, "notes": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Notes", "description": "Free-text notes from the step author." } }, "additionalProperties": false, "type": "object", "required": [ "file_id", "filename" ], "title": "StepExample", "description": "One attached example file on a step.\n\nExamples are resolved at cycle launch \u2014 the runtime fetches the\nfile's extracted preview (filename, page_count, first chunk) and\ninjects it into the LLM prompt or step input bag depending on\nrole. ``input_hint`` is meant to bias chunking / structure\ninference; ``reference`` is documentation the step can cite;\n``schema_sample`` is a representative input the agent should\naccept in production." }, "StepExampleRole": { "type": "string", "enum": [ "input_hint", "reference", "schema_sample" ], "title": "StepExampleRole", "description": "Why this example is attached to the step." }, "StepGuard": { "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$", "title": "Name", "description": "Named contract that is violated." }, "when": { "type": "string", "title": "When", "description": "Jinja2 boolean expression over {{ params. }} / {{ outputs. }}. The guard FIRES (halts) when this is FALSY \u2014 i.e. the asserted invariant does NOT hold." }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message", "description": "Human reason; surfaced as the step's error_message." } }, "additionalProperties": false, "type": "object", "required": [ "name", "when" ], "title": "StepGuard", "description": "AR-727 \u2014 a named guard the runtime reads at execution time.\n\nDistinct from ``HaltCondition`` (a post-execution output check): a guard is a\nNAMED invariant over the resolved step parameters (``{{ params. }}``)\nand the step's outputs (``{{ outputs. }}``) evaluated AFTER the step's\nwork runs. Violating a guard fails closed \u2014 the step is downgraded to\n``success=False`` / ``disposition=\"halted\"`` and the failure NAMES the guard\n\u2014 so an operator knows which named contract was breached, not merely that\n\"a check failed\".\n\n``when`` is a Jinja2 boolean expression evaluated against a ``{params,\noutputs}`` namespace. A guard is a contract the step ASSERTS must hold to\nproceed; it FIRES \u2014 fails closed \u2014 when ``when`` evaluates FALSY (the\ninvariant does NOT hold / is violated). The declared default is what makes\nthe common case pass (e.g. ``when=\"{{ outputs.diff <=\nparams.pay_date_tolerance_days }}\"`` with default 7 holds for a diff of 3\nand fires only for a tie outside the window). A blank/missing ``when``\nnever fires (a named guard with no predicate is a no-op annotation, not a\nfail-closed trap \u2014 fail-closed applies to a stated invariant that does not\nhold, not to a guard that expresses nothing). A ``when`` that raises at\nevaluation time fails closed (the contract could not be verified)." }, "StepParameter": { "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$", "title": "Name", "description": "Binding key." }, "type": { "$ref": "#/components/schemas/ParameterType" }, "default": { "title": "Default", "description": "Value used when no decision override is bound." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" } }, "additionalProperties": false, "type": "object", "required": [ "name", "type", "default" ], "title": "StepParameter", "description": "AR-727 \u2014 a named parameter a step DECLARES with a type and a DEFAULT.\n\nDeclared on ``BaseStepDefinition`` so every step type inherits it (the\nguardrail forbids a per-type dict or ``extra=allow`` as the mechanism \u2014 an\nundeclared key the runtime happens to read is the invisible assumption this\nepic exists to remove). The DECLARED DEFAULT is what makes AR-722's\nwarn-never-block possible: a spec decision can bind ``pay_date_tolerance_days``\nto an arbitrary step and the runtime resolves the default at execution time\nwhile the decision is still open (criterion 5: readable without running).\n\n``name`` is the binding key the runtime exposes as ``{{ params. }}``.\n``type`` reuses ``ParameterType`` (the same vocabulary as context params).\n``default`` is REQUIRED on the declaration \u2014 a parameter without a default\nis exactly the unguarded assumption this surface refuses." }, "StepPayloadResponse": { "properties": { "step_id": { "type": "string", "format": "uuid", "title": "Step Id", "description": "Task UUID whose payload is returned" }, "cycle_id": { "type": "string", "format": "uuid", "title": "Cycle Id", "description": "Parent cycle UUID" }, "size_bytes": { "type": "integer", "minimum": 0.0, "title": "Size Bytes", "description": "UTF-8 JSON byte size of the raw payload" }, "content_uri": { "type": "string", "title": "Content Uri", "description": "content_uri per the wss-bridge convention: 'inline:' for payloads <= 8 KB, else an external reference URI." }, "inline_content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Inline Content", "description": "Decoded payload content, present ONLY when content_uri is inline (payload <= 8 KB). Absent for external references." }, "kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Kind", "description": "Payload kind (tool / step type) for renderer dispatch." } }, "type": "object", "required": [ "step_id", "cycle_id", "size_bytes", "content_uri" ], "title": "ApiRoutersWorkstreamsModels__StepPayloadResponse", "description": "Lazy raw-payload fetch for a single step (run-view canon contract).\n\nReturned by ``GET /cycles/{cycle_id}/steps/{step_id}/payload``. The raw\n``outputs`` JSONB never travels inline on the cycle fetch; it is fetched\nhere only when the UI's Show-payload disclosure opens. Cycle-scoped by\nconstruction \u2014 never served by bare step id." }, "StudioCapabilities": { "properties": { "roles": { "items": { "type": "string", "enum": [ "architect", "operator", "debugger", "reviewer" ] }, "type": "array", "title": "Roles" }, "can": { "$ref": "#/components/schemas/StudioCapabilityMap" }, "approvable_gate_ids": { "items": { "type": "string" }, "type": "array", "title": "Approvable Gate Ids" } }, "type": "object", "required": [ "roles", "can", "approvable_gate_ids" ], "title": "StudioCapabilities", "description": "Response for GET /api/v1/studio/capabilities (TDD_17)." }, "StudioCapabilityMap": { "properties": { "edit_blueprint": { "type": "boolean", "title": "Edit Blueprint" }, "save_blueprint": { "type": "boolean", "title": "Save Blueprint" }, "delete_blueprint": { "type": "boolean", "title": "Delete Blueprint" }, "set_expected_trace": { "type": "boolean", "title": "Set Expected Trace" }, "launch_cycle": { "type": "boolean", "title": "Launch Cycle" }, "abort_cycle": { "type": "boolean", "title": "Abort Cycle" }, "configure_container": { "type": "boolean", "title": "Configure Container" }, "approve_gate": { "type": "boolean", "title": "Approve Gate" }, "view_trace": { "type": "boolean", "title": "View Trace" }, "view_trace_costs": { "type": "boolean", "title": "View Trace Costs" }, "open_deep_inspector": { "type": "boolean", "title": "Open Deep Inspector" }, "view_system_prompt": { "type": "boolean", "title": "View System Prompt" }, "view_raw_json": { "type": "boolean", "title": "View Raw Json" }, "view_xray": { "type": "boolean", "title": "View Xray" }, "edit_prompt": { "type": "boolean", "title": "Edit Prompt" }, "test_fire_prompt": { "type": "boolean", "title": "Test Fire Prompt" }, "bind_knowledge": { "type": "boolean", "title": "Bind Knowledge" }, "edit_knowledge_metadata": { "type": "boolean", "title": "Edit Knowledge Metadata" } }, "type": "object", "required": [ "edit_blueprint", "save_blueprint", "delete_blueprint", "set_expected_trace", "launch_cycle", "abort_cycle", "configure_container", "approve_gate", "view_trace", "view_trace_costs", "open_deep_inspector", "view_system_prompt", "view_raw_json", "view_xray", "edit_prompt", "test_fire_prompt", "bind_knowledge", "edit_knowledge_metadata" ], "title": "StudioCapabilityMap", "description": "Fine-grained capability flags for WorkStream Studio." }, "SubWorkStreamStepDefinition": { "properties": { "id": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9_-]+$", "title": "Id" }, "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name" }, "type": { "type": "string", "const": "sub_workstream", "title": "Type", "default": "sub_workstream" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "depends_on": { "items": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" } ] }, "type": "array", "title": "Depends On" }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stage" }, "timeout": { "anyOf": [ { "type": "string", "pattern": "^\\d+[smhd]$" }, { "type": "null" } ], "title": "Timeout" }, "retry_policy": { "anyOf": [ { "$ref": "#/components/schemas/RetryPolicy" }, { "type": "null" } ] }, "error_handler": { "anyOf": [ { "$ref": "#/components/schemas/StepErrorHandler" }, { "type": "null" } ] }, "emit_artifact": { "anyOf": [ { "$ref": "#/components/schemas/EmitArtifactSpec" }, { "type": "null" } ] }, "optional": { "type": "boolean", "title": "Optional", "default": false }, "continue_on_error": { "type": "boolean", "title": "Continue On Error", "default": false }, "halt_conditions": { "items": { "$ref": "#/components/schemas/HaltCondition" }, "type": "array", "title": "Halt Conditions" }, "parameters": { "items": { "$ref": "#/components/schemas/StepParameter" }, "type": "array", "title": "Parameters" }, "guards": { "items": { "$ref": "#/components/schemas/StepGuard" }, "type": "array", "title": "Guards" }, "impact_level": { "$ref": "#/components/schemas/ImpactLevel", "default": "medium" }, "run_mode": { "$ref": "#/components/schemas/RunMode", "default": "propose" }, "requires_approval": { "type": "boolean", "title": "Requires Approval", "default": false }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "examples": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StepExample" }, "type": "array" }, { "type": "null" } ], "title": "Examples", "description": "Attached example files for this step. Each entry pairs a platform.file_uploads.file_id with a role + tags + notes so the runtime can shape its instruction. Bounded at 20 to keep a reasonable upper limit on the prompt preamble." }, "applies_when": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applies When", "description": "CEL predicate evaluated at MATERIALIZATION (not at step execution): the step is marked skipped when it evaluates False. Stored verbatim \u2014 the expression is parsed by celpy at launch, so any coercion here would change its meaning." }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "Categorical labels on the step itself (e.g. 'pdf-read', 'coutts', 'fy25'). Free-form; recommended tag set is documented per workstream surface." }, "workstream_id": { "type": "string", "title": "Workstream Id", "description": "ID of workstream to invoke" }, "inputs": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Inputs", "description": "Input mappings" }, "outputs": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Outputs", "description": "Output mappings" }, "wait": { "type": "boolean", "title": "Wait", "default": true }, "on_complete": { "anyOf": [ { "$ref": "#/components/schemas/OnCompleteAction" }, { "type": "null" } ] }, "on_failure": { "anyOf": [ { "$ref": "#/components/schemas/BranchAction" }, { "type": "null" } ] } }, "additionalProperties": false, "type": "object", "required": [ "id", "name", "workstream_id" ], "title": "SubWorkStreamStepDefinition", "description": "Sub-workstream step - invokes another workstream." }, "TargetSelector": { "properties": { "type": { "type": "string", "title": "Type", "description": "Selector type: manual, all_active, client_list, tag, single" }, "client_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Client Ids", "description": "For client_list type" }, "client_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Client Id", "description": "For single type" }, "tag": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tag", "description": "For tag type" } }, "type": "object", "required": [ "type" ], "title": "TargetSelector", "description": "Who to run the job for." }, "Task": { "type": "object", "description": "A single step within a Cycle.", "properties": { "id": { "type": "string" }, "cycle_id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "running", "awaiting_approval", "completed", "failed", "skipped" ] }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "output": { "type": "object", "nullable": true } } }, "TaskApprovalRequest": { "properties": { "action": { "$ref": "#/components/schemas/ApprovalAction", "description": "Approval action" }, "comment": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Comment", "description": "Optional comment" } }, "type": "object", "required": [ "action" ], "title": "TaskApprovalRequest", "description": "Request to approve or reject a task.", "example": { "action": "approve", "comment": "Values verified against source documents" } }, "TaskListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/TaskResponse" }, "type": "array", "title": "Items" }, "total": { "type": "integer", "minimum": 0.0, "title": "Total", "description": "Total task count" } }, "type": "object", "required": [ "total" ], "title": "ApiRoutersWorkstreamsModels__TaskListResponse", "description": "List of tasks for a cycle." }, "TaskPlan": { "properties": { "task_id": { "type": "string", "format": "uuid", "title": "Task Id", "description": "Task UUID this plan belongs to" }, "cycle_id": { "type": "string", "format": "uuid", "title": "Cycle Id", "description": "Parent cycle UUID" }, "step_id": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Step Id", "description": "Blueprint step ID this task corresponds to" }, "task_name": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Task Name", "description": "Human-readable task name" }, "summary": { "type": "string", "maxLength": 2000, "minLength": 1, "title": "Summary", "description": "High-level summary of what this task will accomplish" }, "steps": { "items": { "$ref": "#/components/schemas/PlanStep" }, "type": "array", "minItems": 1, "title": "Steps", "description": "Ordered list of execution steps" }, "total_estimated_duration_seconds": { "anyOf": [ { "type": "integer", "minimum": 1.0 }, { "type": "null" } ], "title": "Total Estimated Duration Seconds", "description": "Total estimated duration for all steps combined" }, "write_operation_count": { "type": "integer", "minimum": 0.0, "title": "Write Operation Count", "description": "Number of steps that perform write operations", "default": 0 }, "high_risk_step_count": { "type": "integer", "minimum": 0.0, "title": "High Risk Step Count", "description": "Number of steps classified as high risk", "default": 0 }, "requires_approval": { "type": "boolean", "title": "Requires Approval", "description": "Whether this task requires user approval before execution", "default": false }, "approval_reason": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "title": "Approval Reason", "description": "Explanation of why approval is required (if applicable)" }, "context_used": { "items": { "type": "string" }, "type": "array", "title": "Context Used", "description": "List of context sources used to generate this plan" }, "generated_at": { "type": "string", "format": "date-time", "title": "Generated At", "description": "Timestamp when this plan was generated" }, "model_version": { "type": "string", "maxLength": 100, "title": "Model Version", "description": "AI model version used to generate this plan", "default": "unspecified" } }, "type": "object", "required": [ "task_id", "cycle_id", "step_id", "task_name", "summary", "steps", "generated_at" ], "title": "TaskPlan", "description": "Complete AI-generated execution plan for a workstream task.\n\nGenerated before task execution to provide transparency about\nwhat the AI will do. Stored in task.plan_summary for audit trail." }, "TaskResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Task UUID" }, "permakey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Permakey", "description": "Stable human-readable task/instance key for the nested deep-link URL .../cycles/{cycle}/instance/{permakey}. Null on legacy rows." }, "cycle_id": { "type": "string", "format": "uuid", "title": "Cycle Id", "description": "Parent cycle UUID" }, "step_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Step Id", "description": "Blueprint step id this task corresponds to (FE OutputsViewer resolver)" }, "step_index": { "type": "integer", "minimum": 0.0, "title": "Step Index", "description": "Step index in workflow" }, "name": { "type": "string", "title": "Name", "description": "Task name" }, "type": { "type": "string", "title": "Type", "description": "Task type (domain type for display: extraction, validation, etc.)" }, "status": { "$ref": "#/components/schemas/TaskStatus", "description": "Task status" }, "requires_approval": { "type": "boolean", "title": "Requires Approval", "description": "Whether task requires approval", "default": false }, "gate_record": { "anyOf": [ { "$ref": "#/components/schemas/RunGateRecord" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Plain-English description of what this step does, derived once at save time from the step definition and stored. NULL on legacy rows that were never derived." }, "input_data": { "additionalProperties": true, "type": "object", "title": "Input Data", "description": "Task input" }, "output_data": { "additionalProperties": true, "type": "object", "title": "Output Data", "description": "Task output" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Message", "description": "Why this step did not complete, written for an accountant. Composed by src.workstreams.language \u2014 the raw engine/approver text is on error_details and is the only place it appears." }, "error_details": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Details", "description": "The engine's or the approver's own words for this step, verbatim and unshortened, for a Details affordance. Never rendered inline." }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Started At", "description": "Start timestamp" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Completed At", "description": "Completion timestamp" }, "approved_by": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Approved By", "description": "Approver user ID" }, "approved_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Approved At", "description": "Approval timestamp" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Last update timestamp" }, "reasoning_summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reasoning Summary", "description": "The step's reasoning trace summary (workstreams.task.thinking_summary). NULL on older cycles or steps that recorded no reasoning." }, "tokens_input": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tokens Input", "description": "Input tokens consumed by this step. NULL on legacy rows." }, "tokens_output": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tokens Output", "description": "Output tokens produced by this step. NULL on legacy rows." }, "duration_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Duration Ms", "description": "Wall-time of this step in ms (persisted duration_ms, else completed_at - started_at). NULL when not started / no timestamps." }, "customer_cost_gbp": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Customer Cost Gbp", "description": "What this STEP cost the customer: its execution time x the organisation's hourly rate. Same figure as the cycle-level field of the same name, one grain finer.\n\nNamed `customer_cost_gbp`, not `cost_gbp`: the wire-boundary contract bans any read model carrying a bare cost noun, because `cost_cents` (our token spend) must never reach a browser. A field called `cost_gbp` cannot be told apart from that at a glance, and the guard was right to refuse it.\n\nThe value was already being computed and passed by _cycles.py and silently discarded, because no such field existed here." }, "tool": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tool", "description": "Tool/action that performed this step (step_definition.tool, else the structural type). Drives the FE tool chip + payload typing." }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "One accountant-English line authored at step completion (e.g. 'Read Doc 1 \u2014 36pp \u00b7 4s'); the honesty line when no judgment was recorded. Server-capped < 500 chars; never a dump." }, "payload_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Payload Ref", "description": "content_uri reference to this step's raw payload: 'inline:' when <= 8 KB, else 'workstreams://step/{id}/payload' resolved by GET /cycles/{cycle_id}/steps/{step_id}/payload. Absent when the step produced no payload." }, "payload_size_bytes": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Payload Size Bytes", "description": "Byte size of the raw payload (UTF-8 JSON) \u2014 the UI's size hint for the Show-payload disclosure. Null when no payload." } }, "type": "object", "required": [ "id", "cycle_id", "step_index", "name", "type", "status", "created_at", "updated_at" ], "title": "ApiRoutersWorkstreamsModels__TaskResponse", "description": "Task response model." }, "TaskStatus": { "type": "string", "enum": [ "pending", "planning", "pending_approval", "upload_document", "running", "paused", "blocked", "awaiting_approval", "approved", "rejected", "done", "completed", "failed", "skipped" ], "title": "TaskStatus", "description": "Status for individual tasks.\n\nDatabase constraint: pending, running, paused, blocked, done, skipped, failed\nAdditional API statuses: planning, pending_approval, awaiting_approval, approved, rejected, completed" }, "TaskStepDefinition": { "properties": { "id": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9_-]+$", "title": "Id" }, "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name" }, "type": { "type": "string", "const": "task", "title": "Type", "default": "task" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "depends_on": { "items": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" } ] }, "type": "array", "title": "Depends On" }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stage" }, "timeout": { "anyOf": [ { "type": "string", "pattern": "^\\d+[smhd]$" }, { "type": "null" } ], "title": "Timeout" }, "retry_policy": { "anyOf": [ { "$ref": "#/components/schemas/RetryPolicy" }, { "type": "null" } ] }, "error_handler": { "anyOf": [ { "$ref": "#/components/schemas/StepErrorHandler" }, { "type": "null" } ] }, "emit_artifact": { "anyOf": [ { "$ref": "#/components/schemas/EmitArtifactSpec" }, { "type": "null" } ] }, "optional": { "type": "boolean", "title": "Optional", "default": false }, "continue_on_error": { "type": "boolean", "title": "Continue On Error", "default": false }, "halt_conditions": { "items": { "$ref": "#/components/schemas/HaltCondition" }, "type": "array", "title": "Halt Conditions" }, "parameters": { "items": { "$ref": "#/components/schemas/StepParameter" }, "type": "array", "title": "Parameters" }, "guards": { "items": { "$ref": "#/components/schemas/StepGuard" }, "type": "array", "title": "Guards" }, "impact_level": { "$ref": "#/components/schemas/ImpactLevel", "default": "medium" }, "run_mode": { "$ref": "#/components/schemas/RunMode", "default": "propose" }, "requires_approval": { "type": "boolean", "title": "Requires Approval", "default": false }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "examples": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StepExample" }, "type": "array" }, { "type": "null" } ], "title": "Examples", "description": "Attached example files for this step. Each entry pairs a platform.file_uploads.file_id with a role + tags + notes so the runtime can shape its instruction. Bounded at 20 to keep a reasonable upper limit on the prompt preamble." }, "applies_when": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applies When", "description": "CEL predicate evaluated at MATERIALIZATION (not at step execution): the step is marked skipped when it evaluates False. Stored verbatim \u2014 the expression is parsed by celpy at launch, so any coercion here would change its meaning." }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "Categorical labels on the step itself (e.g. 'pdf-read', 'coutts', 'fy25'). Free-form; recommended tag set is documented per workstream surface." }, "agent": { "type": "string", "title": "Agent", "description": "Agent type" }, "instruction": { "type": "string", "title": "Instruction", "description": "Natural language instruction" }, "tools": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tools", "description": "Allowed tools" }, "inputs": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Inputs", "description": "Input mappings" }, "outputs": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/OutputDefinition" }, "type": "object" }, { "type": "null" } ], "title": "Outputs", "description": "Output definitions" }, "on_complete": { "anyOf": [ { "$ref": "#/components/schemas/OnCompleteAction" }, { "type": "null" } ] } }, "additionalProperties": false, "type": "object", "required": [ "id", "name", "agent", "instruction" ], "title": "TaskStepDefinition", "description": "Task step - executes an action with AI agent." }, "TemplateCreate": { "properties": { "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name", "description": "Template name" }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Description", "description": "Template description" }, "category": { "anyOf": [ { "type": "string", "enum": [ "compliance", "advisory", "audit", "bookkeeping", "tax", "internal" ] }, { "type": "null" } ], "title": "Category", "description": "Template category (closed taxonomy; off-taxonomy input is mapped)" }, "steps": { "items": { "oneOf": [ { "$ref": "#/components/schemas/TaskStepDefinition" }, { "$ref": "#/components/schemas/ToolCallStepDefinition" }, { "$ref": "#/components/schemas/ArchieQueryStepDefinition" }, { "$ref": "#/components/schemas/NotifyStepDefinition" }, { "$ref": "#/components/schemas/ConditionalStepDefinition" }, { "$ref": "#/components/schemas/LoopStepDefinition" }, { "$ref": "#/components/schemas/ParallelStepDefinition" }, { "$ref": "#/components/schemas/ApprovalStepDefinition" }, { "$ref": "#/components/schemas/DocumentUploadStepDefinition" }, { "$ref": "#/components/schemas/StageStepDefinition" }, { "$ref": "#/components/schemas/GotoStepDefinition" }, { "$ref": "#/components/schemas/SubWorkStreamStepDefinition" }, { "$ref": "#/components/schemas/DeterministicExtractionStepDefinition" }, { "$ref": "#/components/schemas/VerificationStepDefinition" }, { "$ref": "#/components/schemas/EmailSendStepDefinition" }, { "$ref": "#/components/schemas/WaitForReplyStepDefinition" }, { "$ref": "#/components/schemas/SkillStepDefinition" }, { "$ref": "#/components/schemas/AgentRunStepDefinition" }, { "$ref": "#/components/schemas/WaitStepDefinition" }, { "$ref": "#/components/schemas/WebhookStepDefinition" }, { "$ref": "#/components/schemas/FormStepDefinition" }, { "$ref": "#/components/schemas/FileStepDefinition" } ], "discriminator": { "propertyName": "type", "mapping": { "agent_run": "#/components/schemas/AgentRunStepDefinition", "approval": "#/components/schemas/ApprovalStepDefinition", "archie_query": "#/components/schemas/ArchieQueryStepDefinition", "conditional": "#/components/schemas/ConditionalStepDefinition", "deterministic_extraction": "#/components/schemas/DeterministicExtractionStepDefinition", "document_upload": "#/components/schemas/DocumentUploadStepDefinition", "email_send": "#/components/schemas/EmailSendStepDefinition", "file": "#/components/schemas/FileStepDefinition", "form": "#/components/schemas/FormStepDefinition", "goto": "#/components/schemas/GotoStepDefinition", "loop": "#/components/schemas/LoopStepDefinition", "notify": "#/components/schemas/NotifyStepDefinition", "parallel": "#/components/schemas/ParallelStepDefinition", "skill": "#/components/schemas/SkillStepDefinition", "stage": "#/components/schemas/StageStepDefinition", "sub_workstream": "#/components/schemas/SubWorkStreamStepDefinition", "task": "#/components/schemas/TaskStepDefinition", "tool_call": "#/components/schemas/ToolCallStepDefinition", "verification": "#/components/schemas/VerificationStepDefinition", "wait": "#/components/schemas/WaitStepDefinition", "wait_for_reply": "#/components/schemas/WaitForReplyStepDefinition", "webhook": "#/components/schemas/WebhookStepDefinition" } } }, "type": "array", "title": "Steps", "description": "WDL step definitions" }, "default_config": { "additionalProperties": true, "type": "object", "title": "Default Config", "description": "Default configuration" }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags", "description": "Template tags" }, "input_schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Input Schema", "description": "Declared workstream inputs (array of InputDef: name/type/required/...)." }, "output_schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Output Schema", "description": "Declared workstream outputs (array of OutputDef: name/label/type/format/...)." }, "execution_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Execution Mode", "description": "Execution mode" }, "jurisdictions": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Jurisdictions", "description": "Applicable jurisdictions" }, "owner": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner", "description": "Owner (owning_team_id)" }, "goal_spec": { "anyOf": [ { "$ref": "#/components/schemas/GoalSpecPayload" }, { "type": "null" } ], "description": "Optional goal contract scored by the deterministic goal gate after each cycle. A workstream is launchable with steps OR a goal_spec." }, "accounting_ledger": { "type": "string", "enum": [ "off", "optional", "required" ], "title": "Accounting Ledger", "description": "Cycle Accounting Ledger capability. Most WorkStreams leave this off; optional exposes Ledger tools on demand; required makes a frozen Ledger checkpoint a completion condition.", "default": "off" } }, "type": "object", "required": [ "name" ], "title": "TemplateCreate", "description": "Request to create a new template with WDL steps.", "example": { "category": "reconciliation", "description": "Automated month-end close process", "name": "Monthly Close Reconciliation", "steps": [ { "agent": "data_extraction", "id": "fetch-data", "impact_level": "low", "instruction": "Fetch trial balance for period {{ context.parameters.period }}", "name": "Fetch Trial Balance", "run_mode": "auto_run", "type": "task" }, { "agent": "validation", "depends_on": [ "fetch-data" ], "id": "validate-data", "impact_level": "low", "instruction": "Validate the fetched data for completeness", "name": "Validate Balances", "run_mode": "auto_run", "type": "task" }, { "actions": { "approve": { "label": "Approve", "next": "complete" }, "reject": { "label": "Reject", "require_reason": true } }, "depends_on": [ "validate-data" ], "id": "approval-gate", "impact_level": "high", "name": "Review & Approve", "summary": { "description": "Review data before proceeding", "title": "Month-End Close Review" }, "type": "approval" } ], "tags": [ "month-end", "reconciliation" ] } }, "TemplateListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/TemplateResponse" }, "type": "array", "title": "Items" }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object", "required": [ "pagination" ], "title": "TemplateListResponse", "description": "Paginated list of templates." }, "TemplateResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Template UUID" }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Slug", "description": "Human-readable URL key (e.g. 'asc-606-review'). Stable + globally unique; resolvable by GET /templates/{id}. Link the FE here, not the UUID." }, "permakey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Permakey", "description": "Stable opaque short id (7-char); the cross-entity permalink, also resolvable." }, "name": { "type": "string", "title": "Name", "description": "Template name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Template description" }, "source_description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Description", "description": "The definition's own text, verbatim (the audit-true record of what was authored). Disclosed behind 'The definition, as written', in mono \u2014 never the firm-facing head. NULL when the definition has no prose distinct from the interpreted description." }, "source_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Name", "description": "The definition's own name, verbatim. Disclosed alongside source_description when it differs from the firm-facing name." }, "category": { "anyOf": [ { "type": "string", "enum": [ "compliance", "advisory", "audit", "bookkeeping", "tax", "internal" ] }, { "type": "null" } ], "title": "Category", "description": "Template category (closed taxonomy: compliance/advisory/audit/bookkeeping/tax/internal). NULL = genuinely uncategorised (no category set); 'internal' = an off-taxonomy value mapped to the catch-all bucket \u2014 the two are distinct (NULL is NOT coerced to 'internal')." }, "steps": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Steps", "description": "WDL step definitions" }, "default_config": { "additionalProperties": true, "type": "object", "title": "Default Config", "description": "Default configuration" }, "goal_spec": { "anyOf": [ { "$ref": "#/components/schemas/GoalSpecPayload-Output" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Goal Spec", "description": "The versioned deterministic goal contract. This is definition state, not cycle output, and must round-trip through every authoring surface." }, "accounting_ledger": { "type": "string", "enum": [ "off", "optional", "required" ], "title": "Accounting Ledger", "description": "The WorkStream's explicit Cycle Accounting Ledger capability.", "default": "off" }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags", "description": "Template tags" }, "input_schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Input Schema", "description": "Declared workstream inputs (array of InputDef: name/type/required/...)." }, "families": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Families" }, "output_schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Output Schema", "description": "Declared workstream outputs for the Outputs tab (array of OutputDef: name/label/type/format/...). Empty \u21d2 no Outputs tab." }, "forked_from": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Forked From", "description": "Provenance: parent recipe {name, version} this was forked from. NULL when not a fork." }, "upstream_update": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Upstream Update", "description": "{version, note} when the fork's parent has advanced past the fork point. NULL when none/uncomputable." }, "is_template": { "type": "boolean", "title": "Is Template", "description": "Always true for templates", "default": true }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain", "description": "DomainAgent knowledge-key backing this recipe (e.g. 'ita_2007_eis'), resolved from the linked job_definition.domain via its most-recent cycle and surfaced ONLY when it maps to a real DomainAgent persona. NULL for fixed-step recipes and generic agentic containers (the 'workstream'/'general' placeholder domains) \u2014 which are NOT WorkPlan-able. The WorkPlan-create picker filters to `domain != null`." }, "status": { "$ref": "#/components/schemas/WorkstreamStatus", "description": "Template status" }, "version": { "type": "integer", "title": "Version", "description": "Template version, incremented on each update", "default": 1 }, "active_blueprint_count": { "type": "integer", "title": "Active Blueprint Count", "description": "Number of active linked workplans for this template", "default": 0 }, "total_runs": { "type": "integer", "title": "Total Runs", "description": "Count of cycles ever launched from this template (run count).", "default": 0 }, "total_instances": { "type": "integer", "title": "Total Instances", "description": "Aggregate instance count across all cycles. Each backend cycle is one instance run, so this equals total_runs today; kept distinct so the FE contract is stable if job-level fan-out grouping lands later.", "default": 0 }, "last_run_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Run At", "description": "Start (or creation) timestamp of the most recent cycle. NULL if never run." }, "last_run_state": { "anyOf": [ { "$ref": "#/components/schemas/CycleStatus" }, { "type": "null" } ], "description": "Status of the most recent cycle, for the 'last run' badge. NULL if never run." }, "avg_instance_cost": { "type": "number", "title": "Avg Instance Cost", "description": "Average customer-facing cost (GBP) across runs: mean of \u00a319/hr x elapsed per cycle. Mirrors CycleResponse.customer_cost_gbp.", "default": 0.0 }, "cycle_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "title": "Cycle Ids", "description": "Cycle ids that have run this template, most recent first (capped)." }, "needs_you_count": { "type": "integer", "title": "Needs You Count", "description": "Instances of this WorkStream parked at an approval gate, waiting on a person. APPROVALS ONLY \u2014 blocked (waiting on the client) and errored (needs a retry) are different asks and are counted elsewhere, so the orange attention number means the same thing on the list card, the WorkStream page and a cycle's triage.", "default": 0 }, "needs_you_job_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Needs You Job Id", "description": "The batch holding the most of those approvals \u2014 the DOOR the attention chip opens, so the count is never a claim the user then has to hunt for. NULL when needs_you_count is 0, and ALSO null when the gated instances belong to no batch (a standalone run has no fan-out to open). A non-zero count with a null door is therefore expected: fall back to the WorkStream's own Cycles tab, which is always reachable \u2014 never render the count as unclickable." }, "created_by": { "type": "string", "format": "uuid", "title": "Created By", "description": "Creator user ID" }, "created_by_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created By Name", "description": "Creator display name" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Last update timestamp" }, "scope": { "type": "string", "title": "Scope", "description": "Distribution scope: gallery|firm|team|user|plan (provenance pill).", "default": "firm" }, "is_catalog": { "type": "boolean", "title": "Is Catalog", "description": "True for curated public library recipes (the seeded catalog).", "default": false }, "owning_team_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Owning Team Id", "description": "The team a `scope='team'` workstream belongs to \u2014 lets the FE group the My WorkStreams list under the team name (#170). NULL for firm/user-scoped rows." }, "workspace_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Workspace Id", "description": "Workspace ID owning this template, or NULL for catalog/curated recipes" }, "lint": { "items": { "type": "string" }, "type": "array", "title": "Lint", "description": "ADVISORY structural findings for the saved step set \u2014 duplicate ids, dangling depends_on, dependency cycles, unresolvable references. Entries prefixed `warn:` are advisory by the linter's own tiering. This NEVER blocks a save and an empty list is not a guarantee: see the note on the update handler for why a hard gate would be wrong against today's stored data." } }, "type": "object", "required": [ "id", "name", "status", "created_by", "created_at", "updated_at" ], "title": "TemplateResponse", "description": "Template response model." }, "TemplateUpdate": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 200, "minLength": 1 }, { "type": "null" } ], "title": "Name", "description": "Template name" }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Description", "description": "Template description" }, "source_description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Source Description", "description": "The definition's own text, verbatim." }, "source_name": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Source Name", "description": "The definition's own name, verbatim." }, "category": { "anyOf": [ { "type": "string", "enum": [ "compliance", "advisory", "audit", "bookkeeping", "tax", "internal" ] }, { "type": "null" } ], "title": "Category", "description": "Template category (closed taxonomy; off-taxonomy input is mapped)" }, "steps": { "anyOf": [ { "items": { "oneOf": [ { "$ref": "#/components/schemas/TaskStepDefinition" }, { "$ref": "#/components/schemas/ToolCallStepDefinition" }, { "$ref": "#/components/schemas/ArchieQueryStepDefinition" }, { "$ref": "#/components/schemas/NotifyStepDefinition" }, { "$ref": "#/components/schemas/ConditionalStepDefinition" }, { "$ref": "#/components/schemas/LoopStepDefinition" }, { "$ref": "#/components/schemas/ParallelStepDefinition" }, { "$ref": "#/components/schemas/ApprovalStepDefinition" }, { "$ref": "#/components/schemas/DocumentUploadStepDefinition" }, { "$ref": "#/components/schemas/StageStepDefinition" }, { "$ref": "#/components/schemas/GotoStepDefinition" }, { "$ref": "#/components/schemas/SubWorkStreamStepDefinition" }, { "$ref": "#/components/schemas/DeterministicExtractionStepDefinition" }, { "$ref": "#/components/schemas/VerificationStepDefinition" }, { "$ref": "#/components/schemas/EmailSendStepDefinition" }, { "$ref": "#/components/schemas/WaitForReplyStepDefinition" }, { "$ref": "#/components/schemas/SkillStepDefinition" }, { "$ref": "#/components/schemas/AgentRunStepDefinition" }, { "$ref": "#/components/schemas/WaitStepDefinition" }, { "$ref": "#/components/schemas/WebhookStepDefinition" }, { "$ref": "#/components/schemas/FormStepDefinition" }, { "$ref": "#/components/schemas/FileStepDefinition" } ], "discriminator": { "propertyName": "type", "mapping": { "agent_run": "#/components/schemas/AgentRunStepDefinition", "approval": "#/components/schemas/ApprovalStepDefinition", "archie_query": "#/components/schemas/ArchieQueryStepDefinition", "conditional": "#/components/schemas/ConditionalStepDefinition", "deterministic_extraction": "#/components/schemas/DeterministicExtractionStepDefinition", "document_upload": "#/components/schemas/DocumentUploadStepDefinition", "email_send": "#/components/schemas/EmailSendStepDefinition", "file": "#/components/schemas/FileStepDefinition", "form": "#/components/schemas/FormStepDefinition", "goto": "#/components/schemas/GotoStepDefinition", "loop": "#/components/schemas/LoopStepDefinition", "notify": "#/components/schemas/NotifyStepDefinition", "parallel": "#/components/schemas/ParallelStepDefinition", "skill": "#/components/schemas/SkillStepDefinition", "stage": "#/components/schemas/StageStepDefinition", "sub_workstream": "#/components/schemas/SubWorkStreamStepDefinition", "task": "#/components/schemas/TaskStepDefinition", "tool_call": "#/components/schemas/ToolCallStepDefinition", "verification": "#/components/schemas/VerificationStepDefinition", "wait": "#/components/schemas/WaitStepDefinition", "wait_for_reply": "#/components/schemas/WaitForReplyStepDefinition", "webhook": "#/components/schemas/WebhookStepDefinition" } } }, "type": "array" }, { "type": "null" } ], "title": "Steps", "description": "WDL step definitions" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "Template tags" }, "input_schema": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Input Schema", "description": "Declared workstream inputs (array of InputDef)." }, "output_schema": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Output Schema", "description": "Declared workstream outputs (array of OutputDef)." }, "status": { "anyOf": [ { "$ref": "#/components/schemas/WorkstreamStatus" }, { "type": "null" } ], "description": "Template status" }, "goal_spec": { "anyOf": [ { "$ref": "#/components/schemas/GoalSpecPayload" }, { "type": "null" } ], "description": "Goal contract scored by the deterministic goal gate. Omit to leave the existing goal untouched; the tolerances a reviewer already approved must not change just because an unrelated field did." }, "spec": { "anyOf": [ { "$ref": "#/components/schemas/Spec" }, { "type": "null" } ], "description": "The WSS spec (decisions + compiled bindings) for the new version. Persisted with spec_hash and definition_hash on the version snapshot. Every cited document_id must be an upload in this workspace. Omit to keep the latest version's spec (definition_hash recomputed over the new steps)." }, "change_summary": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "title": "Change Summary", "description": "Caller-supplied version-history note (e.g. 'Revised from cycle : \u2026'). Falls back to the auto-computed field list when omitted." }, "accounting_ledger": { "anyOf": [ { "type": "string", "enum": [ "off", "optional", "required" ] }, { "type": "null" } ], "title": "Accounting Ledger", "description": "Change the Cycle Accounting Ledger capability. Omit to preserve it; use off for WorkStreams that do not need a Ledger." }, "shared_with_user_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Shared With User Ids", "description": "User IDs granted editor rights to this workstream definition." } }, "type": "object", "title": "TemplateUpdate", "description": "Request to update a template." }, "TemplateVersionEntry": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "workstream_id": { "type": "string", "format": "uuid", "title": "Workstream Id" }, "version": { "type": "integer", "title": "Version" }, "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "steps": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Steps" }, "goal_spec": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Goal Spec" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags" }, "accounting_ledger": { "type": "string", "enum": [ "off", "optional", "required" ], "title": "Accounting Ledger", "default": "off" }, "change_summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Change Summary" }, "created_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created By" }, "created_by_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created By Name" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "type": "object", "required": [ "id", "workstream_id", "version", "name", "created_at" ], "title": "TemplateVersionEntry", "description": "A snapshot of a template at a specific version." }, "TemplateVersionListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/TemplateVersionEntry" }, "type": "array", "title": "Items" }, "current_version": { "type": "integer", "title": "Current Version" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "current_version", "total" ], "title": "TemplateVersionListResponse", "description": "List of template version snapshots." }, "ToolCallStepDefinition": { "properties": { "id": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9_-]+$", "title": "Id" }, "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name" }, "type": { "type": "string", "const": "tool_call", "title": "Type", "default": "tool_call" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "depends_on": { "items": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" } ] }, "type": "array", "title": "Depends On" }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stage" }, "timeout": { "anyOf": [ { "type": "string", "pattern": "^\\d+[smhd]$" }, { "type": "null" } ], "title": "Timeout" }, "retry_policy": { "anyOf": [ { "$ref": "#/components/schemas/RetryPolicy" }, { "type": "null" } ] }, "error_handler": { "anyOf": [ { "$ref": "#/components/schemas/StepErrorHandler" }, { "type": "null" } ] }, "emit_artifact": { "anyOf": [ { "$ref": "#/components/schemas/EmitArtifactSpec" }, { "type": "null" } ] }, "optional": { "type": "boolean", "title": "Optional", "default": false }, "continue_on_error": { "type": "boolean", "title": "Continue On Error", "default": false }, "halt_conditions": { "items": { "$ref": "#/components/schemas/HaltCondition" }, "type": "array", "title": "Halt Conditions" }, "parameters": { "items": { "$ref": "#/components/schemas/StepParameter" }, "type": "array", "title": "Parameters" }, "guards": { "items": { "$ref": "#/components/schemas/StepGuard" }, "type": "array", "title": "Guards" }, "impact_level": { "$ref": "#/components/schemas/ImpactLevel", "default": "medium" }, "run_mode": { "$ref": "#/components/schemas/RunMode", "default": "propose" }, "requires_approval": { "type": "boolean", "title": "Requires Approval", "default": false }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "examples": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StepExample" }, "type": "array" }, { "type": "null" } ], "title": "Examples", "description": "Attached example files for this step. Each entry pairs a platform.file_uploads.file_id with a role + tags + notes so the runtime can shape its instruction. Bounded at 20 to keep a reasonable upper limit on the prompt preamble." }, "applies_when": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applies When", "description": "CEL predicate evaluated at MATERIALIZATION (not at step execution): the step is marked skipped when it evaluates False. Stored verbatim \u2014 the expression is parsed by celpy at launch, so any coercion here would change its meaning." }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "Categorical labels on the step itself (e.g. 'pdf-read', 'coutts', 'fy25'). Free-form; recommended tag set is documented per workstream surface." }, "tool_name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Tool Name", "description": "V4 tool identifier (e.g. 'read_pdf_document', 'generate_pdf')." }, "tool_params": { "additionalProperties": true, "type": "object", "title": "Tool Params", "description": "Free-form parameter bag forwarded to the V4 tool. May contain Jinja2 placeholders like '{{ inputs.* }}'." }, "expected_outputs": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Expected Outputs", "description": "Optional output schema hints (name + type per entry)." }, "instruction": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instruction", "description": "Optional natural-language instruction the runtime can use to shape the tool dispatch (e.g. prompt preamble for LLM-style tools)." }, "inputs": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Inputs", "description": "Input mappings \u2014 same Jinja2 surface as TaskStep." } }, "additionalProperties": false, "type": "object", "required": [ "id", "name", "tool_name" ], "title": "ToolCallStepDefinition", "description": "Tool-call step \u2014 dispatches a single named V4 tool.\n\nStuart 2026-05-19: the read-shape stored in\n``workstreams.workstream.steps`` for V4 workstream templates uses\n``type='tool_call'`` with ``tool_name``/``tool_params`` directly on\nthe step. The write-side schema previously had no such variant,\nwhich caused every PATCH that included an existing tool_call step\nto 422 (`StepEditOverride` localStorage workaround in\n`apps/workstream-studio/src/lib/stepEditOverrides.ts`). This class\ncloses that round-trip gap.\n\nFields are intentionally permissive: ``tool_params`` is the same\nfree-form ``dict`` the cycle launcher already passes through into\n``task.step_definition``. The V4 executor reads ``tool_name`` +\n``tool_params`` directly off the step blob." }, "ToolListResponse": { "properties": { "tools": { "items": { "$ref": "#/components/schemas/ToolResponse" }, "type": "array", "title": "Tools" }, "count": { "type": "integer", "title": "Count" } }, "type": "object", "required": [ "tools", "count" ], "title": "ToolListResponse", "description": "Response from listing custom tools." }, "ToolRegisterRequest": { "properties": { "name": { "type": "string", "maxLength": 100, "title": "Name", "description": "Unique tool name within the workspace" }, "display_name": { "type": "string", "maxLength": 255, "title": "Display Name", "description": "Human-readable name" }, "description": { "type": "string", "title": "Description", "description": "What the tool does", "default": "" }, "category": { "type": "string", "title": "Category", "description": "Tool category", "default": "custom" }, "endpoint_path": { "type": "string", "title": "Endpoint Path", "description": "HTTP path (e.g. /api/v1/integrations/data/invoices)" }, "http_method": { "type": "string", "title": "Http Method", "description": "HTTP method (GET, POST, PUT, PATCH, DELETE)", "default": "GET" }, "parameters": { "additionalProperties": true, "type": "object", "title": "Parameters", "description": "JSON Schema for tool input parameters" }, "auth_config": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Auth Config", "description": "Optional auth configuration. {\"type\": \"bearer\", \"token\": \"...\"} for bearer auth, {\"type\": \"api_key\", \"api_key\": \"...\", \"header_name\": \"X-API-Key\"} for API keys. NOTE: e2e_bypass is NOT available via the API \u2014 it is operator-only." } }, "type": "object", "required": [ "name", "display_name", "endpoint_path" ], "title": "ToolRegisterRequest", "description": "Request to register a custom HTTP tool." }, "ToolResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "display_name": { "type": "string", "title": "Display Name" }, "description": { "type": "string", "title": "Description" }, "category": { "type": "string", "title": "Category" }, "endpoint_path": { "type": "string", "title": "Endpoint Path" }, "http_method": { "type": "string", "title": "Http Method" }, "parameters": { "additionalProperties": true, "type": "object", "title": "Parameters" }, "auth_config": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Auth Config" }, "workspace_id": { "type": "string", "format": "uuid", "title": "Workspace Id" }, "is_enabled": { "type": "boolean", "title": "Is Enabled" } }, "type": "object", "required": [ "id", "name", "display_name", "description", "category", "endpoint_path", "http_method", "parameters", "auth_config", "workspace_id", "is_enabled" ], "title": "ToolResponse", "description": "Response from tool registration." }, "TriggerCreate": { "properties": { "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name", "description": "Trigger name" }, "type": { "$ref": "#/components/schemas/TriggerType", "description": "Trigger type" }, "config": { "additionalProperties": true, "type": "object", "title": "Config", "description": "Trigger configuration" }, "is_active": { "type": "boolean", "title": "Is Active", "description": "Whether trigger is active", "default": true } }, "type": "object", "required": [ "name", "type" ], "title": "ApiRoutersWorkstreamsModels__TriggerCreate", "description": "Request to create a trigger.", "example": { "config": { "cron": "0 9 1 * *", "timezone": "America/New_York" }, "is_active": true, "name": "Monthly Run", "type": "time_based" } }, "TriggerListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/TriggerResponse" }, "type": "array", "title": "Items" }, "total": { "type": "integer", "minimum": 0.0, "title": "Total", "description": "Total trigger count" } }, "type": "object", "required": [ "total" ], "title": "ApiRoutersWorkstreamsModels__TriggerListResponse", "description": "List of triggers for a workplan." }, "TriggerResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Trigger UUID" }, "workplan_id": { "type": "string", "format": "uuid", "title": "Workplan Id", "description": "Parent WorkPlan UUID" }, "name": { "type": "string", "title": "Name", "description": "Trigger name" }, "type": { "$ref": "#/components/schemas/TriggerType", "description": "Trigger type" }, "config": { "additionalProperties": true, "type": "object", "title": "Config", "description": "Trigger configuration" }, "is_active": { "type": "boolean", "title": "Is Active", "description": "Whether trigger is active" }, "last_fired_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Fired At", "description": "Last trigger timestamp" }, "next_fire_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Next Fire At", "description": "Next scheduled trigger" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Last update timestamp" } }, "type": "object", "required": [ "id", "workplan_id", "name", "type", "is_active", "created_at", "updated_at" ], "title": "ApiRoutersWorkstreamsModels__TriggerResponse", "description": "Trigger response model." }, "TriggerType": { "type": "string", "enum": [ "time_based", "event_based", "manual" ], "title": "TriggerType", "description": "Types of workflow triggers." }, "TriggerUpdate": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 200, "minLength": 1 }, { "type": "null" } ], "title": "Name", "description": "Trigger name" }, "config": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Config", "description": "Trigger configuration" }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Active", "description": "Whether trigger is active" } }, "type": "object", "title": "ApiRoutersWorkstreamsModels__TriggerUpdate", "description": "Request to update a trigger." }, "UploadConfig": { "properties": { "required_documents": { "items": { "$ref": "#/components/schemas/RequiredDocument" }, "type": "array", "title": "Required Documents" }, "max_files": { "type": "integer", "minimum": 1.0, "title": "Max Files", "default": 20 }, "max_file_size_mb": { "type": "integer", "minimum": 1.0, "title": "Max File Size Mb", "default": 10 }, "instructions": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ], "title": "Instructions", "description": "Jinja2 template for upload instructions" } }, "additionalProperties": false, "type": "object", "title": "UploadConfig", "description": "Configuration for document upload steps." }, "UploadFilesRequest": { "properties": { "file_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "minItems": 1, "title": "File Ids", "description": "File IDs from /files/upload" } }, "type": "object", "required": [ "file_ids" ], "title": "UploadFilesRequest", "description": "Request to link already-uploaded files to a task." }, "UploadFilesResponse": { "properties": { "task_id": { "type": "string", "format": "uuid", "title": "Task Id" }, "cycle_id": { "type": "string", "format": "uuid", "title": "Cycle Id" }, "attached_files": { "items": { "$ref": "#/components/schemas/UploadedFileInfo" }, "type": "array", "title": "Attached Files" }, "total_attached": { "type": "integer", "title": "Total Attached" } }, "type": "object", "required": [ "task_id", "cycle_id", "attached_files", "total_attached" ], "title": "UploadFilesResponse", "description": "Response after linking files to a task." }, "UploadedFileInfo": { "properties": { "file_id": { "type": "string", "format": "uuid", "title": "File Id" }, "filename": { "type": "string", "title": "Filename" }, "size_bytes": { "type": "integer", "title": "Size Bytes" }, "content_type": { "type": "string", "title": "Content Type" } }, "type": "object", "required": [ "file_id", "filename", "size_bytes", "content_type" ], "title": "UploadedFileInfo", "description": "Information about an uploaded file linked to a task." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "VerificationStepDefinition": { "properties": { "id": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9_-]+$", "title": "Id" }, "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name" }, "type": { "type": "string", "const": "verification", "title": "Type", "default": "verification" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "depends_on": { "items": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" } ] }, "type": "array", "title": "Depends On" }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stage" }, "timeout": { "anyOf": [ { "type": "string", "pattern": "^\\d+[smhd]$" }, { "type": "null" } ], "title": "Timeout" }, "retry_policy": { "anyOf": [ { "$ref": "#/components/schemas/RetryPolicy" }, { "type": "null" } ] }, "error_handler": { "anyOf": [ { "$ref": "#/components/schemas/StepErrorHandler" }, { "type": "null" } ] }, "emit_artifact": { "anyOf": [ { "$ref": "#/components/schemas/EmitArtifactSpec" }, { "type": "null" } ] }, "optional": { "type": "boolean", "title": "Optional", "default": false }, "continue_on_error": { "type": "boolean", "title": "Continue On Error", "default": false }, "halt_conditions": { "items": { "$ref": "#/components/schemas/HaltCondition" }, "type": "array", "title": "Halt Conditions" }, "parameters": { "items": { "$ref": "#/components/schemas/StepParameter" }, "type": "array", "title": "Parameters" }, "guards": { "items": { "$ref": "#/components/schemas/StepGuard" }, "type": "array", "title": "Guards" }, "impact_level": { "$ref": "#/components/schemas/ImpactLevel", "default": "medium" }, "run_mode": { "$ref": "#/components/schemas/RunMode", "default": "propose" }, "requires_approval": { "type": "boolean", "title": "Requires Approval", "default": false }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "examples": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StepExample" }, "type": "array" }, { "type": "null" } ], "title": "Examples", "description": "Attached example files for this step. Each entry pairs a platform.file_uploads.file_id with a role + tags + notes so the runtime can shape its instruction. Bounded at 20 to keep a reasonable upper limit on the prompt preamble." }, "applies_when": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applies When", "description": "CEL predicate evaluated at MATERIALIZATION (not at step execution): the step is marked skipped when it evaluates False. Stored verbatim \u2014 the expression is parsed by celpy at launch, so any coercion here would change its meaning." }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "Categorical labels on the step itself (e.g. 'pdf-read', 'coutts', 'fy25'). Free-form; recommended tag set is documented per workstream surface." }, "config": { "additionalProperties": true, "type": "object", "title": "Config", "description": "Verification config (checks list)" } }, "additionalProperties": true, "type": "object", "required": [ "id", "name" ], "title": "VerificationStepDefinition", "description": "Verification step - runs deterministic cross-checks, no LLM." }, "WaitForReplyStepDefinition": { "properties": { "id": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9_-]+$", "title": "Id" }, "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name" }, "type": { "type": "string", "const": "wait_for_reply", "title": "Type", "default": "wait_for_reply" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "depends_on": { "items": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" } ] }, "type": "array", "title": "Depends On" }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stage" }, "timeout": { "type": "string", "pattern": "^\\d+[smhd]$", "title": "Timeout", "description": "Max time to wait for a reply before timing out", "default": "7d" }, "retry_policy": { "anyOf": [ { "$ref": "#/components/schemas/RetryPolicy" }, { "type": "null" } ] }, "error_handler": { "anyOf": [ { "$ref": "#/components/schemas/StepErrorHandler" }, { "type": "null" } ] }, "emit_artifact": { "anyOf": [ { "$ref": "#/components/schemas/EmitArtifactSpec" }, { "type": "null" } ] }, "optional": { "type": "boolean", "title": "Optional", "default": false }, "continue_on_error": { "type": "boolean", "title": "Continue On Error", "default": false }, "halt_conditions": { "items": { "$ref": "#/components/schemas/HaltCondition" }, "type": "array", "title": "Halt Conditions" }, "parameters": { "items": { "$ref": "#/components/schemas/StepParameter" }, "type": "array", "title": "Parameters" }, "guards": { "items": { "$ref": "#/components/schemas/StepGuard" }, "type": "array", "title": "Guards" }, "impact_level": { "$ref": "#/components/schemas/ImpactLevel", "default": "medium" }, "run_mode": { "$ref": "#/components/schemas/RunMode", "default": "propose" }, "requires_approval": { "type": "boolean", "title": "Requires Approval", "default": false }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "examples": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StepExample" }, "type": "array" }, { "type": "null" } ], "title": "Examples", "description": "Attached example files for this step. Each entry pairs a platform.file_uploads.file_id with a role + tags + notes so the runtime can shape its instruction. Bounded at 20 to keep a reasonable upper limit on the prompt preamble." }, "applies_when": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applies When", "description": "CEL predicate evaluated at MATERIALIZATION (not at step execution): the step is marked skipped when it evaluates False. Stored verbatim \u2014 the expression is parsed by celpy at launch, so any coercion here would change its meaning." }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "Categorical labels on the step itself (e.g. 'pdf-read', 'coutts', 'fy25'). Free-form; recommended tag set is documented per workstream surface." }, "sent_message_id_from": { "type": "string", "title": "Sent Message Id From", "description": "Context path to the message_id of the sent email to watch for replies" }, "on_reply": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "On Reply", "description": "Step ID to jump to when reply is received (default: next step)" }, "on_timeout": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "On Timeout", "description": "Step ID to jump to on timeout (default: next step with timeout status)" } }, "additionalProperties": false, "type": "object", "required": [ "id", "name", "sent_message_id_from" ], "title": "WaitForReplyStepDefinition", "description": "Wait-for-reply step \u2014 pauses until an inbound email matches the thread.\n\nMonitors the Agentmail inbox for a reply to a previously sent email.\nThe workflow pauses (WAIT) and resumes when a matching reply is detected\nor the timeout expires." }, "WaitStepDefinition": { "properties": { "id": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9_-]+$", "title": "Id" }, "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name" }, "type": { "type": "string", "const": "wait", "title": "Type", "default": "wait" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "depends_on": { "items": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" } ] }, "type": "array", "title": "Depends On" }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stage" }, "timeout": { "anyOf": [ { "type": "string", "pattern": "^\\d+[smhd]$" }, { "type": "null" } ], "title": "Timeout" }, "retry_policy": { "anyOf": [ { "$ref": "#/components/schemas/RetryPolicy" }, { "type": "null" } ] }, "error_handler": { "anyOf": [ { "$ref": "#/components/schemas/StepErrorHandler" }, { "type": "null" } ] }, "emit_artifact": { "anyOf": [ { "$ref": "#/components/schemas/EmitArtifactSpec" }, { "type": "null" } ] }, "optional": { "type": "boolean", "title": "Optional", "default": false }, "continue_on_error": { "type": "boolean", "title": "Continue On Error", "default": false }, "halt_conditions": { "items": { "$ref": "#/components/schemas/HaltCondition" }, "type": "array", "title": "Halt Conditions" }, "parameters": { "items": { "$ref": "#/components/schemas/StepParameter" }, "type": "array", "title": "Parameters" }, "guards": { "items": { "$ref": "#/components/schemas/StepGuard" }, "type": "array", "title": "Guards" }, "impact_level": { "$ref": "#/components/schemas/ImpactLevel", "default": "medium" }, "run_mode": { "$ref": "#/components/schemas/RunMode", "default": "propose" }, "requires_approval": { "type": "boolean", "title": "Requires Approval", "default": false }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "examples": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StepExample" }, "type": "array" }, { "type": "null" } ], "title": "Examples", "description": "Attached example files for this step. Each entry pairs a platform.file_uploads.file_id with a role + tags + notes so the runtime can shape its instruction. Bounded at 20 to keep a reasonable upper limit on the prompt preamble." }, "applies_when": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applies When", "description": "CEL predicate evaluated at MATERIALIZATION (not at step execution): the step is marked skipped when it evaluates False. Stored verbatim \u2014 the expression is parsed by celpy at launch, so any coercion here would change its meaning." }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "Categorical labels on the step itself (e.g. 'pdf-read', 'coutts', 'fy25'). Free-form; recommended tag set is documented per workstream surface." }, "instruction": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instruction", "description": "Natural-language instruction, Jinja2-rendered before execution" }, "expected_outputs": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Expected Outputs", "description": "Declared output shape, used by the lint's output-reference checks" }, "wait_seconds": { "anyOf": [ { "type": "number", "minimum": 0.0 }, { "type": "null" } ], "title": "Wait Seconds", "description": "Seconds to pause. Mutually exclusive with wait_until_iso." }, "wait_until_iso": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Wait Until Iso", "description": "ISO-8601 instant to pause until. Mutually exclusive with wait_seconds." } }, "additionalProperties": false, "type": "object", "required": [ "id", "name" ], "title": "WaitStepDefinition", "description": "Wait step \u2014 pause the cycle for a duration or until a wall-clock time.\n\nDistinct from ``wait_for_reply`` (which blocks on an inbound email) and from\na schedule trigger (which is clock-driven at launch). The executor\nheartbeats every 10s so Temporal does not kill the activity mid-sleep, and\ncaps the sleep \u2014 a wait longer than the cap is refused at runtime, so it is\nworth keeping durations modest here." }, "WdlApprovalAction": { "properties": { "label": { "type": "string", "title": "Label" }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next", "description": "Next step after action" }, "require_reason": { "type": "boolean", "title": "Require Reason", "default": false }, "allow_edit": { "type": "boolean", "title": "Allow Edit", "default": false } }, "additionalProperties": false, "type": "object", "required": [ "label" ], "title": "WdlApprovalAction", "description": "Action configuration for approval step." }, "WebhookStepDefinition": { "properties": { "id": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9_-]+$", "title": "Id" }, "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name" }, "type": { "type": "string", "const": "webhook", "title": "Type", "default": "webhook" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "depends_on": { "items": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" } ] }, "type": "array", "title": "Depends On" }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stage" }, "timeout": { "anyOf": [ { "type": "string", "pattern": "^\\d+[smhd]$" }, { "type": "null" } ], "title": "Timeout" }, "retry_policy": { "anyOf": [ { "$ref": "#/components/schemas/RetryPolicy" }, { "type": "null" } ] }, "error_handler": { "anyOf": [ { "$ref": "#/components/schemas/StepErrorHandler" }, { "type": "null" } ] }, "emit_artifact": { "anyOf": [ { "$ref": "#/components/schemas/EmitArtifactSpec" }, { "type": "null" } ] }, "optional": { "type": "boolean", "title": "Optional", "default": false }, "continue_on_error": { "type": "boolean", "title": "Continue On Error", "default": false }, "halt_conditions": { "items": { "$ref": "#/components/schemas/HaltCondition" }, "type": "array", "title": "Halt Conditions" }, "parameters": { "items": { "$ref": "#/components/schemas/StepParameter" }, "type": "array", "title": "Parameters" }, "guards": { "items": { "$ref": "#/components/schemas/StepGuard" }, "type": "array", "title": "Guards" }, "impact_level": { "$ref": "#/components/schemas/ImpactLevel", "default": "medium" }, "run_mode": { "$ref": "#/components/schemas/RunMode", "default": "propose" }, "requires_approval": { "type": "boolean", "title": "Requires Approval", "default": false }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "examples": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StepExample" }, "type": "array" }, { "type": "null" } ], "title": "Examples", "description": "Attached example files for this step. Each entry pairs a platform.file_uploads.file_id with a role + tags + notes so the runtime can shape its instruction. Bounded at 20 to keep a reasonable upper limit on the prompt preamble." }, "applies_when": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applies When", "description": "CEL predicate evaluated at MATERIALIZATION (not at step execution): the step is marked skipped when it evaluates False. Stored verbatim \u2014 the expression is parsed by celpy at launch, so any coercion here would change its meaning." }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "Categorical labels on the step itself (e.g. 'pdf-read', 'coutts', 'fy25'). Free-form; recommended tag set is documented per workstream surface." }, "instruction": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instruction", "description": "Natural-language instruction, Jinja2-rendered before execution" }, "expected_outputs": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Expected Outputs", "description": "Declared output shape, used by the lint's output-reference checks" }, "webhook_url": { "type": "string", "minLength": 1, "title": "Webhook Url", "description": "Target URL (Jinja2-templated, allowlisted at runtime)" }, "webhook_method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ], "title": "Webhook Method", "description": "HTTP method. The executor refuses anything outside this set.", "default": "POST" }, "webhook_headers": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Webhook Headers", "description": "Request headers (values Jinja2-templated)" }, "webhook_body": { "anyOf": [ {}, { "type": "null" } ], "title": "Webhook Body", "description": "Request body, rendered against runtime_vars + prior step outputs" }, "webhook_expect_status": { "items": { "type": "integer" }, "type": "array", "title": "Webhook Expect Status", "description": "Accepted status codes. Empty means any 2xx." } }, "additionalProperties": false, "type": "object", "required": [ "id", "name", "webhook_url" ], "title": "WebhookStepDefinition", "description": "Webhook step \u2014 an outbound HTTP call to an allowlisted target.\n\nDistinct from a ``notify`` step with channel=\"webhook\": this is a\ngeneral-purpose request whose response is exposed to downstream steps.\n\nThe target is checked against a DENY-BY-DEFAULT allowlist at runtime, so a\nsaved step naming an unlisted host will fail when it runs. That check stays\nat runtime deliberately \u2014 the allowlist is deployment config, not something\nan authoring-time model can know." }, "Workplan": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Workplan UUID" }, "workplan_type": { "type": "string", "title": "Workplan Type", "description": "Backing store type: 'blueprint' (legacy single-client, has template_id/client_id) or 'job_definition' (Model A multi-client, has target_selector; client_id is null).", "default": "blueprint" }, "permakey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Permakey", "description": "Stable short key for URL construction" }, "ws_permakey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ws Permakey", "description": "Parent WorkStream permakey for /workstreams//workplan/ URL. Populated via the most-recent cycle's parent workstream for both blueprint and job_definition rows; null only when no cycle has run yet." }, "template_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Template Id", "description": "Source template UUID (workstream_id in DB); null for job_definition-backed workplans" }, "target_selector": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Target Selector", "description": "Multi-client target binding for job_definition workplans (e.g. {type: 'explicit', client_ids: [...]}). Null for blueprint workplans." }, "name": { "type": "string", "title": "Name", "description": "Workplan name" }, "client_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Client Id", "description": "Client UUID (optional)" }, "client_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Name", "description": "Client name" }, "run_mode": { "$ref": "#/components/schemas/WorkplanRunMode", "description": "Effective run posture (S2-READ \u00a71a; derived from configuration)" }, "cohort": { "$ref": "#/components/schemas/WorkplanCohort", "description": "Bound client-set size + shape (S2-READ \u00a71b; derived from configuration)" }, "config_overrides": { "additionalProperties": true, "type": "object", "title": "Config Overrides", "description": "Configuration (from DB)" }, "effective_config": { "additionalProperties": true, "type": "object", "title": "Effective Config", "description": "Merged effective config" }, "schedule": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Schedule", "description": "Cron schedule expression (from configuration; null = unscheduled)" }, "schedule_timezone": { "type": "string", "title": "Schedule Timezone", "description": "IANA timezone for the schedule (from configuration; defaults UTC)", "default": "UTC" }, "max_duration_minutes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Duration Minutes", "description": "Per-instance duration guardrail in minutes (from configuration; null = unset)" }, "human_checkpoints": { "items": {}, "type": "array", "title": "Human Checkpoints", "description": "Sign-off gate checkpoints (from configuration). Non-empty means a partner sign-off gate is on." }, "input_bindings": { "anyOf": [ { "items": { "$ref": "#/components/schemas/InputBindingDef" }, "type": "array" }, { "type": "null" } ], "title": "Input Bindings", "description": "Cross-WorkPlan input bindings parsed from config." }, "schedule_overrides": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Schedule Overrides", "description": "Per-client schedule override map (from job_definition DB; clientId -> {cron_expr, timezone, skip_weekends, holiday_calendar}). Null for blueprint-backed plans." }, "per_client_overrides": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Per Client Overrides", "description": "Per-client input and context overrides map. Null for blueprint-backed plans." }, "status": { "$ref": "#/components/schemas/WorkstreamStatus", "description": "Workplan status" }, "last_run_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Run At", "description": "Most recent cycle start for this WorkPlan (null if never run)" }, "next_run_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Next Run At", "description": "Next scheduled execution \u2014 computed; see GET /workplans/{id}/next-run (P1)" }, "created_by": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Created By", "description": "Creator user ID (owner_id in DB)" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Last update timestamp" } }, "type": "object", "required": [ "id", "name", "status", "created_at", "updated_at" ], "title": "Workplan", "description": "Workplan response model.\n\nOpenAPI title is ``Workplan``; the Python class name stays\n``BlueprintResponse``.\n\n``workplan_type`` discriminates the two backing stores:\n- ``\"blueprint\"`` \u2014 legacy single-client plan (workstreams.blueprint)\n- ``\"job_definition\"`` \u2014 Model A multi-client plan (workstreams.job_definition)" }, "WorkplanCohort": { "properties": { "total_clients": { "type": "integer", "minimum": 0.0, "title": "Total Clients", "description": "Resolved size of the bound client set", "default": 0 }, "selector_kind": { "anyOf": [ { "type": "string", "enum": [ "single", "client_list", "tag", "all_active" ] }, { "type": "null" } ], "title": "Selector Kind", "description": "The dominant selector shape (null when the cohort is empty)" } }, "type": "object", "title": "WorkplanCohort", "description": "Structural facts about the WorkPlan's bound client set (S2-READ \u00a71b).\n\nLive exception/ready counts live on the roster's ``summary`` (one\nauthoritative source); this object carries only the cohort's size + shape.\nWith no multi-client cohort writer yet, ``total_clients`` resolves to 0/1\nand ``selector_kind`` to ``single`` \u2014 the shape is frozen, the populating\ndata is S2-write BE work behind it." }, "WorkplanCreate": { "properties": { "template_id": { "type": "string", "format": "uuid", "title": "Template Id", "description": "Source template UUID (workstream_id)" }, "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name", "description": "Workplan name" }, "client_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Client Id", "description": "Client UUID (optional; references platform.clients)" }, "client_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array", "minItems": 1 }, { "type": "null" } ], "title": "Client Ids", "description": "Client UUIDs for a multi-client roster \u2014 maps to target_selector.type='client_list'. Mutually exclusive with client_id." }, "config_overrides": { "additionalProperties": true, "type": "object", "title": "Config Overrides", "description": "Configuration overrides" }, "schedule": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Schedule", "description": "Cron schedule expression (folded into configuration; null = unscheduled)" }, "schedule_timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Schedule Timezone", "description": "IANA timezone for the schedule (folded into configuration)" }, "skip_weekends": { "type": "boolean", "title": "Skip Weekends", "description": "Shift a fire time landing on Sat/Sun to the next business day", "default": false }, "holiday_calendar": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Holiday Calendar", "description": "Shift a fire time landing on a holiday to the next business day: 'UK', 'US', or 'AU'" }, "max_duration_minutes": { "anyOf": [ { "type": "integer", "minimum": 1.0 }, { "type": "null" } ], "title": "Max Duration Minutes", "description": "Per-instance duration guardrail in minutes (folded into configuration)" }, "human_checkpoints": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Human Checkpoints", "description": "Sign-off gate checkpoints (folded into configuration); [] clears the gate" }, "run_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Run Mode", "description": "Run posture: propose|auto_run (folded into configuration)" }, "not_ready_policy": { "type": "string", "title": "Not Ready Policy", "description": "Fan-out ready-gating policy for a client whose inputs are not ready at a scheduled fire: 'hold_and_wait' (skip that client, retry next cycle), 'run_and_flag' (fire anyway, flag the cycle \u2014 legacy default), or 'skip_cycle' (write a terminal skipped-cycle tombstone).", "default": "run_and_flag" }, "schedule_overrides": { "additionalProperties": true, "type": "object", "title": "Schedule Overrides", "description": "Per-client schedule override map (clientId -> {cron_expr, timezone, skip_weekends, holiday_calendar}). An entry REPLACES the plan-level schedule for that client at fan-out; absent clients use the plan schedule." } }, "type": "object", "required": [ "template_id", "name" ], "title": "WorkplanCreate", "description": "Request to create a workplan from a template.\n\nOpenAPI title is ``WorkplanCreate`` (the public noun); the Python class\nname stays ``BlueprintCreate`` so internal imports and the DB layer are\nuntouched.", "example": { "client_id": "660e8400-e29b-41d4-a716-446655440001", "config_overrides": { "currency": "USD", "threshold": 1000 }, "name": "Acme Corp Monthly Close", "schedule": "0 9 1 * *", "template_id": "550e8400-e29b-41d4-a716-446655440000" } }, "WorkplanDomain": { "properties": { "domain_key": { "type": "string", "title": "Domain Key", "description": "Canonical domain key \u2014 pass straight into POST /workstreams/jobs {domain}. Round-trips through PERSONA_REGISTRY.for_workstream() to this DomainAgent's goal_template (e.g. 'ita_2007_eis', 'vat_return')." }, "label": { "type": "string", "title": "Label", "description": "Human-readable agent name for the picker." }, "description": { "type": "string", "title": "Description", "description": "What this DomainAgent produces." }, "goal_template": { "type": "string", "title": "Goal Template", "description": "The agent's goal template (the create flow's default goal)." } }, "type": "object", "required": [ "domain_key", "label", "description", "goal_template" ], "title": "WorkplanDomain", "description": "One WorkPlan-able DomainAgent, for the domain-centric create picker." }, "WorkplanDomainsResponse": { "properties": { "domains": { "items": { "$ref": "#/components/schemas/WorkplanDomain" }, "type": "array", "title": "Domains" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "domains", "total" ], "title": "WorkplanDomainsResponse", "description": "The WorkPlan-able domain catalog (named DomainAgents only)." }, "WorkplanListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/Workplan" }, "type": "array", "title": "Items" }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object", "required": [ "pagination" ], "title": "WorkplanListResponse", "description": "Paginated list of workplans.\n\nOpenAPI title is ``WorkplanListResponse``; the Python class name stays\n``BlueprintListResponse``." }, "WorkplanRoster": { "properties": { "workplan_id": { "type": "string", "title": "Workplan Id" }, "workstream_id": { "type": "string", "title": "Workstream Id" }, "run_mode": { "$ref": "#/components/schemas/RunMode", "default": "propose" }, "summary": { "$ref": "#/components/schemas/RosterSummary" }, "clients": { "items": { "$ref": "#/components/schemas/RosterClient" }, "type": "array", "title": "Clients" }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object", "required": [ "workplan_id", "workstream_id", "summary", "clients", "pagination" ], "title": "WorkplanRoster", "description": "GET /workplans/{id}/roster \u2014 the all-clients cohort card." }, "WorkplanRunMode": { "properties": { "effective": { "$ref": "#/components/schemas/RunMode", "description": "propose | auto_run \u2014 the resolved run posture", "default": "propose" }, "source": { "type": "string", "enum": [ "plan", "workstream_default" ], "title": "Source", "description": "Where `effective` came from", "default": "workstream_default" }, "locked": { "type": "boolean", "title": "Locked", "description": "Governance read-only flag (always false in S2)", "default": false } }, "type": "object", "title": "WorkplanRunMode", "description": "The WorkPlan's effective run posture (S2-READ \u00a71a).\n\n``effective`` resolves: plan-level ``configuration.run_mode`` \u2192 the\nworkstream default \u2192 ``propose``. ``source`` tells the FE whether the value\nwas set on this plan or inherited. ``locked`` is the firm-lock governance\nflag \u2014 always ``False`` in S2." }, "WorkplanUpdate": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 200, "minLength": 1 }, { "type": "null" } ], "title": "Name", "description": "Workplan name" }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Description", "description": "Workplan description" }, "client_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Client Id", "description": "Client UUID (references platform.clients). Omit to leave unchanged; send an explicit null to clear the assignment (the handler distinguishes the two via fields-set)." }, "config_overrides": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Config Overrides", "description": "Configuration overrides \u2014 shallow-merged into the stored configuration (existing keys survive unless explicitly overridden)." }, "schedule": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Schedule", "description": "Cron schedule expression (folded into configuration; null = unscheduled)" }, "schedule_timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Schedule Timezone", "description": "IANA timezone for the schedule (folded into configuration)" }, "skip_weekends": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Skip Weekends", "description": "Shift a fire time landing on Sat/Sun to the next business day" }, "holiday_calendar": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Holiday Calendar", "description": "Shift a fire time landing on a holiday to the next business day: 'UK', 'US', or 'AU'" }, "max_duration_minutes": { "anyOf": [ { "type": "integer", "maximum": 1440.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Max Duration Minutes", "description": "Per-instance duration guardrail in minutes (folded into configuration). Positive and \u2264 1440 (24h)." }, "human_checkpoints": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Human Checkpoints", "description": "Sign-off gate checkpoints (folded into configuration); [] clears the gate" }, "run_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Run Mode", "description": "Run posture / autonomy: propose|auto_run (folded into configuration)" }, "default_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Default Context", "description": "Run-context bag. Its ``autonomy`` key is an alias for ``run_mode`` (propose|auto_run) \u2014 supplied here it is folded into the effective run posture when ``run_mode`` is not given explicitly." }, "status": { "anyOf": [ { "$ref": "#/components/schemas/WorkstreamStatus" }, { "type": "null" } ], "description": "Workplan status" }, "schedule_overrides": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Schedule Overrides", "description": "Per-client schedule override map (client UUID -> cron expression). Keys must be valid UUIDs." } }, "type": "object", "title": "WorkplanUpdate", "description": "Request to update a workplan.\n\nOpenAPI title is ``WorkplanUpdate``; the Python class name stays\n``BlueprintUpdate``." }, "Workstream": { "type": "object", "description": "A reusable workstream template. Bind to a client via a Workplan to make it runnable. NEVER call this a 'playbook' \u2014 that schema was retired in Phase 7.", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published", "archived" ] }, "execution_mode": { "type": "string", "enum": [ "inline", "containerized" ], "description": "Inline = Temporal-native declarative; containerized = agentic Fly.io. See docs/connect/tool-surface-matrix.md." }, "steps": { "type": "array", "items": { "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WorkstreamDraftCommit": { "properties": { "scope": { "$ref": "#/components/schemas/WorkstreamScope", "default": "user" }, "scope_owner_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Scope Owner Id", "description": "Required for team/firm scope" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Override name from draft_definition" }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Slug" } }, "type": "object", "title": "WorkstreamDraftCommit", "description": "Commit a draft into a real Playbook." }, "WorkstreamDraftCreate": { "properties": { "topic_id": { "type": "string", "title": "Topic Id", "description": "Topic the draft is being authored in \u2014 permakey (preferred) or UUID" }, "initial_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Initial Message", "description": "First user message describing the playbook (passed to playbook_generation_service to seed draft_definition)" }, "draft_definition": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Draft Definition", "description": "Optional pre-seeded PlaybookV1 JSON" } }, "type": "object", "required": [ "topic_id" ], "title": "WorkstreamDraftCreate", "description": "Start a new conversational draft anchored to a Topic." }, "WorkstreamDraftListResponse": { "properties": { "drafts": { "items": { "$ref": "#/components/schemas/WorkstreamDraftResponse" }, "type": "array", "title": "Drafts" }, "total": { "type": "integer", "title": "Total", "default": 0 } }, "type": "object", "title": "WorkstreamDraftListResponse" }, "WorkstreamDraftResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "workspace_id": { "type": "string", "title": "Workspace Id" }, "topic_id": { "type": "string", "title": "Topic Id" }, "author_user_id": { "type": "string", "title": "Author User Id" }, "status": { "$ref": "#/components/schemas/WorkstreamDraftStatus" }, "draft_definition": { "additionalProperties": true, "type": "object", "title": "Draft Definition" }, "conversation": { "items": { "$ref": "#/components/schemas/DraftConversationMessage" }, "type": "array", "title": "Conversation" }, "validation_errors": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Validation Errors" }, "committed_to_playbook_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Committed To Playbook Id" }, "committed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Committed At" }, "abandoned_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Abandoned At" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" } }, "type": "object", "required": [ "id", "workspace_id", "topic_id", "author_user_id", "status", "created_at", "updated_at" ], "title": "WorkstreamDraftResponse" }, "WorkstreamDraftStatus": { "type": "string", "enum": [ "drafting", "committed", "abandoned" ], "title": "WorkstreamDraftStatus" }, "WorkstreamDraftUpdate": { "properties": { "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message", "description": "Append a user message and regenerate the draft" }, "draft_definition": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Draft Definition" }, "validation_errors": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Validation Errors" } }, "type": "object", "title": "WorkstreamDraftUpdate", "description": "Iterate on a draft. Either append a conversation turn (which the\ngeneration service will use to regenerate ``draft_definition``) and/or\noverwrite ``draft_definition`` directly." }, "WorkstreamExportPayload": { "properties": { "schema_version": { "type": "string", "title": "Schema Version", "description": "Export format version. Bumped if the shape evolves.", "default": "1" }, "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name" }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Description" }, "source_description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Source Description" }, "source_name": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Source Name" }, "category": { "anyOf": [ { "type": "string", "enum": [ "compliance", "advisory", "audit", "bookkeeping", "tax", "internal" ] }, { "type": "null" } ], "title": "Category" }, "steps": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Steps" }, "default_config": { "additionalProperties": true, "type": "object", "title": "Default Config" }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags" }, "input_schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Input Schema" }, "output_schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Output Schema" }, "execution_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Execution Mode" }, "jurisdictions": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Jurisdictions" }, "goal_spec": { "anyOf": [ { "$ref": "#/components/schemas/GoalSpecPayload" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Goal Spec" }, "accounting_ledger": { "type": "string", "enum": [ "off", "optional", "required" ], "title": "Accounting Ledger", "description": "Portable opt-in Accounting Ledger capability.", "default": "off" }, "source": { "additionalProperties": true, "type": "object", "title": "Source", "description": "Provenance: where this export came from. Includes {workspace_id, workstream_id, version, exported_at, exported_by}. The import endpoint stores this in forked_from so the receiving workspace can trace lineage." } }, "type": "object", "required": [ "name" ], "title": "WorkstreamExportPayload", "description": "The portable definition of a workstream \u2014 everything needed to\nreconstruct it in another workspace or environment.\n\nProduced by ``GET /templates/{id}/export`` and consumed by\n``POST /templates/import``. The shape is a superset of\n``TemplateCreate`` with provenance metadata so the receiving workspace\nknows where the definition came from." }, "WorkstreamExportPayload-Output": { "properties": { "schema_version": { "type": "string", "title": "Schema Version", "description": "Export format version. Bumped if the shape evolves.", "default": "1" }, "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name" }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Description" }, "source_description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Source Description" }, "source_name": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Source Name" }, "category": { "anyOf": [ { "type": "string", "enum": [ "compliance", "advisory", "audit", "bookkeeping", "tax", "internal" ] }, { "type": "null" } ], "title": "Category" }, "steps": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Steps" }, "default_config": { "additionalProperties": true, "type": "object", "title": "Default Config" }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags" }, "input_schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Input Schema" }, "output_schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Output Schema" }, "execution_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Execution Mode" }, "jurisdictions": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Jurisdictions" }, "goal_spec": { "anyOf": [ { "$ref": "#/components/schemas/GoalSpecPayload-Output" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Goal Spec" }, "accounting_ledger": { "type": "string", "enum": [ "off", "optional", "required" ], "title": "Accounting Ledger", "description": "Portable opt-in Accounting Ledger capability.", "default": "off" }, "source": { "additionalProperties": true, "type": "object", "title": "Source", "description": "Provenance: where this export came from. Includes {workspace_id, workstream_id, version, exported_at, exported_by}. The import endpoint stores this in forked_from so the receiving workspace can trace lineage." } }, "type": "object", "required": [ "name" ], "title": "WorkstreamExportPayload", "description": "The portable definition of a workstream \u2014 everything needed to\nreconstruct it in another workspace or environment.\n\nProduced by ``GET /templates/{id}/export`` and consumed by\n``POST /templates/import``. The shape is a superset of\n``TemplateCreate`` with provenance metadata so the receiving workspace\nknows where the definition came from." }, "WorkstreamForkResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "New fork's UUID" }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Slug", "description": "New fork's slug (auto-generated)" }, "name": { "type": "string", "title": "Name", "description": "Fork name (copied from source)" }, "scope": { "type": "string", "title": "Scope", "description": "Fork scope (private 'user' by default)" }, "status": { "type": "string", "title": "Status", "description": "Fork status ('draft')" }, "version": { "type": "integer", "title": "Version", "description": "Fork version (copied from source at fork time)" }, "parent_workstream_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Parent Workstream Id", "description": "Source recipe this was forked from (drives forked_from)" } }, "type": "object", "required": [ "id", "name", "scope", "status", "version" ], "title": "WorkstreamForkResponse", "description": "The new private copy produced by forking a recipe (the prototype's Fork\naffordance). Carries the keys the FE needs to navigate to the fork." }, "WorkstreamImportRequest": { "properties": { "definition": { "$ref": "#/components/schemas/WorkstreamExportPayload", "description": "The exported workstream definition to import." }, "name_override": { "anyOf": [ { "type": "string", "maxLength": 200, "minLength": 1 }, { "type": "null" } ], "title": "Name Override", "description": "Override the workstream name in the receiving workspace." }, "description_override": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Description Override", "description": "Override the description." }, "status": { "$ref": "#/components/schemas/WorkstreamStatus", "description": "Status for the imported workstream (default: draft).", "default": "draft" } }, "type": "object", "required": [ "definition" ], "title": "WorkstreamImportRequest", "description": "Request body for ``POST /templates/import``.\n\nAccepts a ``WorkstreamExportPayload`` (the definition + provenance) and\noptional overrides for the receiving workspace." }, "WorkstreamScope": { "type": "string", "enum": [ "plan", "user", "team", "firm", "gallery", "gallery_community", "gallery_verified" ], "title": "WorkstreamScope" }, "WorkstreamStatus": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ], "title": "WorkstreamStatus", "description": "Status for workstream entities." }, "WorkstreamTriggerCreate": { "properties": { "trigger_type": { "type": "string", "title": "Trigger Type" }, "config": { "additionalProperties": true, "type": "object", "title": "Config", "default": {} }, "client_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Client Id" } }, "type": "object", "required": [ "trigger_type" ], "title": "WorkstreamTriggerCreate" }, "WriteModeTransitionResponse": { "properties": { "blueprint_id": { "type": "string", "format": "uuid", "title": "Blueprint Id", "description": "Blueprint UUID" }, "previous_state": { "type": "boolean", "title": "Previous State", "description": "Write mode before transition" }, "new_state": { "type": "boolean", "title": "New State", "description": "Write mode after transition" }, "transitioned_by": { "type": "string", "title": "Transitioned By", "description": "User ID who performed the transition" }, "transitioned_at": { "type": "string", "format": "date-time", "title": "Transitioned At", "description": "Timestamp of the transition" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason", "description": "Reason provided for the transition" }, "cycle_count_affected": { "type": "integer", "minimum": 0.0, "title": "Cycle Count Affected", "description": "Number of cycles affected by this change", "default": 0 }, "message": { "type": "string", "title": "Message", "description": "Human-readable status message" } }, "type": "object", "required": [ "blueprint_id", "previous_state", "new_state", "transitioned_by", "transitioned_at", "message" ], "title": "WriteModeTransitionResponse", "description": "Response schema for write mode enable/disable operations.\n\nProvides confirmation of the mode transition with audit details." }, "WriteStatusResponse": { "properties": { "blueprint_id": { "type": "string", "format": "uuid", "title": "Blueprint Id", "description": "Blueprint UUID" }, "write_enabled": { "type": "boolean", "title": "Write Enabled", "description": "Whether write operations are currently enabled" }, "write_enabled_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Write Enabled At", "description": "When writes were last enabled (None if never enabled)" }, "write_enabled_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Write Enabled By", "description": "User ID who enabled writes (None if never enabled)" }, "write_enabled_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Write Enabled Reason", "description": "Reason provided when writes were enabled" }, "cycle_count_affected": { "type": "integer", "minimum": 0.0, "title": "Cycle Count Affected", "description": "Number of active/running cycles affected by current mode", "default": 0 }, "last_write_operation_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Write Operation At", "description": "Timestamp of the last write operation performed" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links", "description": "HATEOAS links for related actions" } }, "type": "object", "required": [ "blueprint_id", "write_enabled" ], "title": "WriteStatusResponse", "description": "Response schema for write mode status.\n\nProvides current write mode state and audit information." } } } }