{ "openapi": "3.1.0", "info": { "title": "YieldFabric Agents Service API", "version": "0.14.0", "summary": "REST API for working groups, workflows, threads, agents, pipelines, knowledge graphs, and notebook/CRM/conversation operations. GraphQL deal-flow is exposed but documented via the federated payments spec.", "description": "Canonical specification for the YieldFabric **agents service** — the\nmulti-agent AI framework that hosts working-group collaboration,\nworkflow orchestration, agent runtime, knowledge-graph operations,\nnotebook/CRM, and conversation analysis.\n\n## Two surfaces\n\nThe agents service exposes two HTTP surfaces:\n\n| Surface | Path | Auth | Documented in |\n|---------|------|------|---------------|\n| **REST API** | `/working-groups/*`, `/agents/*`, `/pipelines/*`, `/kgs/*`, `/api/notebook/*`, `/api/crm/*`, `/api/conversation/*`, etc. | Bearer JWT | This spec |\n| **GraphQL** (`dealFlow`) | `/graphql` | Bearer JWT | [yieldfabric-payments/docs/api/](../../../yieldfabric-payments/docs/api/) — via the federated gateway at api.yieldfabric.com |\n\nFor deal operations (`proposeDeal`, `signDeal`, `activateDeal`, etc.) clients should hit the federated gateway. The agents service is the underlying subgraph owner; the documentation lives in the payments spec to keep the federated client-facing story unified.\n\n## How to read this spec\n\nThis is an OpenAPI 3.1 spec. The REST surface is documented under standard\n`paths/` entries, grouped by domain tag (Working Groups, Workflows, Threads,\nAgents, Pipelines, Knowledge Graphs, Notebook, CRM, Conversation,\nPresence). Per-operation files under `operations/**/*.yaml` carry the full\ndescription, examples, MCP metadata, and code samples — see `README.md` for\nthe convention.\n\nTwo SSE streaming endpoints (`GET /working-groups/{id}/chat/stream`,\n`GET /working-groups/{id}/workflows/{wid}/stream`) are documented with\n`text/event-stream` responses and an `x-event-types` extension enumerating\nthe event variants.\n", "contact": { "name": "YieldFabric Team", "email": "support@yieldfabric.com" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://api.yieldfabric.com", "description": "Production. REST is routed by the upstream reverse proxy; GraphQL goes through the federated gateway." } ], "tags": [ { "name": "Health", "description": "Liveness / readiness." }, { "name": "Working Groups", "description": "Multi-human multi-agent collaboration scopes. Owns workflows, threads, KGs, documents, members, federation policies.", "externalDocs": { "url": "guides/working-groups.md", "description": "Working groups guide" } }, { "name": "Members", "description": "Group membership and roles." }, { "name": "Group Documents", "description": "Documents attached to a working group (used as RAG sources)." }, { "name": "Audit", "description": "Audit-event timeline for a working group." }, { "name": "Federation", "description": "Cross-group RAG access grants." }, { "name": "Feedback", "description": "User feedback on agent outputs." }, { "name": "Workflows", "description": "YAML-defined multi-step workflows; create, start, stream, complete, approve, reject, reassign steps.", "externalDocs": { "url": "guides/workflows.md", "description": "Workflows guide" } }, { "name": "Workflow Templates", "description": "Reusable workflow definitions." }, { "name": "Deal Templates", "description": "Tenant-authored, versioned control-panel and conditions-precedent standards for classified deal types." }, { "name": "Threads", "description": "Conversation threads within a working group; messages, typing, weaver sub-threads.", "externalDocs": { "url": "guides/threads.md", "description": "Threads & chat guide" } }, { "name": "Chat", "description": "Per-group chat session + SSE stream." }, { "name": "Intents", "description": "Agent-proposed actions awaiting user confirmation.", "externalDocs": { "url": "guides/intents-and-drafts.md", "description": "Intents and drafts" } }, { "name": "Pipeline Drafts", "description": "Scratch workflows being authored before submission." }, { "name": "Agents", "description": "Agent definitions, versions, memory, studio (conversational authoring).", "externalDocs": { "url": "guides/agents-studio.md", "description": "Agents and Studio" } }, { "name": "Pipelines", "description": "Unified transform framework — run, resume, rewind, compose, reason-over.", "externalDocs": { "url": "guides/pipelines-and-kgs.md", "description": "Pipelines and KGs" } }, { "name": "Knowledge Graphs", "description": "KG CRUD, chunks, lexicons, frames." }, { "name": "Knowledge Documents", "description": "Document ingestion for KGs, plus frozen membership sets — immutable, hash-pinned document snapshots that make an absence or coverage claim checkable later." }, { "name": "LLM Credentials", "description": "Bring-your-own OpenAI / Azure OpenAI / Anthropic keys, scoped to a user or a room. Secrets are write-only — no endpoint returns one." }, { "name": "Notebook", "description": "Notebook surface for observations, entities, relationships." }, { "name": "CRM", "description": "Contact/account/entity surface." }, { "name": "Conversation", "description": "Conversation analysis (LLM-driven extraction)." }, { "name": "Presence", "description": "Presence join/heartbeat/disconnect for live collaboration." }, { "name": "Tools & Skills", "description": "Tool and skill catalogs." }, { "name": "Domain", "description": "Domain extraction utilities." }, { "name": "Economies & Usage", "description": "Economy manifest catalog and usage metering." }, { "name": "OpenAI Compatibility", "description": "OpenAI-wire-compatible LLM surface (/v1/*) — point any OpenAI SDK at the service." } ], "paths": { "/.well-known/oauth-authorization-server": { "get": { "operationId": "oauthAuthorizationServerShim_Misc", "x-method": "GET", "x-path": "/.well-known/oauth-authorization-server", "x-handler": "yieldfabric_mcp_transport::http::oauth_authorization_server::", "tags": [ "MCP" ], "summary": "Authorization-server metadata shim (RFC 8414) for older MCP clients", "description": "Compatibility shim for pre-RFC-9728 MCP clients (2025-03-26 spec\ndiscovery) that probe the RESOURCE server's origin for\nauthorization-server metadata instead of following the\nprotected-resource pointer. Emits the same RFC 8414 document the auth\nservice serves at its own `/.well-known/oauth-authorization-server` —\nthe metadata is fully derived from the configured auth base URL, so\nnothing is proxied. **Anonymous by design.**\n", "security": [], "responses": { "200": { "description": "Authorization-server metadata (mirror of the auth service's document)", "content": { "application/json": { "schema": { "type": "object", "required": [ "issuer", "authorization_endpoint", "token_endpoint" ], "properties": { "issuer": { "type": "string" }, "authorization_endpoint": { "type": "string" }, "token_endpoint": { "type": "string" }, "registration_endpoint": { "type": "string" }, "response_types_supported": { "type": "array", "items": { "type": "string" } }, "grant_types_supported": { "type": "array", "items": { "type": "string" } }, "code_challenge_methods_supported": { "type": "array", "items": { "type": "string" } }, "token_endpoint_auth_methods_supported": { "type": "array", "items": { "type": "string" } }, "scopes_supported": { "type": "array", "items": { "type": "string" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_oauthAuthorizationServerShim_Misc", "resource_uri": "yf://agents/mcp", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl https://agents.yieldfabric.com/.well-known/oauth-authorization-server" } ], "x-related": [ "/.well-known/oauth-protected-resource", "/mcp" ] } }, "/.well-known/oauth-authorization-server/mcp": { "get": { "operationId": "oauthAuthorizationServerShimMcp_Misc", "x-method": "GET", "x-path": "/.well-known/oauth-authorization-server/mcp", "x-handler": "yieldfabric_mcp_transport::http::oauth_authorization_server::", "tags": [ "MCP" ], "summary": "OAuth authorization-server metadata at the MCP resource suffix", "description": "Compatibility discovery alias for MCP clients that probe the resource\nserver's origin at an MCP-suffixed well-known path. The document is derived\nfrom the configured auth-service base and is identical to the origin-level\ncompatibility shim. It is not a proxy and is anonymous by design.\n", "security": [], "responses": { "200": { "description": "Authorization-server metadata derived from the auth base URL.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "issuer", "authorization_endpoint", "token_endpoint", "registration_endpoint", "response_types_supported", "grant_types_supported", "code_challenge_methods_supported", "token_endpoint_auth_methods_supported", "scopes_supported" ], "properties": { "issuer": { "type": "string" }, "authorization_endpoint": { "type": "string" }, "token_endpoint": { "type": "string" }, "registration_endpoint": { "type": "string" }, "response_types_supported": { "type": "array", "items": { "type": "string" } }, "grant_types_supported": { "type": "array", "items": { "type": "string" } }, "code_challenge_methods_supported": { "type": "array", "items": { "type": "string" } }, "token_endpoint_auth_methods_supported": { "type": "array", "items": { "type": "string" } }, "scopes_supported": { "type": "array", "items": { "type": "string" } } } }, "example": { "issuer": "https://auth.yieldfabric.com", "authorization_endpoint": "https://auth.yieldfabric.com/oauth/authorize", "token_endpoint": "https://auth.yieldfabric.com/oauth/token", "registration_endpoint": "https://auth.yieldfabric.com/oauth/register", "response_types_supported": [ "code" ], "grant_types_supported": [ "authorization_code", "refresh_token" ], "code_challenge_methods_supported": [ "S256" ], "token_endpoint_auth_methods_supported": [ "none" ], "scopes_supported": [ "mcp" ] } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_oauthAuthorizationServerShimMcp_Misc", "resource_uri": "yf://agents/mcp", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl https://agents.yieldfabric.com/.well-known/oauth-authorization-server/mcp" } ], "x-related": [ { "operationId": "oauthAuthorizationServerShim_Misc", "relation": "alias" }, { "operationId": "oauthProtectedResourceMcp_Misc", "relation": "protected-resource" }, { "operationId": "handleMcpHttp_Misc", "relation": "discovery-for" } ] } }, "/.well-known/oauth-protected-resource": { "get": { "operationId": "oauthProtectedResource_Misc", "x-method": "GET", "x-path": "/.well-known/oauth-protected-resource", "x-handler": "yieldfabric_mcp_transport::http::oauth_protected_resource::", "tags": [ "MCP" ], "summary": "OAuth protected-resource metadata for /mcp (RFC 9728)", "description": "Discovery document telling OAuth-capable MCP clients (claude.ai\ncustom connectors, Claude Code/Desktop) which authorization server\nguards the `/mcp` resource. Referenced from the `WWW-Authenticate`\nchallenge that an anonymous `POST /mcp` returns.\n\n**Anonymous by design** — this endpoint is the entry point of the\nlogin flow, so it cannot require the credential it helps obtain.\n", "security": [], "responses": { "200": { "description": "Protected-resource metadata", "content": { "application/json": { "schema": { "type": "object", "required": [ "resource", "authorization_servers" ], "properties": { "resource": { "type": "string", "description": "The protected resource URL (…/mcp)" }, "authorization_servers": { "type": "array", "items": { "type": "string" }, "description": "Base URLs of the authorization server(s) — the auth service." }, "bearer_methods_supported": { "type": "array", "items": { "type": "string" } } } }, "examples": { "local": { "value": { "resource": "https://agents.yieldfabric.com/mcp", "authorization_servers": [ "https://auth.yieldfabric.com" ], "bearer_methods_supported": [ "header" ] } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_oauthProtectedResource_Misc", "resource_uri": "yf://agents/mcp", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl https://agents.yieldfabric.com/.well-known/oauth-protected-resource" } ], "x-related": [ "/mcp", "/.well-known/oauth-authorization-server" ] } }, "/.well-known/oauth-protected-resource/mcp": { "get": { "operationId": "oauthProtectedResourceMcp_Misc", "x-method": "GET", "x-path": "/.well-known/oauth-protected-resource/mcp", "x-handler": "yieldfabric_mcp_transport::http::oauth_protected_resource::", "tags": [ "MCP" ], "summary": "OAuth protected-resource metadata at the MCP resource suffix", "description": "RFC 9728 discovery alias for clients that derive metadata as\n`/.well-known/oauth-protected-resource` plus the protected resource path.\nIt returns the same document as the origin-level endpoint: the protected\nresource is `/mcp`, and the configured auth-service base\nis its authorization server. Anonymous by design.\n", "security": [], "responses": { "200": { "description": "Protected-resource metadata for `/mcp`.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "resource", "authorization_servers", "bearer_methods_supported" ], "properties": { "resource": { "type": "string" }, "authorization_servers": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "bearer_methods_supported": { "type": "array", "items": { "type": "string", "const": "header" } } } }, "example": { "resource": "https://agents.yieldfabric.com/mcp", "authorization_servers": [ "https://auth.yieldfabric.com" ], "bearer_methods_supported": [ "header" ] } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_oauthProtectedResourceMcp_Misc", "resource_uri": "yf://agents/mcp", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl https://agents.yieldfabric.com/.well-known/oauth-protected-resource/mcp" } ], "x-related": [ { "operationId": "oauthProtectedResource_Misc", "relation": "alias" }, { "operationId": "oauthAuthorizationServerShimMcp_Misc", "relation": "authorization-server" }, { "operationId": "handleMcpHttp_Misc", "relation": "describes" } ] } }, "/agents": { "get": { "operationId": "listAgents_Agents", "x-method": "GET", "x-path": "/agents", "x-handler": "handlers::agent_registry::list_agents", "tags": [ "Agents" ], "summary": "List agents visible to the caller (latest version of each)", "description": "Each agent resolves to the authenticated caller's visible version before filtering.\nReturn all agents the caller is allowed to see, one row per agent (the\nlatest non-retired version). Visibility is scoped: the registry filters by\nthe caller's user-tier specs, the working groups they belong to, and the\neconomies they participate in; system-tier specs are always returned.\nAuth: bearer JWT — `Authorization: Bearer `. The handler resolves\nthe caller's group + economy membership from the token before filtering.\nThis is the read used by the Studio sidebar, pipeline composition pickers,\nand the `/agents` MCP resource. The endpoint is idempotent and safe to\ncache for short windows (TTL ~10s recommended).\n", "responses": { "200": { "description": "Array of agent summaries (id, version, display_name, role, source, working_group_id).", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "Lightweight listing form.", "required": [ "id", "version", "display_name", "role", "source" ], "properties": { "id": { "type": "string" }, "version": { "type": "string" }, "display_name": { "type": "string" }, "role": { "type": "string" }, "source": { "type": "string", "enum": [ "seed", "user", "team_construction" ] }, "created_by": { "type": [ "string", "null" ] }, "working_group_id": { "type": [ "string", "null" ], "format": "uuid" } } } }, "examples": { "two-agents": { "summary": "Two visible agents", "value": [ { "id": "yieldfabric.proposer", "version": "1.4.0", "display_name": "Proposer", "role": "proposer", "source": "seed", "created_by": null, "working_group_id": null }, { "id": "acme.weekly-summariser", "version": "0.2.1", "display_name": "Weekly Summariser", "role": "summariser", "source": "user", "created_by": "bob@acme.example", "working_group_id": "6c1c79bb-7e2e-4a06-83a7-9d4d6c7a0e21" } ] } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listAgents_Agents", "resource_uri": "yf://agents/agents", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/agents" } ], "x-related": [ { "operationId": "getAgent_Agents" }, { "operationId": "createAgent_Agents" }, { "operationId": "discoverAgents_Agents" }, { "url": "guides/agents-studio.md", "description": "Agents and Studio guide" } ] }, "post": { "operationId": "createAgent_Agents", "x-method": "POST", "x-path": "/agents", "x-handler": "handlers::agent_registry::create_agent", "tags": [ "Agents" ], "summary": "Create a new agent or publish a new version", "description": "Create a new agent or push a new version of an existing one. The request\nbody is an `AgentSpec` (flattened) plus an optional `created_by` field\nidentifying the author. The handler first calls `spec.resolve()` to\nverify the skills, tool grants, model selector, and pinned-KG ids all\nbind cleanly; if validation fails the call returns 422 with the error\nmessage. Otherwise the spec is persisted as a new row in the registry\nwith the supplied `version` string. Auth: bearer JWT. Not idempotent —\nposting the same `(id, version)` twice returns 409 (`CONFLICT`). To\npublish a revision, bump the `version` field and POST again; both rows\nco-exist and `GET /agents/{id}` returns the newest non-retired one.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Body is an `AgentSpec` (flattened) plus an optional `created_by`. The\nspec MUST resolve before persisting; failures return 422.\n", "required": [ "id", "version", "display_name", "role", "goal", "source", "system_prompt" ], "allOf": [ { "type": "object", "description": "The unified agent definition. Every agent — pipeline agents, user\nspecialists, team-construction agents — is one of these.\n", "required": [ "id", "version", "display_name", "role", "goal", "source", "system_prompt" ], "properties": { "id": { "type": "string" }, "version": { "type": "string" }, "display_name": { "type": "string" }, "role": { "type": "string" }, "goal": { "type": "string" }, "source": { "type": "string", "enum": [ "seed", "user", "team_construction" ] }, "system_prompt": { "type": "string" }, "skills": { "type": "array", "items": { "type": "object", "required": [ "name", "prompt_addendum" ], "properties": { "name": { "type": "string" }, "prompt_addendum": { "type": "string" }, "tool_grants": { "description": "Arbitrary JSON value." } } } }, "model": { "type": "object", "description": "Per-agent model routing. The `ProviderRegistry` resolves this to a\nconcrete LLMProvider at runtime.\n", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "default", "tagged", "exact" ] }, "tag": { "type": [ "string", "null" ], "description": "Used when kind=tagged." }, "provider": { "type": [ "string", "null" ], "description": "Used when kind=exact." }, "model": { "type": [ "string", "null" ], "description": "Used when kind=exact." } } }, "reasoning_effort": { "type": "string", "enum": [ "low", "medium", "high", "max" ] }, "max_tokens": { "type": "integer", "default": 4000 }, "tools": { "description": "Arbitrary JSON value." }, "context_builder": { "type": "string", "default": "summarised" }, "output_parser": { "type": "string", "default": "tool_calls" }, "memory_enabled": { "type": "boolean", "default": false }, "created_by": { "type": [ "string", "null" ] }, "economy_id": { "type": [ "string", "null" ], "format": "uuid" }, "working_group_id": { "type": [ "string", "null" ], "format": "uuid" }, "user_id": { "type": [ "string", "null" ] }, "pinned_kg_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "personality": { "type": [ "string", "null" ] }, "expertise": { "type": "array", "items": { "type": "string" } }, "focus": { "type": [ "string", "null" ] }, "anti_focus": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": { "description": "Arbitrary JSON value." } } } }, { "type": "object", "properties": { "created_by": { "type": [ "string", "null" ] } } } ] }, "examples": { "minimal": { "summary": "Minimal user-tier agent", "value": { "id": "acme.weekly-summariser", "version": "0.1.0", "display_name": "Weekly Summariser", "role": "summariser", "goal": "Summarise the prior week's notebook activity.", "system_prompt": "You are a weekly summariser. Read the user's notebook activity\nfor the past 7 days and produce a one-paragraph summary.\n", "model": { "kind": "alias", "alias": "default" }, "max_tokens": 2048, "memory_enabled": false, "tools": { "allow": [], "deny": [] }, "skills": [], "source": "user", "created_by": "bob@acme.example" } }, "with-skills": { "summary": "Agent with skills and pinned KG", "value": { "id": "acme.research-analyst", "version": "1.0.0", "display_name": "Research Analyst", "role": "analyst", "goal": "Investigate a topic against the firm's reference KG.", "system_prompt": "You are a research analyst. Use the firm's KG as your primary\nreference. Cite chunk ids when you make factual claims.\n", "model": { "kind": "alias", "alias": "capable" }, "reasoning_effort": "medium", "max_tokens": 8192, "memory_enabled": true, "pinned_kg_ids": [ "4f1c7a8e-2b6f-4f01-9a2d-3a5d2c1e7b81" ], "tools": { "allow": [ "kg.search", "kg.cite", "memory.put" ], "deny": [] }, "skills": [ { "name": "cite-as-you-go", "prompt_addendum": "When you reference a fact, attach the chunk_id you read it from." } ], "source": "user", "created_by": "alice@acme.example" } } } } } }, "responses": { "201": { "description": "Agent created. Returns the canonical id + version that were persisted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "version" ], "properties": { "id": { "type": "string" }, "version": { "type": "string" } } }, "examples": { "created": { "summary": "New version persisted", "value": { "id": "acme.research-analyst", "version": "1.0.0" } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "409": { "description": "Conflicting state (e.g. step already completed, intent already cancelled, duplicate idempotency key with different body).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "422": { "description": "Spec failed validation (skill binding, tool grant, model alias, or pinned-KG check).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_createAgent_Agents", "resource_uri": "yf://agents/agents", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" \\\n -d '{\"id\":\"acme.weekly-summariser\",\"version\":\"0.1.0\",\"display_name\":\"Weekly Summariser\",\"role\":\"summariser\",\"goal\":\"Summarise\",\"system_prompt\":\"...\",\"model\":{\"kind\":\"alias\",\"alias\":\"default\"},\"max_tokens\":2048,\"memory_enabled\":false,\"tools\":{\"allow\":[],\"deny\":[]},\"skills\":[],\"source\":\"user\"}' \\\n https://agents.yieldfabric.com/agents\n" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx, os\nspec = {\n \"id\": \"acme.weekly-summariser\",\n \"version\": \"0.1.0\",\n \"display_name\": \"Weekly Summariser\",\n \"role\": \"summariser\",\n \"goal\": \"Summarise the prior week's notebook activity.\",\n \"system_prompt\": \"You are a weekly summariser...\",\n \"model\": {\"kind\": \"alias\", \"alias\": \"default\"},\n \"max_tokens\": 2048,\n \"memory_enabled\": False,\n \"tools\": {\"allow\": [], \"deny\": []},\n \"skills\": [],\n \"source\": \"user\",\n \"created_by\": \"bob@acme.example\",\n}\nr = httpx.post(\n \"https://agents.yieldfabric.com/agents\",\n headers={\"Authorization\": f\"Bearer {os.environ['JWT']}\"},\n json=spec,\n)\nr.raise_for_status()\nprint(r.json()) # {\"id\": \"...\", \"version\": \"0.1.0\"}\n" } ], "x-related": [ { "operationId": "getAgent_Agents" }, { "operationId": "validateAgent_Agents" }, { "operationId": "retireAgentVersion_Agents" }, { "operationId": "listAgents_Agents" }, { "url": "guides/agents-studio.md", "description": "Agents and Studio guide" } ] } }, "/agents/discover": { "post": { "operationId": "discoverAgents_Agents", "x-method": "POST", "x-path": "/agents/discover", "x-handler": "wg::discover_agents", "tags": [ "Agents" ], "summary": "Discover active agents matching a free-text query", "description": "Free-text discovery over active agents in the working-group registry.\nThe query is matched against the agent's `role`, `display_name`,\n`expertise`, and `capabilities`; results are ordered by historical\n`sessions_participated` (busiest agents first) and capped by `top_k`\n(default 4). Auth: bearer JWT. Not idempotent in the strict sense\n(results can shift as new agents are seeded), but safe to retry.\nUse this when composing a multi-agent team and you only know the\ndomain — call once with the topic (\"loan underwriting\", \"tax\",\n\"yield strategy\") and pick the top hits to wire into a pipeline.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string" }, "top_k": { "type": "integer", "default": 4, "minimum": 1 } } }, "examples": { "minimal": { "summary": "Default top_k (4)", "value": { "query": "tax" } }, "explicit-top-k": { "summary": "Cap at 2 results", "value": { "query": "underwriting", "top_k": 2 } } } } } }, "responses": { "200": { "description": "Discovery results, ordered by activity.", "content": { "application/json": { "schema": { "type": "object", "required": [ "agents" ], "properties": { "agents": { "type": "array", "items": { "type": "object", "required": [ "id", "agent_key", "display_name", "role" ], "properties": { "id": { "type": "string", "format": "uuid" }, "agent_key": { "type": "string" }, "display_name": { "type": "string" }, "role": { "type": "string" }, "expertise": { "type": "array", "items": { "type": "string" } }, "focus": { "type": [ "string", "null" ] }, "capabilities": { "type": "array", "items": { "type": "string" } } } } } } }, "examples": { "two-hits": { "summary": "Two matching agents", "value": { "agents": [ { "id": "7a7e2ab2-4c01-4b5b-8d56-3e7f8c2a1b09", "agent_key": "acme.tax-analyst", "display_name": "Tax Analyst", "role": "analyst", "expertise": [ "tax", "withholding", "treaty" ], "focus": "cross-border", "capabilities": [ "cite", "summarise" ] }, { "id": "4c1e0a9d-7b32-49f0-b6f2-1e2d3c4b5a6f", "agent_key": "acme.tax-reviewer", "display_name": "Tax Reviewer", "role": "reviewer", "expertise": [ "tax" ], "focus": null, "capabilities": [ "critique" ] } ] } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_discoverAgents_Agents", "resource_uri": "yf://agents/agents", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" \\\n -d '{\"query\":\"tax\",\"top_k\":4}' \\\n https://agents.yieldfabric.com/agents/discover\n" } ], "x-related": [ { "operationId": "listAgents_Agents" }, { "operationId": "getAgent_Agents" }, { "url": "guides/agents-studio.md", "description": "Agents and Studio guide" } ] } }, "/agents/validate": { "post": { "operationId": "validateAgent_Agents", "x-method": "POST", "x-path": "/agents/validate", "x-handler": "handlers::agent_registry::validate_agent", "tags": [ "Agents" ], "summary": "Dry-run validation of an AgentSpec without persisting", "description": "Run the same `spec.resolve()` validation that `POST /agents` runs, but\nwithout writing to the registry. Use this from the Studio editor to give\ninline feedback (broken tool grant, unknown skill, mis-typed model alias)\nbefore the user clicks Save. Auth: bearer JWT. Idempotent.\nReturns `200 OK` with `{ valid: true, error: null }` when the spec\nresolves cleanly, or `422 Unprocessable Entity` with `{ valid: false,\nerror: \"...\" }` carrying a human-readable diagnostic when it doesn't.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "The unified agent definition. Every agent — pipeline agents, user\nspecialists, team-construction agents — is one of these.\n", "required": [ "id", "version", "display_name", "role", "goal", "source", "system_prompt" ], "properties": { "id": { "type": "string" }, "version": { "type": "string" }, "display_name": { "type": "string" }, "role": { "type": "string" }, "goal": { "type": "string" }, "source": { "type": "string", "enum": [ "seed", "user", "team_construction" ] }, "system_prompt": { "type": "string" }, "skills": { "type": "array", "items": { "type": "object", "required": [ "name", "prompt_addendum" ], "properties": { "name": { "type": "string" }, "prompt_addendum": { "type": "string" }, "tool_grants": { "description": "Arbitrary JSON value." } } } }, "model": { "type": "object", "description": "Per-agent model routing. The `ProviderRegistry` resolves this to a\nconcrete LLMProvider at runtime.\n", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "default", "tagged", "exact" ] }, "tag": { "type": [ "string", "null" ], "description": "Used when kind=tagged." }, "provider": { "type": [ "string", "null" ], "description": "Used when kind=exact." }, "model": { "type": [ "string", "null" ], "description": "Used when kind=exact." } } }, "reasoning_effort": { "type": "string", "enum": [ "low", "medium", "high", "max" ] }, "max_tokens": { "type": "integer", "default": 4000 }, "tools": { "description": "Arbitrary JSON value." }, "context_builder": { "type": "string", "default": "summarised" }, "output_parser": { "type": "string", "default": "tool_calls" }, "memory_enabled": { "type": "boolean", "default": false }, "created_by": { "type": [ "string", "null" ] }, "economy_id": { "type": [ "string", "null" ], "format": "uuid" }, "working_group_id": { "type": [ "string", "null" ], "format": "uuid" }, "user_id": { "type": [ "string", "null" ] }, "pinned_kg_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "personality": { "type": [ "string", "null" ] }, "expertise": { "type": "array", "items": { "type": "string" } }, "focus": { "type": [ "string", "null" ] }, "anti_focus": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": { "description": "Arbitrary JSON value." } } } }, "examples": { "ok": { "summary": "A valid spec", "value": { "id": "acme.weekly-summariser", "version": "0.1.0", "display_name": "Weekly Summariser", "role": "summariser", "goal": "Summarise activity.", "system_prompt": "You are a summariser.", "model": { "kind": "alias", "alias": "default" }, "max_tokens": 2048, "memory_enabled": false, "tools": { "allow": [], "deny": [] }, "skills": [], "source": "user" } }, "bad-tool": { "summary": "References an unknown tool", "value": { "id": "acme.weekly-summariser", "version": "0.1.0", "display_name": "Weekly Summariser", "role": "summariser", "goal": "Summarise activity.", "system_prompt": "You are a summariser.", "model": { "kind": "alias", "alias": "default" }, "max_tokens": 2048, "memory_enabled": false, "tools": { "allow": [ "doesnt.exist" ], "deny": [] }, "skills": [], "source": "user" } } } } } }, "responses": { "200": { "description": "Spec is valid.", "content": { "application/json": { "schema": { "type": "object", "required": [ "valid" ], "properties": { "valid": { "type": "boolean" }, "error": { "type": [ "string", "null" ] } } }, "examples": { "valid": { "summary": "Valid response", "value": { "valid": true, "error": null } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "422": { "description": "Spec failed validation. `error` carries a human-readable diagnostic.", "content": { "application/json": { "schema": { "type": "object", "required": [ "valid" ], "properties": { "valid": { "type": "boolean" }, "error": { "type": [ "string", "null" ] } } }, "examples": { "invalid": { "summary": "Invalid response", "value": { "valid": false, "error": "unknown tool 'doesnt.exist' in allow list" } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_validateAgent_Agents", "resource_uri": "yf://agents/agents", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" \\\n -d @spec.json \\\n https://agents.yieldfabric.com/agents/validate\n" } ], "x-related": [ { "operationId": "createAgent_Agents" }, { "operationId": "getAgent_Agents" }, { "url": "guides/agents-studio.md", "description": "Agents and Studio guide" } ] } }, "/agents/{id}": { "get": { "operationId": "getAgent_Agents", "x-method": "GET", "x-path": "/agents/{id}", "x-handler": "handlers::agent_registry::get_agent", "tags": [ "Agents" ], "summary": "Get the latest version of an agent's full spec", "description": "Returns the version visible to the authenticated caller; another user's personal version cannot shadow it.\nReturn the full `AgentSpec` for the latest non-retired version of the\nagent identified by `id` (UUID or slug). The response includes the\nsystem prompt, model selector, skills, tool grants, memory configuration,\nreasoning effort, and tier metadata. Auth: bearer JWT. Idempotent.\nThe Studio sidebar uses this read to hydrate the editor; pipeline\nresolution loads the same data when composing a team. Returns 404 when\nno version of the agent exists or all versions have been retired.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent id (UUID or slug).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Full agent spec for the latest version.", "content": { "application/json": { "schema": { "type": "object", "description": "The unified agent definition. Every agent — pipeline agents, user\nspecialists, team-construction agents — is one of these.\n", "required": [ "id", "version", "display_name", "role", "goal", "source", "system_prompt" ], "properties": { "id": { "type": "string" }, "version": { "type": "string" }, "display_name": { "type": "string" }, "role": { "type": "string" }, "goal": { "type": "string" }, "source": { "type": "string", "enum": [ "seed", "user", "team_construction" ] }, "system_prompt": { "type": "string" }, "skills": { "type": "array", "items": { "type": "object", "required": [ "name", "prompt_addendum" ], "properties": { "name": { "type": "string" }, "prompt_addendum": { "type": "string" }, "tool_grants": { "description": "Arbitrary JSON value." } } } }, "model": { "type": "object", "description": "Per-agent model routing. The `ProviderRegistry` resolves this to a\nconcrete LLMProvider at runtime.\n", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "default", "tagged", "exact" ] }, "tag": { "type": [ "string", "null" ], "description": "Used when kind=tagged." }, "provider": { "type": [ "string", "null" ], "description": "Used when kind=exact." }, "model": { "type": [ "string", "null" ], "description": "Used when kind=exact." } } }, "reasoning_effort": { "type": "string", "enum": [ "low", "medium", "high", "max" ] }, "max_tokens": { "type": "integer", "default": 4000 }, "tools": { "description": "Arbitrary JSON value." }, "context_builder": { "type": "string", "default": "summarised" }, "output_parser": { "type": "string", "default": "tool_calls" }, "memory_enabled": { "type": "boolean", "default": false }, "created_by": { "type": [ "string", "null" ] }, "economy_id": { "type": [ "string", "null" ], "format": "uuid" }, "working_group_id": { "type": [ "string", "null" ], "format": "uuid" }, "user_id": { "type": [ "string", "null" ] }, "pinned_kg_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "personality": { "type": [ "string", "null" ] }, "expertise": { "type": "array", "items": { "type": "string" } }, "focus": { "type": [ "string", "null" ] }, "anti_focus": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": { "description": "Arbitrary JSON value." } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getAgent_Agents", "resource_uri": "yf://agents/agents", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/agents/yieldfabric.proposer" } ], "x-related": [ { "operationId": "getAgentVersions_Agents" }, { "operationId": "listAgents_Agents" }, { "operationId": "createAgent_Agents" }, { "url": "guides/agents-studio.md", "description": "Agents and Studio guide" } ] } }, "/agents/{id}/memory": { "get": { "operationId": "listGlobalAgentMemory_Agents", "x-method": "GET", "x-path": "/agents/{id}/memory", "x-handler": "handlers::agent_registry::list_global_agent_memory", "tags": [ "Agents" ], "summary": "List the agent's global memories (cross-KG, cross-group)", "description": "Requires a caller-visible agent. Reads and writes address only the verified\ncaller's private memory partition, including when the agent spec is shared.\nReturn every global-scope memory row for the agent identified by `id`.\nGlobal memories are the agent's cross-KG, cross-working-group learning —\nthings like coding-style preferences, persistent persona instructions,\nor named-entity disambiguation tables that should follow the agent\neverywhere. KG-scoped and working-group-scoped memories live behind\nseparate endpoints (`/kgs/{kg_id}/agent_memory/{id}` and the\nworking-group-namespaced equivalent). Auth: bearer JWT. Idempotent.\nRows are returned in `updated_at` DESC order. The global scope is capped\nat 30 entries per agent and user (see `MAX_GLOBAL_MEMORIES` in `agents/memory.rs`).\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent id (UUID or slug).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of `MemoryRow` entries.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "agent_id", "key", "value", "created_at", "updated_at" ], "properties": { "agent_id": { "type": "string" }, "user_id": { "type": [ "string", "null" ] }, "kg_id": { "type": [ "string", "null" ], "format": "uuid" }, "working_group_id": { "type": [ "string", "null" ], "format": "uuid" }, "key": { "type": "string" }, "value": { "description": "Arbitrary JSON value." }, "description": { "type": [ "string", "null" ] }, "confidence": { "type": [ "number", "null" ] }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } }, "examples": { "two-entries": { "summary": "Two global memories", "value": [ { "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef", "agent_id": "yieldfabric.proposer", "user_id": null, "kg_id": null, "working_group_id": null, "key": "tone_preference", "memory_type": "reference", "description": "User prefers concise, jargon-free responses.", "value": { "tone": "concise", "jargon": "avoid" }, "created_at": "2027-05-01T10:00:00Z", "updated_at": "2027-05-12T14:30:00Z" } ] } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listGlobalAgentMemory_Agents", "resource_uri": "yf://agents/agents", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/agents/yieldfabric.proposer/memory" } ], "x-related": [ { "operationId": "putGlobalAgentMemory_Agents" }, { "operationId": "deleteGlobalAgentMemory_Agents" }, { "operationId": "migrateAgentMemory_Agents" }, { "url": "guides/agents-studio.md", "description": "Agents and Studio guide" } ] }, "post": { "operationId": "putGlobalAgentMemory_Agents", "x-method": "POST", "x-path": "/agents/{id}/memory", "x-handler": "handlers::agent_registry::put_global_agent_memory", "tags": [ "Agents" ], "summary": "Upsert a global-scope memory entry for an agent", "description": "Requires a caller-visible agent. Reads and writes address only the verified\ncaller's private memory partition, including when the agent spec is shared.\nInsert or update a global memory entry for the agent identified by `id`.\nThe body is a `MemoryEntry` (`key`, `memory_type`, `description`,\n`value`). Existing entries with the same `(agent_id, key)` are replaced;\nthe upsert is keyed by `key`, so callers don't need a separate\n\"update\" endpoint. Auth: bearer JWT. Idempotent at the `key` level —\nretrying the same body is safe and converges to the same row.\nGlobal scope is capped at 30 entries per agent and user. Returns `204 No Content`\non success. For KG- or working-group-scoped writes, use the matching\n`/kgs/{kg_id}/agent_memory/{id}` endpoint instead.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent id (UUID or slug).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "One memory entry for an agent at a given scope (KG / WG / global).", "required": [ "key", "value" ], "properties": { "key": { "type": "string" }, "value": { "description": "Arbitrary JSON value." }, "description": { "type": [ "string", "null" ] }, "confidence": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 } } }, "examples": { "tone-preference": { "summary": "Save the user's tone preference", "value": { "key": "tone_preference", "memory_type": "reference", "description": "User prefers concise, jargon-free responses.", "value": { "tone": "concise", "jargon": "avoid" } } }, "feedback": { "summary": "Persist agent feedback", "value": { "key": "avoid_speculation", "memory_type": "feedback", "description": "Don't speculate about unfounded scenarios.", "value": { "rule": "stick to cited facts only" } } } } } } }, "responses": { "204": { "description": "Memory entry upserted." }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_putGlobalAgentMemory_Agents", "resource_uri": "yf://agents/agents", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" \\\n -d '{\"key\":\"tone_preference\",\"memory_type\":\"reference\",\"description\":\"...\",\"value\":{\"tone\":\"concise\"}}' \\\n https://agents.yieldfabric.com/agents/yieldfabric.proposer/memory\n" } ], "x-related": [ { "operationId": "listGlobalAgentMemory_Agents" }, { "operationId": "deleteGlobalAgentMemory_Agents" }, { "operationId": "migrateAgentMemory_Agents" }, { "url": "guides/agents-studio.md", "description": "Agents and Studio guide" } ] } }, "/agents/{id}/memory/{key}": { "delete": { "operationId": "deleteGlobalAgentMemory_Agents", "x-method": "DELETE", "x-path": "/agents/{id}/memory/{key}", "x-handler": "handlers::agent_registry::delete_global_agent_memory", "tags": [ "Agents" ], "summary": "Delete a global-scope memory entry for an agent", "description": "Requires a caller-visible agent. Reads and writes address only the verified\ncaller's private memory partition, including when the agent spec is shared.\nRemove a single global memory row identified by `(agent_id, key)`.\nReturns `204 No Content` on success and `404` when no entry with that\nkey exists in the global scope. KG-scoped and working-group-scoped\nentries are NOT touched by this call — they live in separate rows and\nare addressed through their own scoped endpoints. Auth: bearer JWT.\nNot idempotent in the strict sense (a second DELETE returns 404), but\nsafe to retry.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent id (UUID or slug).", "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "description": "Memory key (as set in `MemoryEntry.key` on the upsert).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Memory entry deleted." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_deleteGlobalAgentMemory_Agents", "resource_uri": "yf://agents/agents", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X DELETE -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/agents/yieldfabric.proposer/memory/tone_preference" } ], "x-related": [ { "operationId": "listGlobalAgentMemory_Agents" }, { "operationId": "putGlobalAgentMemory_Agents" }, { "url": "guides/agents-studio.md", "description": "Agents and Studio guide" } ] } }, "/agents/{id}/migrate_memory": { "post": { "operationId": "migrateAgentMemory_Agents", "x-method": "POST", "x-path": "/agents/{id}/migrate_memory", "x-handler": "handlers::agent_registry::migrate_agent_memory", "tags": [ "Agents" ], "summary": "Copy all memories from this agent to a target agent id", "description": "Copy the authenticated caller's memory from the visible source agent to the\nvisible target_agent_id. Only entries in currently accessible KG and working\ngroup scopes, plus the caller's global entries, are eligible. Other users and\nlegacy unpartitioned entries are excluded. Existing destination keys are\npreserved. Returns `{ copied: }` for newly inserted rows; repeating the\nsame migration inserts zero additional rows. Auth: bearer JWT. Idempotent.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent id (UUID or slug).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target_agent_id" ], "properties": { "target_agent_id": { "type": "string" } } }, "examples": { "rename": { "summary": "Fork acme.proposer-v1 -> acme.proposer", "value": { "target_agent_id": "acme.proposer" } } } } } }, "responses": { "200": { "description": "Memories copied. `copied` is the row count written to the target.", "content": { "application/json": { "schema": { "type": "object", "required": [ "copied" ], "properties": { "copied": { "type": "integer", "minimum": 0 } } }, "examples": { "copied-12": { "summary": "12 memory rows copied", "value": { "copied": 12 } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_migrateAgentMemory_Agents", "resource_uri": "yf://agents/agents", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" \\\n -d '{\"target_agent_id\":\"acme.proposer\"}' \\\n https://agents.yieldfabric.com/agents/acme.proposer-v1/migrate_memory\n" } ], "x-related": [ { "operationId": "listGlobalAgentMemory_Agents" }, { "operationId": "putGlobalAgentMemory_Agents" }, { "operationId": "createAgent_Agents" }, { "url": "guides/agents-studio.md", "description": "Agents and Studio guide" } ] } }, "/agents/{id}/runs": { "get": { "operationId": "listAgentRuns_Agents", "x-method": "GET", "x-path": "/agents/{id}/runs", "x-handler": "handlers::agent_registry::list_agent_runs", "tags": [ "Agents" ], "summary": "List the 10 most recent pipeline runs this agent participated in", "description": "Requires a caller-visible agent and access to all associated run resources, including private conversations.\nReturn up to 10 recent runs where this agent was invoked, grouped by\n`run_id`. Each row carries the target KG (`kg_id` + `kg_name`),\n`invocation_count`, `total_tokens` (prompt + completion), `avg_latency_ms`,\nand `last_used` timestamp. Auth: bearer JWT. Idempotent.\nUsed by the Studio \"recent activity\" pane and the agent-detail page to\nsurface where this agent has been useful. The 10-row cap is hardcoded\nin the handler; for longer history call `GET /pipelines/{run_id}/invocations`\nwith `agent_id=` for specific runs.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent id (UUID or slug).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Up to 10 recent run summaries for this agent.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "run_id", "kg_id", "invocation_count", "total_tokens", "avg_latency_ms", "last_used" ], "properties": { "run_id": { "type": "string", "format": "uuid" }, "kg_id": { "type": "string", "format": "uuid" }, "kg_name": { "type": [ "string", "null" ] }, "invocation_count": { "type": "integer", "minimum": 0 }, "total_tokens": { "type": "integer", "minimum": 0 }, "avg_latency_ms": { "type": "integer", "minimum": 0 }, "last_used": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } }, "examples": { "one-run": { "summary": "One recent run", "value": [ { "run_id": "9d3b1a2c-5e6f-4d7a-8b9c-0d1e2f3a4b5c", "kg_id": "4f1c7a8e-2b6f-4f01-9a2d-3a5d2c1e7b81", "kg_name": "Acme Research KG", "invocation_count": 12, "total_tokens": 18432, "avg_latency_ms": 1280, "last_used": "2027-05-17T13:22:11Z" } ] } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listAgentRuns_Agents", "resource_uri": "yf://agents/agents", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/agents/yieldfabric.proposer/runs" } ], "x-related": [ { "operationId": "getAgent_Agents" }, { "operationId": "listInvocations_Pipelines" }, { "url": "guides/agents-studio.md", "description": "Agents and Studio guide" } ] } }, "/agents/{id}/studio/chat": { "post": { "operationId": "studioChat_Agents", "x-method": "POST", "x-path": "/agents/{id}/studio/chat", "x-handler": "handlers::agent_studio::studio_chat", "tags": [ "Agents" ], "summary": "Send a message to an agent in Studio mode and get its reply", "description": "Send a message in the authenticated caller's private conversation with a\nvisible agent. The handler resolves its configured model, persona, skills and\nprivate memory. An optional spec_override changes editable behavior but cannot\nreplace identity, version, creator or ownership scopes. Optional kg_id must\nbe a valid accessible KG before the user turn is saved.\nCoach mode (default) includes spec feedback and typed proposal blocks; direct\nmode rehearses the configured persona. This is one conversational completion,\nnot full production tool execution. Successful replies and proposal cards are\nsaved together. Provider failure or incomplete output returns 502 before\naccepting a reply, proposals or direct-mode memory writes; the saved user turn\nremains available for retry. Direct memory writes require memory_enabled.\nThe response is synchronous JSON. Auth: bearer JWT. Not idempotent.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent id (UUID or slug).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "spec_override": { "oneOf": [ { "type": "object", "description": "The unified agent definition. Every agent — pipeline agents, user\nspecialists, team-construction agents — is one of these.\n", "required": [ "id", "version", "display_name", "role", "goal", "source", "system_prompt" ], "properties": { "id": { "type": "string" }, "version": { "type": "string" }, "display_name": { "type": "string" }, "role": { "type": "string" }, "goal": { "type": "string" }, "source": { "type": "string", "enum": [ "seed", "user", "team_construction" ] }, "system_prompt": { "type": "string" }, "skills": { "type": "array", "items": { "type": "object", "required": [ "name", "prompt_addendum" ], "properties": { "name": { "type": "string" }, "prompt_addendum": { "type": "string" }, "tool_grants": { "description": "Arbitrary JSON value." } } } }, "model": { "type": "object", "description": "Per-agent model routing. The `ProviderRegistry` resolves this to a\nconcrete LLMProvider at runtime.\n", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "default", "tagged", "exact" ] }, "tag": { "type": [ "string", "null" ], "description": "Used when kind=tagged." }, "provider": { "type": [ "string", "null" ], "description": "Used when kind=exact." }, "model": { "type": [ "string", "null" ], "description": "Used when kind=exact." } } }, "reasoning_effort": { "type": "string", "enum": [ "low", "medium", "high", "max" ] }, "max_tokens": { "type": "integer", "default": 4000 }, "tools": { "description": "Arbitrary JSON value." }, "context_builder": { "type": "string", "default": "summarised" }, "output_parser": { "type": "string", "default": "tool_calls" }, "memory_enabled": { "type": "boolean", "default": false }, "created_by": { "type": [ "string", "null" ] }, "economy_id": { "type": [ "string", "null" ], "format": "uuid" }, "working_group_id": { "type": [ "string", "null" ], "format": "uuid" }, "user_id": { "type": [ "string", "null" ] }, "pinned_kg_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "personality": { "type": [ "string", "null" ] }, "expertise": { "type": "array", "items": { "type": "string" } }, "focus": { "type": [ "string", "null" ] }, "anti_focus": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": { "description": "Arbitrary JSON value." } } } }, { "type": "null" } ], "description": "Overrides editable behavior for this turn; identity, version, creator and ownership scopes stay pinned to the caller-visible published spec." }, "mode": { "type": "string", "enum": [ "coach", "direct" ], "default": "coach" }, "kg_id": { "type": [ "string", "null" ], "format": "uuid", "description": "An accessible KG to load as context; malformed or unauthorized selections fail before the user turn is saved." } } }, "examples": { "coach": { "summary": "Coach mode (default) - ask agent to critique itself", "value": { "message": "Your system prompt feels too verbose. Can you suggest a tighter version?", "mode": "coach" } }, "direct": { "summary": "Direct mode - rehearse production behaviour", "value": { "message": "Summarise the latest deal memo I attached.", "mode": "direct" } }, "with-spec-override": { "summary": "Test an edited spec without publishing", "value": { "message": "How would you respond to a request for cost reduction?", "mode": "direct", "spec_override": { "id": "acme.proposer", "version": "1.4.0-draft", "display_name": "Proposer", "role": "proposer", "goal": "Propose deal options.", "system_prompt": "You are a terse proposer. Three options max.", "model": { "kind": "alias", "alias": "default" }, "max_tokens": 1024, "memory_enabled": true, "tools": { "allow": [ "*" ], "deny": [] }, "skills": [], "source": "user" } } }, "with-kg-context": { "summary": "Load a KG into context for the chat", "value": { "message": "Walk me through what the latest extraction discovered.", "mode": "direct", "kg_id": "4f1c7a8e-2b6f-4f01-9a2d-3a5d2c1e7b81" } } } } } }, "responses": { "200": { "description": "Reply persisted. Carries both messages and any new proposals emitted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "user_message", "agent_message", "proposals" ], "properties": { "user_message": { "type": "object", "description": "One message in the authenticated user's private Studio conversation.", "required": [ "id", "thread_id", "role", "content", "had_draft", "tool_calls", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "thread_id": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "user", "agent" ] }, "content": { "type": "string" }, "thinking": { "type": [ "string", "null" ] }, "raw_llm_response": { "type": [ "string", "null" ] }, "base_version": { "type": [ "string", "null" ] }, "had_draft": { "type": "boolean" }, "tool_calls": { "description": "Arbitrary JSON value." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } }, "agent_message": { "type": "object", "description": "One message in the authenticated user's private Studio conversation.", "required": [ "id", "thread_id", "role", "content", "had_draft", "tool_calls", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "thread_id": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "user", "agent" ] }, "content": { "type": "string" }, "thinking": { "type": [ "string", "null" ] }, "raw_llm_response": { "type": [ "string", "null" ] }, "base_version": { "type": [ "string", "null" ] }, "had_draft": { "type": "boolean" }, "tool_calls": { "description": "Arbitrary JSON value." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } }, "proposals": { "type": "array", "items": { "type": "object", "required": [ "key", "thread_id", "agent_id", "user_id", "kind", "payload", "rationale", "status", "created_at" ], "properties": { "key": { "type": "string", "format": "uuid" }, "thread_id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string" }, "user_id": { "type": "string" }, "kind": { "type": "string", "enum": [ "prompt_edit", "memory_add", "memory_edit", "memory_delete", "skill_add", "skill_remove", "behaviour_change", "tool_grant_change" ] }, "payload": { "type": "object", "description": "Typed proposal payload, including its matching kind discriminator.", "additionalProperties": true }, "rationale": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "applied", "rejected" ] }, "rejection_reason": { "type": [ "string", "null" ] }, "applied_edit": { "description": "Arbitrary JSON value." }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } }, "examples": { "coach-with-proposal": { "summary": "Coach reply with one proposal", "value": { "user_message": { "id": "aaaa1111-bbbb-2222-cccc-333333333333", "thread_id": "22222222-3333-4444-5555-666666666666", "role": "user", "content": "Your system prompt feels too verbose.", "created_at": "2027-05-17T14:00:00Z" }, "agent_message": { "id": "bbbb2222-cccc-3333-dddd-444444444444", "thread_id": "22222222-3333-4444-5555-666666666666", "role": "agent", "content": "I see what you mean. The third paragraph repeats the first. Here's a tighter version...", "created_at": "2027-05-17T14:00:04Z" }, "proposals": [ { "key": "cccc3333-dddd-4444-eeee-555555555555", "thread_id": "22222222-3333-4444-5555-666666666666", "rationale": "Keep the agent concise and consistent.", "agent_id": "acme.proposer", "user_id": "11111111-2222-4333-8444-555555555555", "kind": "prompt_edit", "status": "pending", "payload": { "kind": "prompt_edit", "op": { "replace": { "old": "You are a careful proposer..." } }, "text": "You are a terse proposer. Three options max.", "rationale": "Shorter, removes the repeated framing." }, "created_at": "2027-05-17T14:00:04Z" } ] } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "502": { "description": "Provider failed or returned incomplete output; no agent reply or effects were accepted." } }, "x-mcp": { "tool_name": "yieldfabric_agents_studioChat_Agents", "resource_uri": "yf://agents/agents", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" \\\n -d '{\"message\":\"How could your prompt be tighter?\",\"mode\":\"coach\"}' \\\n https://agents.yieldfabric.com/agents/acme.proposer/studio/chat\n" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx, os\nr = httpx.post(\n \"https://agents.yieldfabric.com/agents/acme.proposer/studio/chat\",\n headers={\"Authorization\": f\"Bearer {os.environ['JWT']}\"},\n json={\"message\": \"How could your prompt be tighter?\", \"mode\": \"coach\"},\n timeout=60.0,\n)\nr.raise_for_status()\nreply = r.json()\nprint(reply[\"agent_message\"][\"content\"])\nfor proposal in reply[\"proposals\"]:\n print(f\"Pending: {proposal['kind']} -> {proposal['key']}\")\n" } ], "x-related": [ { "operationId": "getStudioThread_Agents" }, { "operationId": "listProposals_Agents" }, { "operationId": "applyProposal_Agents" }, { "operationId": "rejectProposal_Agents" }, { "operationId": "requestProposal_Agents" }, { "url": "guides/agents-studio.md", "description": "Agents and Studio guide" } ] } }, "/agents/{id}/studio/proposals": { "get": { "operationId": "listProposals_Agents", "x-method": "GET", "x-path": "/agents/{id}/studio/proposals", "x-handler": "handlers::agent_studio::list_proposals", "tags": [ "Agents" ], "summary": "List Studio proposals raised by the agent (optionally filtered by status)", "description": "Only proposals owned by the verified caller for this visible agent are returned.\nReturn every `propose_*` block the agent has emitted in its Studio\nconversation, optionally filtered by status. Status values are\n`pending` (awaiting accept/reject), `applied` (operator clicked Apply),\nand `rejected` (operator clicked Reject with a reason). Proposals come\nin several kinds — prompt edits, memory add/edit/delete, skill add/remove,\nbehaviour changes, and tool-grant changes — surfaced via `kind` on each\nrow. Auth: bearer JWT. Idempotent.\nUse this for the Studio sidebar's pending-proposals tray or to audit\npast coaching decisions.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent id (UUID or slug).", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by proposal status. Omit to return all.", "schema": { "type": "string", "enum": [ "pending", "applied", "rejected" ] } } ], "responses": { "200": { "description": "Array of proposal rows for this agent.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "key", "thread_id", "agent_id", "user_id", "kind", "payload", "rationale", "status", "created_at" ], "properties": { "key": { "type": "string", "format": "uuid" }, "thread_id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string" }, "user_id": { "type": "string" }, "kind": { "type": "string", "enum": [ "prompt_edit", "memory_add", "memory_edit", "memory_delete", "skill_add", "skill_remove", "behaviour_change", "tool_grant_change" ] }, "payload": { "type": "object", "description": "Typed proposal payload, including its matching kind discriminator.", "additionalProperties": true }, "rationale": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "applied", "rejected" ] }, "rejection_reason": { "type": [ "string", "null" ] }, "applied_edit": { "description": "Arbitrary JSON value." }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } }, "examples": { "one-pending": { "summary": "One pending proposal", "value": [ { "key": "cccc3333-dddd-4444-eeee-555555555555", "thread_id": "22222222-3333-4444-5555-666666666666", "rationale": "Keep the agent concise and consistent.", "agent_id": "acme.proposer", "user_id": "11111111-2222-4333-8444-555555555555", "kind": "prompt_edit", "status": "pending", "payload": { "kind": "prompt_edit", "op": "append", "text": "Always cite the source chunk.", "rationale": "Improves traceability." }, "created_at": "2027-05-17T14:00:04Z" } ] } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listProposals_Agents", "resource_uri": "yf://agents/agents", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/agents/acme.proposer/studio/proposals?status=pending\"" } ], "x-related": [ { "operationId": "applyProposal_Agents" }, { "operationId": "rejectProposal_Agents" }, { "operationId": "studioChat_Agents" }, { "operationId": "requestProposal_Agents" }, { "url": "guides/agents-studio.md", "description": "Agents and Studio guide" } ] } }, "/agents/{id}/studio/proposals/{key}/apply": { "post": { "operationId": "applyProposal_Agents", "x-method": "POST", "x-path": "/agents/{id}/studio/proposals/{key}/apply", "x-handler": "handlers::agent_studio::apply_proposal", "tags": [ "Agents" ], "summary": "Accept a Studio proposal and dispatch its side effect", "description": "Resolve a pending proposal belonging to the authenticated caller and the\nvisible agent identified by `id`. The proposal row is locked for the operation.\nOptional `edit` fields are merged and validated without changing its kind.\nMemory changes affect only this caller's global memory; a failed effect leaves\nthe proposal pending. Spec changes are accepted for the editor and must be\npublished separately with `POST /agents`. Only a successful effect or accepted\nspec edit marks the proposal applied. Another apply or reject after resolution\nreturns 409. Auth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent id (UUID or slug).", "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "description": "Proposal id (UUID) from `GET /agents/{id}/studio/proposals`.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "edit": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Optional fields merged into the typed proposal payload before execution.\nThe edited payload must validate and cannot change its kind.\n" } } }, "examples": { "plain-apply": { "summary": "Accept the proposal as-is", "value": {} }, "with-edit": { "summary": "Reword the prompt before applying", "value": { "edit": { "text": "You are a terse proposer. Two options max." } } } } } } }, "responses": { "200": { "description": "Proposal applied. `effect` carries a human-readable note for memory side-effects.", "content": { "application/json": { "schema": { "type": "object", "required": [ "proposal" ], "properties": { "proposal": { "type": "object", "required": [ "key", "thread_id", "agent_id", "user_id", "kind", "payload", "rationale", "status", "created_at" ], "properties": { "key": { "type": "string", "format": "uuid" }, "thread_id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string" }, "user_id": { "type": "string" }, "kind": { "type": "string", "enum": [ "prompt_edit", "memory_add", "memory_edit", "memory_delete", "skill_add", "skill_remove", "behaviour_change", "tool_grant_change" ] }, "payload": { "type": "object", "description": "Typed proposal payload, including its matching kind discriminator.", "additionalProperties": true }, "rationale": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "applied", "rejected" ] }, "rejection_reason": { "type": [ "string", "null" ] }, "applied_edit": { "description": "Arbitrary JSON value." }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } }, "effect": { "type": [ "string", "null" ] } } }, "examples": { "memory-applied": { "summary": "Memory entry created", "value": { "proposal": { "key": "cccc3333-dddd-4444-eeee-555555555555", "thread_id": "22222222-3333-4444-5555-666666666666", "rationale": "Keep the agent concise and consistent.", "agent_id": "acme.proposer", "user_id": "11111111-2222-4333-8444-555555555555", "kind": "memory_add", "status": "applied", "payload": { "kind": "memory_add", "entry": { "key": "avoid_speculation", "memory_type": "feedback", "description": "Avoid unsupported claims", "value": true }, "rationale": "Keep the agent concise and consistent." }, "created_at": "2027-05-17T14:00:04Z" }, "effect": "Memory entry 'avoid_speculation' saved." } }, "spec-applied": { "summary": "Spec-change accepted (frontend updates sidebar)", "value": { "proposal": { "key": "cccc3333-dddd-4444-eeee-555555555555", "thread_id": "22222222-3333-4444-5555-666666666666", "rationale": "Keep the agent concise and consistent.", "agent_id": "acme.proposer", "user_id": "11111111-2222-4333-8444-555555555555", "kind": "prompt_edit", "status": "applied", "payload": { "kind": "prompt_edit", "op": "append", "text": "...", "rationale": "Keep the agent concise and consistent." }, "created_at": "2027-05-17T14:00:04Z" }, "effect": "Change accepted for your editor. Save a new version to publish it." } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "409": { "description": "Conflicting state (e.g. step already completed, intent already cancelled, duplicate idempotency key with different body).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_applyProposal_Agents", "resource_uri": "yf://agents/agents", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" \\\n -d '{}' \\\n https://agents.yieldfabric.com/agents/acme.proposer/studio/proposals/cccc3333-dddd-4444-eeee-555555555555/apply\n" } ], "x-related": [ { "operationId": "rejectProposal_Agents" }, { "operationId": "listProposals_Agents" }, { "operationId": "studioChat_Agents" }, { "url": "guides/agents-studio.md", "description": "Agents and Studio guide" } ] } }, "/agents/{id}/studio/proposals/{key}/reject": { "post": { "operationId": "rejectProposal_Agents", "x-method": "POST", "x-path": "/agents/{id}/studio/proposals/{key}/reject", "x-handler": "handlers::agent_studio::reject_proposal", "tags": [ "Agents" ], "summary": "Reject a Studio proposal with a reason", "description": "The proposal must belong to this visible agent and the verified caller; the pending row is locked before resolution.\nFlip the proposal identified by `key` from `pending` to `rejected` and\nattach the operator's `reason`. No side effect runs — the agent's spec\nand memory are unchanged. The rejection reason is surfaced to the agent\nin subsequent coach-mode turns under \"recent decisions\", so the agent\ncan learn from the feedback (\"rejected: propose_prompt_edit — reason:\ntoo aggressive a change\"). Auth: bearer JWT. Not idempotent — a second\nreject returns 409 (`already resolved`).\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent id (UUID or slug).", "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "description": "Proposal id (UUID) from `GET /agents/{id}/studio/proposals`.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string" } } }, "examples": { "with-reason": { "summary": "Reject with a short reason", "value": { "reason": "Too aggressive — would break existing pipelines." } } } } } }, "responses": { "200": { "description": "Proposal rejected.", "content": { "application/json": { "schema": { "type": "object", "required": [ "key", "thread_id", "agent_id", "user_id", "kind", "payload", "rationale", "status", "created_at" ], "properties": { "key": { "type": "string", "format": "uuid" }, "thread_id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string" }, "user_id": { "type": "string" }, "kind": { "type": "string", "enum": [ "prompt_edit", "memory_add", "memory_edit", "memory_delete", "skill_add", "skill_remove", "behaviour_change", "tool_grant_change" ] }, "payload": { "type": "object", "description": "Typed proposal payload, including its matching kind discriminator.", "additionalProperties": true }, "rationale": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "applied", "rejected" ] }, "rejection_reason": { "type": [ "string", "null" ] }, "applied_edit": { "description": "Arbitrary JSON value." }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } }, "examples": { "rejected": { "summary": "Rejected row", "value": { "key": "cccc3333-dddd-4444-eeee-555555555555", "thread_id": "22222222-3333-4444-5555-666666666666", "rationale": "Keep the agent concise and consistent.", "agent_id": "acme.proposer", "user_id": "11111111-2222-4333-8444-555555555555", "kind": "prompt_edit", "status": "rejected", "rejection_reason": "Too aggressive — would break existing pipelines.", "payload": { "kind": "prompt_edit", "op": "append", "text": "Use concise wording.", "rationale": "Keep the agent concise and consistent." }, "created_at": "2027-05-17T14:00:04Z" } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "409": { "description": "Conflicting state (e.g. step already completed, intent already cancelled, duplicate idempotency key with different body).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_rejectProposal_Agents", "resource_uri": "yf://agents/agents", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" \\\n -d '{\"reason\":\"Too aggressive.\"}' \\\n https://agents.yieldfabric.com/agents/acme.proposer/studio/proposals/cccc3333-dddd-4444-eeee-555555555555/reject\n" } ], "x-related": [ { "operationId": "applyProposal_Agents" }, { "operationId": "listProposals_Agents" }, { "operationId": "studioChat_Agents" }, { "url": "guides/agents-studio.md", "description": "Agents and Studio guide" } ] } }, "/agents/{id}/studio/request_proposal": { "post": { "operationId": "requestProposal_Agents", "x-method": "POST", "x-path": "/agents/{id}/studio/request_proposal", "x-handler": "handlers::agent_studio::request_proposal", "tags": [ "Agents" ], "summary": "Nudge the agent to emit improvement proposals", "description": "Synthesise a user message asking the agent for self-reflection\n(\"what would you propose improving about your own configuration?\")\nand forward it through the normal Studio chat path in coach mode.\nOptional `focus` narrows the request (\"focus on memory\" / \"focus on\nthe system prompt\"). The response shape is identical to\n`POST /agents/{id}/studio/chat`: the synthesised user message,\nthe agent reply, and any new proposals emitted. Auth: bearer JWT.\nNot idempotent. Useful as a UI affordance (\"Suggest improvements\"\nbutton) — saves the operator from typing the same prompt every time.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent id (UUID or slug).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "focus": { "type": [ "string", "null" ], "description": "\"what area should I look at improving?\"" } } }, "examples": { "no-focus": { "summary": "Open-ended nudge", "value": {} }, "focused": { "summary": "Focus the agent on a specific area", "value": { "focus": "memory — what should this agent persistently remember?" } } } } } }, "responses": { "200": { "description": "Reply persisted. Same shape as `POST /agents/{id}/studio/chat`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "user_message", "agent_message", "proposals" ], "properties": { "user_message": { "type": "object", "description": "One message in the authenticated user's private Studio conversation.", "required": [ "id", "thread_id", "role", "content", "had_draft", "tool_calls", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "thread_id": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "user", "agent" ] }, "content": { "type": "string" }, "thinking": { "type": [ "string", "null" ] }, "raw_llm_response": { "type": [ "string", "null" ] }, "base_version": { "type": [ "string", "null" ] }, "had_draft": { "type": "boolean" }, "tool_calls": { "description": "Arbitrary JSON value." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } }, "agent_message": { "type": "object", "description": "One message in the authenticated user's private Studio conversation.", "required": [ "id", "thread_id", "role", "content", "had_draft", "tool_calls", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "thread_id": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "user", "agent" ] }, "content": { "type": "string" }, "thinking": { "type": [ "string", "null" ] }, "raw_llm_response": { "type": [ "string", "null" ] }, "base_version": { "type": [ "string", "null" ] }, "had_draft": { "type": "boolean" }, "tool_calls": { "description": "Arbitrary JSON value." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } }, "proposals": { "type": "array", "items": { "type": "object", "required": [ "key", "thread_id", "agent_id", "user_id", "kind", "payload", "rationale", "status", "created_at" ], "properties": { "key": { "type": "string", "format": "uuid" }, "thread_id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string" }, "user_id": { "type": "string" }, "kind": { "type": "string", "enum": [ "prompt_edit", "memory_add", "memory_edit", "memory_delete", "skill_add", "skill_remove", "behaviour_change", "tool_grant_change" ] }, "payload": { "type": "object", "description": "Typed proposal payload, including its matching kind discriminator.", "additionalProperties": true }, "rationale": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "applied", "rejected" ] }, "rejection_reason": { "type": [ "string", "null" ] }, "applied_edit": { "description": "Arbitrary JSON value." }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_requestProposal_Agents", "resource_uri": "yf://agents/agents", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" \\\n -d '{\"focus\":\"memory\"}' \\\n https://agents.yieldfabric.com/agents/acme.proposer/studio/request_proposal\n" } ], "x-related": [ { "operationId": "studioChat_Agents" }, { "operationId": "listProposals_Agents" }, { "operationId": "applyProposal_Agents" }, { "operationId": "rejectProposal_Agents" }, { "url": "guides/agents-studio.md", "description": "Agents and Studio guide" } ] } }, "/agents/{id}/studio/thread": { "get": { "operationId": "getStudioThread_Agents", "x-method": "GET", "x-path": "/agents/{id}/studio/thread", "x-handler": "handlers::agent_studio::get_studio_thread", "tags": [ "Agents" ], "summary": "Retrieve the Studio conversation thread for an agent", "description": "Return this authenticated caller's private Studio thread for the visible\nagent, or `{ thread: null, messages: [] }` before the first turn. Messages are\nordered oldest first; `offset` skips oldest messages and `limit` is clamped to\n1–200 (default 100). Coach and direct turns share one conversation. Auth:\nbearer JWT. Read-only and idempotent.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent id (UUID or slug).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of messages to return. Default 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Skip the first N oldest messages.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Thread + ordered messages.", "content": { "application/json": { "schema": { "type": "object", "required": [ "messages" ], "properties": { "thread": { "oneOf": [ { "type": "object", "required": [ "id", "user_id", "agent_id", "agent_version", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string" }, "agent_id": { "type": "string" }, "agent_version": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } }, { "type": "null" } ] }, "messages": { "type": "array", "items": { "type": "object", "description": "One message in the authenticated user's private Studio conversation.", "required": [ "id", "thread_id", "role", "content", "had_draft", "tool_calls", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "thread_id": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "user", "agent" ] }, "content": { "type": "string" }, "thinking": { "type": [ "string", "null" ] }, "raw_llm_response": { "type": [ "string", "null" ] }, "base_version": { "type": [ "string", "null" ] }, "had_draft": { "type": "boolean" }, "tool_calls": { "description": "Arbitrary JSON value." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } }, "examples": { "empty": { "summary": "Fresh agent, no thread yet", "value": { "thread": null, "messages": [] } }, "with-history": { "summary": "Existing thread with two messages", "value": { "thread": { "id": "22222222-3333-4444-5555-666666666666", "user_id": "11111111-2222-4333-8444-555555555555", "agent_id": "acme.proposer", "agent_version": "1.4.0", "created_at": "2027-05-16T09:00:00Z", "updated_at": "2027-05-17T14:00:04Z" }, "messages": [ { "id": "aaaa1111-bbbb-2222-cccc-333333333333", "thread_id": "22222222-3333-4444-5555-666666666666", "role": "user", "content": "Your system prompt feels too verbose.", "created_at": "2027-05-17T14:00:00Z" }, { "id": "bbbb2222-cccc-3333-dddd-444444444444", "thread_id": "22222222-3333-4444-5555-666666666666", "role": "agent", "content": "I see what you mean...", "created_at": "2027-05-17T14:00:04Z" } ] } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getStudioThread_Agents", "resource_uri": "yf://agents/agents", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/agents/acme.proposer/studio/thread?limit=50\"" } ], "x-related": [ { "operationId": "studioChat_Agents" }, { "operationId": "listProposals_Agents" }, { "url": "guides/agents-studio.md", "description": "Agents and Studio guide" } ] } }, "/agents/{id}/versions": { "get": { "operationId": "getAgentVersions_Agents", "x-method": "GET", "x-path": "/agents/{id}/versions", "x-handler": "handlers::agent_registry::get_agent_versions", "tags": [ "Agents" ], "summary": "List all versions of an agent (newest first)", "description": "Returns only versions visible to the authenticated caller.\nReturn every persisted version of the agent identified by `id`, in\nnewest-first order. Retired versions are included so the Studio version\npicker can show full history. Use `GET /agents/{id}` to fetch only the\nlatest non-retired version. Auth: bearer JWT. Idempotent.\nReturns 404 when no version of the agent has ever been created.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent id (UUID or slug).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of `AgentSpec` rows, one per persisted version.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "The unified agent definition. Every agent — pipeline agents, user\nspecialists, team-construction agents — is one of these.\n", "required": [ "id", "version", "display_name", "role", "goal", "source", "system_prompt" ], "properties": { "id": { "type": "string" }, "version": { "type": "string" }, "display_name": { "type": "string" }, "role": { "type": "string" }, "goal": { "type": "string" }, "source": { "type": "string", "enum": [ "seed", "user", "team_construction" ] }, "system_prompt": { "type": "string" }, "skills": { "type": "array", "items": { "type": "object", "required": [ "name", "prompt_addendum" ], "properties": { "name": { "type": "string" }, "prompt_addendum": { "type": "string" }, "tool_grants": { "description": "Arbitrary JSON value." } } } }, "model": { "type": "object", "description": "Per-agent model routing. The `ProviderRegistry` resolves this to a\nconcrete LLMProvider at runtime.\n", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "default", "tagged", "exact" ] }, "tag": { "type": [ "string", "null" ], "description": "Used when kind=tagged." }, "provider": { "type": [ "string", "null" ], "description": "Used when kind=exact." }, "model": { "type": [ "string", "null" ], "description": "Used when kind=exact." } } }, "reasoning_effort": { "type": "string", "enum": [ "low", "medium", "high", "max" ] }, "max_tokens": { "type": "integer", "default": 4000 }, "tools": { "description": "Arbitrary JSON value." }, "context_builder": { "type": "string", "default": "summarised" }, "output_parser": { "type": "string", "default": "tool_calls" }, "memory_enabled": { "type": "boolean", "default": false }, "created_by": { "type": [ "string", "null" ] }, "economy_id": { "type": [ "string", "null" ], "format": "uuid" }, "working_group_id": { "type": [ "string", "null" ], "format": "uuid" }, "user_id": { "type": [ "string", "null" ] }, "pinned_kg_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "personality": { "type": [ "string", "null" ] }, "expertise": { "type": "array", "items": { "type": "string" } }, "focus": { "type": [ "string", "null" ] }, "anti_focus": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": { "description": "Arbitrary JSON value." } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getAgentVersions_Agents", "resource_uri": "yf://agents/agents", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/agents/yieldfabric.proposer/versions" } ], "x-related": [ { "operationId": "getAgent_Agents" }, { "operationId": "retireAgentVersion_Agents" }, { "operationId": "createAgent_Agents" }, { "url": "guides/agents-studio.md", "description": "Agents and Studio guide" } ] } }, "/agents/{id}/versions/{version}": { "delete": { "operationId": "retireAgentVersion_Agents", "x-method": "DELETE", "x-path": "/agents/{id}/versions/{version}", "x-handler": "handlers::agent_registry::retire_agent_version", "tags": [ "Agents" ], "summary": "Soft-retire a specific version of an agent", "description": "Mark the named `(id, version)` as retired. Retired versions remain in the\nregistry and are still returned by `GET /agents/{id}/versions` for audit\nhistory, but they are hidden from `GET /agents`, `GET /agents/{id}`, and\npipeline composition. Auth: bearer JWT. Not idempotent — retiring an\nalready-retired version is still treated as a no-op success. Returns\n`204 No Content` on success and `404` when the version doesn't exist.\nUse this when you publish a buggy version: bump and publish a fixed\none, then retire the bad one to take it out of rotation.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent id (UUID or slug).", "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "description": "Version string of the agent to retire (matches `AgentSpec.version`).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Version retired (or already retired)." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_retireAgentVersion_Agents", "resource_uri": "yf://agents/agents", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X DELETE -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/agents/acme.research-analyst/versions/1.0.0" } ], "x-related": [ { "operationId": "getAgentVersions_Agents" }, { "operationId": "createAgent_Agents" }, { "operationId": "getAgent_Agents" }, { "url": "guides/agents-studio.md", "description": "Agents and Studio guide" } ] } }, "/api/authoring/bootstrap": { "post": { "operationId": "handleAuthoringBootstrap_Misc", "x-method": "POST", "x-path": "/api/authoring/bootstrap", "x-handler": "handlers::authoring::handle_authoring_bootstrap", "tags": [ "Authoring" ], "summary": "Prose → LLM → YAML → import pipeline", "description": "End-to-end prose-to-KG bootstrap: the supplied free-text prompt is\nshipped to the LLM, the LLM emits a YAML manifest, the manifest is\nparsed, and a fresh persistent KG is created. One repair retry is\nattempted on parse / validation failure. Returns the new `kg_id`.\nAuth: bearer JWT.\n", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "`service::handlers::authoring::bootstrap::BootstrapRequest`.\nOpaque (authoring submodule).\n", "additionalProperties": true }, "examples": { "prose": { "summary": "Bootstrap from a paragraph", "value": { "prompt": "Model a simple credit deal schema with parties, instruments, and waterfall." } } } } } }, "responses": { "201": { "description": "New KG created.", "content": { "application/json": { "schema": { "type": "object", "description": "Bootstrap result. Opaque (authoring submodule).", "additionalProperties": true } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_handleAuthoringBootstrap_Misc", "resource_uri": "yf://agents/misc", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" -d '{\"prompt\":\"...\"}' https://agents.yieldfabric.com/api/authoring/bootstrap" } ], "x-related": [ { "operationId": "handleAuthoringImport_Misc", "relation": "alternative" }, { "operationId": "handleAuthoringElicit_Misc", "relation": "sibling" } ] } }, "/api/authoring/diff": { "post": { "operationId": "handleAuthoringDiff_Misc", "x-method": "POST", "x-path": "/api/authoring/diff", "x-handler": "handlers::authoring::handle_authoring_diff", "tags": [ "Authoring" ], "summary": "Structural delta between two KGs", "description": "Returns the per-artifact added / removed / modified delta between\ntwo KGs. Read-only on both sides. Useful for previewing what an\napply batch did before promoting the draft. Auth: bearer JWT.\n", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "`service::handlers::authoring::diff::DiffRequest`. Opaque\n(authoring submodule).\n", "additionalProperties": true }, "examples": { "compare": { "summary": "Diff two KGs", "value": { "base_kg_id": "8c7e1a32-1111-4e44-b9d1-aaaaaaaaaaaa", "target_kg_id": "8c7e1a32-2222-4e44-b9d1-bbbbbbbbbbbb" } } } } } }, "responses": { "200": { "description": "Structural delta.", "content": { "application/json": { "schema": { "type": "object", "description": "Diff result. Opaque (authoring submodule).", "additionalProperties": true } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_handleAuthoringDiff_Misc", "resource_uri": "yf://agents/misc", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" -d \"{}\" https://agents.yieldfabric.com/api/authoring/diff" } ], "x-related": [ { "operationId": "handleAuthoringApply_Misc", "relation": "sibling" } ] } }, "/api/authoring/draft/apply": { "post": { "operationId": "handleAuthoringApply_Misc", "x-method": "POST", "x-path": "/api/authoring/draft/apply", "x-handler": "handlers::authoring::handle_authoring_apply", "tags": [ "Authoring" ], "summary": "Apply a batch of FrameMutations to a draft KG", "description": "Applies an ordered batch of `FrameMutation`s to the supplied draft\nKG. Sequential and fail-fast — the first failing mutation aborts\nthe rest. Post-apply validation surfaces structural issues without\nrolling back the mutations that succeeded. Auth: bearer JWT.\n", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "`service::handlers::authoring::mutate::ApplyRequest`. Opaque\n(authoring submodule).\n", "additionalProperties": true }, "examples": { "minimal": { "summary": "One mutation", "value": { "kg_id": "8c7e1a32-1111-4e44-b9d1-aaaaaaaaaaaa", "mutations": [ { "op": "addNode", "node": { "id": "foo", "type": "entity" } } ] } } } } } }, "responses": { "200": { "description": "Apply result.", "content": { "application/json": { "schema": { "type": "object", "description": "Apply result. Opaque (authoring submodule).", "additionalProperties": true } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_handleAuthoringApply_Misc", "resource_uri": "yf://agents/misc", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" -d \"{}\" https://agents.yieldfabric.com/api/authoring/draft/apply" } ], "x-related": [ { "operationId": "handleAuthoringDiff_Misc", "relation": "sibling" }, { "operationId": "handleAuthoringImport_Misc", "relation": "precondition" } ] } }, "/api/authoring/elicit": { "post": { "operationId": "handleAuthoringElicit_Misc", "x-method": "POST", "x-path": "/api/authoring/elicit", "x-handler": "handlers::authoring::handle_authoring_elicit", "tags": [ "Authoring" ], "summary": "Conversational schema authoring (LLM-driven mutation suggestions)", "description": "Conversational schema editor. Reads the current schema state and\nships it to the LLM together with the conversation history. Parses\nany inline `[[mutation: ...]]` suggestions in the reply into typed\n`FrameMutation` objects the frontend can accept (via\n`handleAuthoringApply_Misc`) or dismiss. Auth: bearer JWT.\n", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "`service::handlers::authoring::elicit::ElicitRequest`. Opaque\n(authoring submodule).\n", "additionalProperties": true }, "examples": { "ask": { "summary": "One-turn elicitation", "value": { "kg_id": "8c7e1a32-1111-4e44-b9d1-aaaaaaaaaaaa", "user_message": "Add a sponsor entity with a registration field." } } } } } }, "responses": { "200": { "description": "LLM reply + parsed mutation suggestions.", "content": { "application/json": { "schema": { "type": "object", "description": "Elicit result. Opaque (authoring submodule).", "additionalProperties": true } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_handleAuthoringElicit_Misc", "resource_uri": "yf://agents/misc", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" -d \"{}\" https://agents.yieldfabric.com/api/authoring/elicit" } ], "x-related": [ { "operationId": "handleAuthoringApply_Misc", "relation": "next-step" }, { "operationId": "handleAuthoringBootstrap_Misc", "relation": "alternative" } ] } }, "/api/authoring/examples": { "get": { "operationId": "handleExamplesList_Misc", "x-method": "GET", "x-path": "/api/authoring/examples", "x-handler": "handlers::authoring::handle_examples_list", "tags": [ "Authoring" ], "summary": "List bundled fork-able example manifests", "description": "Returns the catalog of bundled authoring examples — id, title,\nshort description — for the picker UI. Auth: bearer JWT.\n", "parameters": [], "responses": { "200": { "description": "Examples catalog.", "content": { "application/json": { "schema": { "type": "object", "description": "Authoring examples catalog —\n`service::handlers::authoring::examples::ListResponse`. Opaque.\n", "additionalProperties": true } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_handleExamplesList_Misc", "resource_uri": "yf://agents/misc", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/api/authoring/examples" } ], "x-related": [ { "operationId": "handleExamplesFork_Misc", "relation": "child" } ] } }, "/api/authoring/examples/{id}/fork": { "post": { "operationId": "handleExamplesFork_Misc", "x-method": "POST", "x-path": "/api/authoring/examples/{id}/fork", "x-handler": "handlers::authoring::handle_examples_fork", "tags": [ "Authoring" ], "summary": "Fork a bundled example into a fresh persistent KG", "description": "Materialises a bundled example into a fresh persistent KG owned by\nthe caller. Response shape mirrors `handleAuthoringImport_Misc`\n(carries the new `kg_id`). Auth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Bundled example id (slug).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "Optional naming override for the forked example. Opaque (authoring\nsubmodule).\n", "additionalProperties": true }, "examples": { "empty": { "summary": "No body required", "value": {} } } } } }, "responses": { "201": { "description": "Forked example; new `kg_id` returned.", "content": { "application/json": { "schema": { "type": "object", "description": "Fork result. Opaque (authoring submodule).", "additionalProperties": true } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_handleExamplesFork_Misc", "resource_uri": "yf://agents/misc", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/api/authoring/examples/demo/fork" } ], "x-related": [ { "operationId": "handleExamplesList_Misc", "relation": "prerequisite" }, { "operationId": "handleAuthoringImport_Misc", "relation": "alternative" } ] } }, "/api/authoring/export": { "post": { "operationId": "handleAuthoringExport_Misc", "x-method": "POST", "x-path": "/api/authoring/export", "x-handler": "handlers::authoring::handle_authoring_export", "tags": [ "Authoring" ], "summary": "Export a schema-bearing KG as YAML", "description": "Authoring-tool export. Read-only on the supplied `kg_id`. Returns\nthe manifest YAML the author can download and swap for the\noperator's manifest at restart. Auth: bearer JWT.\n", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "`service::handlers::authoring::export::ExportRequest`. Opaque\n(authoring submodule).\n", "additionalProperties": true }, "examples": { "kg-export": { "summary": "Export a single KG", "value": { "kg_id": "8c7e1a32-1111-4e44-b9d1-aaaaaaaaaaaa" } } } } } }, "responses": { "200": { "description": "YAML body.", "content": { "application/json": { "schema": { "type": "object", "description": "Export result. Opaque (authoring submodule).", "additionalProperties": true } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_handleAuthoringExport_Misc", "resource_uri": "yf://agents/misc", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" -d '{\"kg_id\":\"\"}' https://agents.yieldfabric.com/api/authoring/export" } ], "x-related": [ { "operationId": "handleAuthoringImport_Misc", "relation": "sibling" }, { "operationId": "handleAuthoringGraph_Misc", "relation": "sibling" } ] } }, "/api/authoring/graph": { "post": { "operationId": "handleAuthoringGraph_Misc", "x-method": "POST", "x-path": "/api/authoring/graph", "x-handler": "handlers::authoring::handle_authoring_graph", "tags": [ "Authoring" ], "summary": "Schema graph view (nodes + edges) for visualization", "description": "Returns the schema graph for the supplied `kg_id` — nodes and edges,\nsuitable for a visualization renderer. Read-only. Auth: bearer JWT.\n", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "`service::handlers::authoring::graph::GraphRequest`. Opaque\n(authoring submodule).\n", "additionalProperties": true }, "examples": { "kg": { "summary": "Graph for one KG", "value": { "kg_id": "8c7e1a32-1111-4e44-b9d1-aaaaaaaaaaaa" } } } } } }, "responses": { "200": { "description": "Nodes + edges.", "content": { "application/json": { "schema": { "type": "object", "description": "Graph view. Opaque (authoring submodule).", "additionalProperties": true } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_handleAuthoringGraph_Misc", "resource_uri": "yf://agents/misc", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" -d '{\"kg_id\":\"\"}' https://agents.yieldfabric.com/api/authoring/graph" } ], "x-related": [ { "operationId": "handleAuthoringLexicon_Misc", "relation": "sibling" }, { "operationId": "handleAuthoringApply_Misc", "relation": "sibling" } ] } }, "/api/authoring/import": { "post": { "operationId": "handleAuthoringImport_Misc", "x-method": "POST", "x-path": "/api/authoring/import", "x-handler": "handlers::authoring::handle_authoring_import", "tags": [ "Authoring" ], "summary": "Import a YAML manifest into a fresh persistent KG", "description": "Authoring-tool import. Parses the supplied YAML manifest into a fresh\npersistent KG. The returned `kg_id` is the handle the author then\nuses to mutate (`/api/authoring/draft/apply`), preview\n(`/api/authoring/playground/compose`), or export\n(`/api/authoring/export`) the schema. Auth: bearer JWT.\n", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "`service::handlers::authoring::import::ImportRequest`. Opaque\n(authoring submodule).\n", "additionalProperties": true }, "examples": { "manifest": { "summary": "Import a manifest body", "value": { "manifest_yaml": "name: example\\nschema: []" } } } } } }, "responses": { "201": { "description": "New KG created.", "content": { "application/json": { "schema": { "type": "object", "description": "Import result. Opaque (authoring submodule).", "additionalProperties": true } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_handleAuthoringImport_Misc", "resource_uri": "yf://agents/misc", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" -d \"{}\" https://agents.yieldfabric.com/api/authoring/import" } ], "x-related": [ { "operationId": "handleAuthoringExport_Misc", "relation": "sibling" }, { "operationId": "handleAuthoringApply_Misc", "relation": "next-step" }, { "operationId": "handleAuthoringGraph_Misc", "relation": "sibling" } ] } }, "/api/authoring/lexicon/{kg_id}": { "get": { "operationId": "handleAuthoringLexicon_Misc", "x-method": "GET", "x-path": "/api/authoring/lexicon/{kg_id}", "x-handler": "handlers::authoring::handle_authoring_lexicon", "tags": [ "Authoring" ], "summary": "Verb + clause lexicon palette for the Ideator", "description": "Returns the verb / clause lexicon for the supplied KG — the\nautocomplete palette the Ideator UI offers as the author types.\nRead-only. Auth: bearer JWT.\n", "parameters": [ { "name": "kg_id", "in": "path", "required": true, "description": "Knowledge-graph id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Lexicon.", "content": { "application/json": { "schema": { "type": "object", "description": "Authoring lexicon snapshot for a KG — wraps\n`yieldfabric-economy-schema::ExtractionLexicon`. Opaque (economy-schema\ntypes live outside this surface).\n", "additionalProperties": true } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_handleAuthoringLexicon_Misc", "resource_uri": "yf://agents/misc", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/api/authoring/lexicon/{kg_id}" } ], "x-related": [ { "operationId": "handleAuthoringGraph_Misc", "relation": "sibling" } ] } }, "/api/authoring/playground/compose": { "post": { "operationId": "handlePlaygroundCompose_Misc", "x-method": "POST", "x-path": "/api/authoring/playground/compose", "x-handler": "handlers::authoring::handle_playground_compose", "tags": [ "Authoring" ], "summary": "Run composition against an arbitrary YAML manifest + sample chat", "description": "Authoring-tool entry point. Allocates a TRANSIENT KG, materializes\nschema frames from the supplied YAML manifest, extracts instance\nframes from the supplied sample chat, runs composition, and drops\nthe KG before returning. No shared-state contamination — every\nrequest is isolated. Auth: bearer JWT.\n", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Authoring playground compose request —\n`service::handlers::authoring::playground::ComposeRequest`.\nOpaque: nested `spec` + `inputs` payloads are economy-schema\ntypes that evolve outside this surface.\n", "additionalProperties": true, "properties": { "spec": { "description": "Arbitrary JSON value." }, "inputs": { "description": "Arbitrary JSON value." } } }, "examples": { "minimal": { "summary": "Manifest + chat", "value": { "manifest_yaml": "name: example\\nschema: []", "chat": { "messages": [] } } } } } } }, "responses": { "200": { "description": "Composition result.", "content": { "application/json": { "schema": { "type": "object", "description": "Compose result — rendered output + diagnostics. Opaque (authoring\nsubmodule).\n", "additionalProperties": true } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_handlePlaygroundCompose_Misc", "resource_uri": "yf://agents/misc", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" -d \"{}\" https://agents.yieldfabric.com/api/authoring/playground/compose" } ], "x-related": [ { "operationId": "handleAuthoringImport_Misc", "relation": "alternative" }, { "operationId": "handleAuthoringElicit_Misc", "relation": "sibling" } ] } }, "/api/catalog/invalidate": { "post": { "operationId": "handleCatalogInvalidate_Catalog", "x-method": "POST", "x-path": "/api/catalog/invalidate", "x-handler": "crate::analyze::handler::handle_catalog_invalidate", "tags": [ "Economies & Usage" ], "summary": "Force-refresh the active payment mode's asset catalog", "description": "Selects a direct payments instance from the authenticated caller's JWT\n`default_chain_id`, then forces an immediate refresh of that route's\nin-memory asset catalog. Test and Live catalogs are independent. Useful\nafter publishing an asset definition when you cannot wait for the next\nstaleness-driven refresh tick.\n\n**Auth**: bearer JWT (any authenticated caller). No per-resource\nauthorization — this is a service-level cache refresh.\n\nMissing, blank, or unmapped user chains fail closed; the operation never\nfalls back to another mode or the federation gateway.\n\n**Idempotency**: idempotent — every call rebuilds the selected catalog from\nits direct `/graphql` endpoint and returns the resulting count.\n\n**Side effects**: rebuilds the in-process cache; subsequent reads see the\nfresh data. Does NOT propagate across replicas — call once per running\nagents-service instance.\n", "responses": { "200": { "description": "Catalog refreshed successfully; body returns the new entry count.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "entries" ], "properties": { "status": { "type": "string", "enum": [ "refreshed" ] }, "entries": { "type": "integer", "minimum": 0 } } }, "examples": { "ok": { "summary": "95 catalog entries after refresh", "value": { "status": "refreshed", "entries": 95 } } } } } }, "400": { "description": "JWT payment mode is missing, blank, or not configured." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "502": { "description": "The selected payments instance could not refresh the catalog." } }, "x-mcp": { "tool_name": "yieldfabric_agents_handleCatalogInvalidate_Catalog", "resource_uri": "yf://agents/catalog", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/api/catalog/invalidate" } ], "x-related": [ { "operationId": "register_Economies", "relation": "alternative" }, { "operationId": "handleAnalyze_Conversation", "relation": "consumer" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/conversation/analyze": { "post": { "operationId": "handleAnalyze_Conversation", "x-method": "POST", "x-path": "/api/conversation/analyze", "x-handler": "crate::analyze::handler::handle_analyze", "tags": [ "Conversation" ], "summary": "Analyze a working-group thread into a DealSnapshot and ranked candidate pipelines.", "description": "Runs the two-box analyze pipeline over a thread's messages. Box 1 (extraction) walks\nthe transcript with a manifest-constrained LLM schema and emits a `DealSnapshot`\n(concepts, terms, parties, agreement state). Box 2 (composition) ranks the manifest's\npattern catalog against the snapshot and returns Ready / Partial / Blocked\n`CandidatePipeline`s the orchestrator can either propose immediately or hand to\n`/api/conversation/analyze/resolve` for user-supplied gap filling.\n\nInputs: `thread_id` + `working_group_id`; optional `scope.from_message_id` to start\nmid-thread, `include_documents`, and `user_hints`. Caller must be a member of the\ntarget working group with at least `ViewThreads` permission — anonymous access is\nrejected with 401, non-members with 403.\n\nSide-effects: persists a fresh deal-scoped KG row keyed on `(thread_id, working_group_id)`\nthe first time it sees this pair; subsequent calls reuse the cached snapshot when the\nmessage-set hash matches, so re-invoking with no new messages is cheap and idempotent.\nAuto-routes any caller-tracked notebook entities mentioned in the transcript to their\nindividual profilers and reports them under `auto_routed` / `possible_mentions`.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "x-entity-id", "in": "header", "required": false, "description": "Caller entity id. Falls back to JWT subject when absent.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "working_group_id", "thread_id" ], "description": "Body for `POST /api/conversation/analyze`. Triggers Box 1 (extraction)\nand Box 2 (composition) over the messages in the named thread.\n`options` is the catch-all for analyzer knobs (`force_refresh`,\n`pattern_filter`, etc.) — kept as opaque JSON.\n", "properties": { "working_group_id": { "type": "string", "format": "uuid" }, "thread_id": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "string" } ] }, "deal_id": { "type": [ "string", "null" ], "format": "uuid" }, "options": { "description": "Arbitrary JSON value." } } }, "examples": { "minimal": { "summary": "Analyze a thread", "value": { "thread_id": "3f2a1c5e-7b9d-4c3a-8f1e-2d6b0a9c4e5f", "working_group_id": "7a9f1b2c-4e6d-4c2b-9f3a-5b8c1d0e2f3a" } }, "scoped": { "summary": "Analyze from a specific message onwards", "value": { "thread_id": "3f2a1c5e-7b9d-4c3a-8f1e-2d6b0a9c4e5f", "working_group_id": "7a9f1b2c-4e6d-4c2b-9f3a-5b8c1d0e2f3a", "scope": { "from_message_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" }, "include_documents": true } } } } } }, "responses": { "200": { "description": "AnalyzeResponse with snapshot + candidate pipelines + mention hits.", "content": { "application/json": { "schema": { "type": "object", "required": [ "snapshot", "candidate_pipelines", "deals" ], "properties": { "snapshot": { "description": "Arbitrary JSON value." }, "candidate_pipelines": { "type": "array", "items": { "description": "Arbitrary JSON value." }, "description": "Flat list of CandidatePipeline across every deal." }, "deals": { "type": "array", "items": { "description": "Arbitrary JSON value." }, "description": "Grouped-by-deal view (DealGroup envelopes)." }, "warnings": { "type": "array", "items": { "type": "string" } }, "auto_routed": { "type": "array", "items": { "type": "object", "required": [ "entity_id", "label", "score" ], "properties": { "entity_id": { "type": "string" }, "label": { "type": "string" }, "score": { "type": "integer", "minimum": 0 } } }, "description": "Notebook entities mentioned in the transcript and auto-routed to\ntheir individual profilers.\n" }, "possible_mentions": { "type": "array", "items": { "type": "object", "required": [ "entity_id", "label", "score" ], "properties": { "entity_id": { "type": "string" }, "label": { "type": "string" }, "score": { "type": "integer", "minimum": 0 } } }, "description": "Weak matches that warrant a user confirmation before routing." } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_handleAnalyze_Conversation", "resource_uri": "yf://agents/conversation", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"thread_id\":\"3f2a1c5e-7b9d-4c3a-8f1e-2d6b0a9c4e5f\",\"working_group_id\":\"7a9f1b2c-4e6d-4c2b-9f3a-5b8c1d0e2f3a\"}' \\\n https://agents.yieldfabric.com/api/conversation/analyze\n" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx\n\nresp = httpx.post(\n \"https://agents.yieldfabric.com/api/conversation/analyze\",\n headers={\"Authorization\": f\"Bearer {jwt}\"},\n json={\n \"thread_id\": \"3f2a1c5e-7b9d-4c3a-8f1e-2d6b0a9c4e5f\",\n \"working_group_id\": \"7a9f1b2c-4e6d-4c2b-9f3a-5b8c1d0e2f3a\",\n \"include_documents\": True,\n },\n timeout=60.0,\n)\nresp.raise_for_status()\npayload = resp.json()\nfor deal in payload[\"deals\"]:\n for candidate in deal[\"candidate_pipelines\"]:\n print(candidate[\"pattern_id\"], candidate[\"status\"])\n" } ], "x-related": [ { "operationId": "handleResolvePartial_Conversation", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/conversation/analyze/resolve": { "post": { "operationId": "handleResolvePartial_Conversation", "x-method": "POST", "x-path": "/api/conversation/analyze/resolve", "x-handler": "crate::analyze::handler::handle_resolve_partial", "tags": [ "Conversation" ], "summary": "Promote a Partial CandidatePipeline to Ready by supplying values for its gaps.", "description": "Background: `POST /api/conversation/analyze` can return a\n`CandidatePipeline::Partial` when the conversation has all the right shape but one\nor more roles are unresolved (`NeedsConfirmation` term, `MissingRole`,\n`UnresolvedParty`). This endpoint lets the UI close those gaps in one shot rather\nthan forcing more back-and-forth in chat.\n\nThe handler looks up the cached snapshot for the thread, patches each resolution\ninto the snapshot (term values flip to Accepted; party_role gaps resolve to a\nspecific entity), re-runs composition, and returns the re-composed candidate for\nthe requested `pattern_id`. If the patched candidate is still not Ready, returns\n400 — the user supplied values didn't close every gap.\n\nThe intent's audit lineage will tag each patched binding as a `user_override` so\nvalues sourced from explicit resolution are distinguishable from chat-extracted\nones downstream.\n\nAuth: bearer JWT; caller must be a member of `working_group_id` with at least\n`ViewThreads` permission. Read-only on the substrate; mutates the snapshot cache.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "working_group_id", "pattern_id" ], "description": "Body for `POST /api/conversation/analyze/resolve` — promote a Partial\ncandidate to Ready by supplying values for its gaps. See\n`analyze::resolve_partial::ResolvePartialRequest`.\n", "properties": { "working_group_id": { "type": "string", "format": "uuid" }, "pattern_id": { "type": "string" }, "role_assignments": { "type": "object", "description": "role_name → assignment object. Each assignment carries either a\nscalar `value` or an `entity_id` reference; extra hint fields\nare tolerated per role.\n", "additionalProperties": { "type": "object", "additionalProperties": true, "properties": { "value": { "description": "Arbitrary JSON value." }, "entity_id": { "type": [ "string", "null" ] } } } } } }, "examples": { "term-value": { "summary": "Resolve a NeedsConfirmation term", "value": { "working_group_id": "7a9f1b2c-4e6d-4c2b-9f3a-5b8c1d0e2f3a", "thread_id": "3f2a1c5e-7b9d-4c3a-8f1e-2d6b0a9c4e5f", "pattern_id": "secured_loan_v1", "resolutions": { "pricing": { "value": 15 } } } }, "party": { "summary": "Resolve an UnresolvedParty", "value": { "working_group_id": "7a9f1b2c-4e6d-4c2b-9f3a-5b8c1d0e2f3a", "thread_id": "3f2a1c5e-7b9d-4c3a-8f1e-2d6b0a9c4e5f", "pattern_id": "secured_loan_v1", "resolutions": { "borrower": { "entity_id": "9c1e2f3a-4b5c-6d7e-8f9a-0b1c2d3e4f5a", "display_name": "Acme Capital" } } } } } } } }, "responses": { "200": { "description": "Re-composed Ready CandidatePipeline.", "content": { "application/json": { "schema": { "description": "Arbitrary JSON value." } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_handleResolvePartial_Conversation", "resource_uri": "yf://agents/conversation", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"working_group_id\":\"7a9f...\",\"thread_id\":\"3f2a...\",\"pattern_id\":\"secured_loan_v1\",\"resolutions\":{\"pricing\":{\"value\":15}}}' \\\n https://agents.yieldfabric.com/api/conversation/analyze/resolve\n" } ], "x-related": [ { "operationId": "handleAnalyze_Conversation", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/crm/contacts": { "post": { "operationId": "createContact_Crm", "x-method": "POST", "x-path": "/api/crm/contacts", "x-handler": "handlers::crm::create_contact", "tags": [ "CRM" ], "summary": "Create a contact in the observer's notebook KG (CRM Person convenience wrapper).", "description": "Creates a `Person` entity frame inside the caller's personal notebook KG. CRM\ncontacts are kind-pinned wrappers over the generic notebook entity surface — the\nsame row is reachable through `/api/notebook/entities/person/{id}`.\n\nInputs come via `ContactInput`: identity fields (display_name, given_name,\nfamily_name, email, phone, platform_entity_id), tags, `no_auto_link`. Side-effects:\nlazy-mints the observer's personal workspace + notebook KG if either is missing;\npersists a new `entity` frame at `lifecycle=typed`, `graph_layer=user`,\n`concept_type=person`.\n\nAuth: bearer JWT — the auth extractor pulls the observer entity id from headers\nand rejects anonymous calls. The observer becomes the frame's `created_by`.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Partial update — all fields optional. Used for create + update.", "properties": { "label": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "aliases": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "linkedin_url": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] }, "tags": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "platform_entity_id": { "type": [ "string", "null" ] }, "no_auto_link": { "type": [ "boolean", "null" ] } } }, "examples": { "minimal": { "summary": "Just a display name", "value": { "display_name": "Alex Lender" } }, "full": { "summary": "With identity + tags", "value": { "display_name": "Alex Lender", "given_name": "Alex", "family_name": "Lender", "email": "alex@acme.fund", "tags": [ "investor", "warm" ], "platform_entity_id": "9c1e2f3a-4b5c-6d7e-8f9a-0b1c2d3e4f5a" } } } } } }, "responses": { "200": { "description": "The created contact frame.", "content": { "application/json": { "schema": { "type": "object", "description": "Rendered contact projection — backed by an `entity` frame of\n`concept_type='person'` in the observer's notebook KG.\n", "required": [ "id", "label", "status", "archived", "created_at" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "aliases": { "type": "array", "items": { "type": "string" } }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "linkedin_url": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "external", "invited", "on_platform", "platform_user_removed" ] }, "platform_entity_id": { "type": [ "string", "null" ] }, "no_auto_link": { "type": "boolean", "default": false }, "archived": { "type": "boolean", "default": false }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_createContact_Crm", "resource_uri": "yf://agents/crm", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"display_name\":\"Alex Lender\",\"email\":\"alex@acme.fund\",\"tags\":[\"investor\"]}' \\\n https://agents.yieldfabric.com/api/crm/contacts\n" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx\n\nresp = httpx.post(\n \"https://agents.yieldfabric.com/api/crm/contacts\",\n headers={\"Authorization\": f\"Bearer {jwt}\"},\n json={\n \"display_name\": \"Alex Lender\",\n \"email\": \"alex@acme.fund\",\n \"tags\": [\"investor\"],\n },\n)\nresp.raise_for_status()\ncontact = resp.json()\nprint(contact[\"id\"], contact[\"display_name\"])\n" } ], "x-related": [ { "operationId": "listContacts_Crm", "relation": "sibling" }, { "operationId": "getContact_Crm", "relation": "sibling" }, { "operationId": "updateContact_Crm", "relation": "sibling" }, { "operationId": "archiveContact_Crm", "relation": "sibling" }, { "operationId": "createEntity_Notebook", "relation": "alternate" }, { "guide": "conversation", "relation": "concept" } ] }, "get": { "operationId": "listContacts_Crm", "x-method": "GET", "x-path": "/api/crm/contacts", "x-handler": "handlers::crm::list_contacts", "tags": [ "CRM" ], "summary": "List the observer's contacts (CRM Person convenience wrapper).", "description": "Lists Person entities in the observer's notebook KG. Optional query filters narrow\nby free-text search (label + alias substring), tag, or status; `include_archived`\ndefaults to false. `workspace_id` opts in to a team workspace's notebook KG —\nmembership-checked; non-members get a 403 and members of a workspace whose KG\nhasn't been minted yet get an empty array (no lazy-mint on read).\n\nAuth: bearer JWT. Read-only.\n", "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Free-text search over label and aliases.", "schema": { "type": "string" } }, { "name": "tag", "in": "query", "required": false, "description": "Filter to contacts carrying this tag.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Lifecycle status string (e.g. active, archived).", "schema": { "type": "string" } }, { "name": "include_archived", "in": "query", "required": false, "description": "Include archived contacts.", "schema": { "type": "boolean", "default": false } }, { "name": "workspace_id", "in": "query", "required": false, "description": "Optional team-workspace scope.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Array of contacts under `{ contacts: [...] }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "contacts" ], "properties": { "contacts": { "type": "array", "items": { "type": "object", "description": "Rendered contact projection — backed by an `entity` frame of\n`concept_type='person'` in the observer's notebook KG.\n", "required": [ "id", "label", "status", "archived", "created_at" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "aliases": { "type": "array", "items": { "type": "string" } }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "linkedin_url": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "external", "invited", "on_platform", "platform_user_removed" ] }, "platform_entity_id": { "type": [ "string", "null" ] }, "no_auto_link": { "type": "boolean", "default": false }, "archived": { "type": "boolean", "default": false }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listContacts_Crm", "resource_uri": "yf://agents/crm", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -G \\\n -H \"Authorization: Bearer $JWT\" \\\n --data-urlencode \"search=alex\" \\\n https://agents.yieldfabric.com/api/crm/contacts\n" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx\n\nresp = httpx.get(\n \"https://agents.yieldfabric.com/api/crm/contacts\",\n headers={\"Authorization\": f\"Bearer {jwt}\"},\n params={\"search\": \"alex\", \"include_archived\": False},\n)\nresp.raise_for_status()\nfor contact in resp.json()[\"contacts\"]:\n print(contact[\"id\"], contact[\"display_name\"])\n" } ], "x-related": [ { "operationId": "createContact_Crm", "relation": "sibling" }, { "operationId": "getContact_Crm", "relation": "sibling" }, { "operationId": "listEntities_Notebook", "relation": "alternate" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/crm/contacts/{id}": { "get": { "operationId": "getContact_Crm", "x-method": "GET", "x-path": "/api/crm/contacts/{id}", "x-handler": "handlers::crm::get_contact", "tags": [ "CRM" ], "summary": "Get a contact + their rendered observation profile.", "description": "Returns the Person entity frame and the temporally-filtered profile rendered from\nevery accepted observation about them across the observer's accessible KGs. The\nprofile walks the slot edges from SpeechActs whose target resolves to this\ncontact, applies the optional `as_of` cutoff (observations with `valid_to` before\nthis drop out), and respects `classification_ceiling` (Phase 5.1 — claims above\nthe level drop out).\n\n`workspace_id` opts in to a team workspace's notebook KG — membership-checked.\n404 when the contact frame doesn't exist; 404 (not 200 with empty) when scoped to\na workspace whose KG hasn't been minted yet.\n\nAuth: bearer JWT. Read-only.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Contact frame id (typically a `person:` prefixed string).", "schema": { "type": "string" } }, { "name": "as_of", "in": "query", "required": false, "description": "ISO8601 timestamp — observations with `valid_to` before this drop out.", "schema": { "type": "string", "format": "date-time" } }, { "name": "classification_ceiling", "in": "query", "required": false, "description": "Server-side classification ceiling (`U`/`CUI`/`C`/`S`/`TS`). Profile entries above the level drop out.", "schema": { "type": "string" } }, { "name": "workspace_id", "in": "query", "required": false, "description": "Optional team-workspace scope.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Contact + rendered profile.", "content": { "application/json": { "schema": { "type": "object", "required": [ "contact", "profile" ], "properties": { "contact": { "type": "object", "description": "Rendered contact projection — backed by an `entity` frame of\n`concept_type='person'` in the observer's notebook KG.\n", "required": [ "id", "label", "status", "archived", "created_at" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "aliases": { "type": "array", "items": { "type": "string" } }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "linkedin_url": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "external", "invited", "on_platform", "platform_user_removed" ] }, "platform_entity_id": { "type": [ "string", "null" ] }, "no_auto_link": { "type": "boolean", "default": false }, "archived": { "type": "boolean", "default": false }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } }, "profile": { "type": "object", "description": "Rendered profile view — wire shape of\n`notebook::profile::ProfileView`. Entries are newest-first up to\n`PROFILE_RENDER_LIMIT` (500); `truncated` flags when paginated.\n", "required": [ "entity_id", "stance_counts", "entries", "total", "truncated" ], "properties": { "entity_id": { "type": "string" }, "stance_counts": { "type": "object", "description": "Per-stance counts across all entries.", "required": [ "support", "challenge", "question", "neutral", "uncertain" ], "properties": { "support": { "type": "integer", "minimum": 0 }, "challenge": { "type": "integer", "minimum": 0 }, "question": { "type": "integer", "minimum": 0 }, "neutral": { "type": "integer", "minimum": 0 }, "uncertain": { "type": "integer", "minimum": 0 } } }, "entries": { "type": "array", "items": { "type": "object", "description": "One entry in a rendered profile — `notebook::profile::ProfileEntry`.\n", "required": [ "frame_id", "kind", "created_at" ], "properties": { "frame_id": { "type": "string" }, "kind": { "type": "string", "enum": [ "observation", "relation_inbound", "platform_signal" ] }, "stance": { "type": [ "string", "null" ], "enum": [ "support", "challenge", "question", "neutral", "uncertain", null ] }, "verb": { "type": [ "string", "null" ] }, "raw_text": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "provenance": { "type": "object", "description": "Bundled provenance — `notebook::profile::ProvenanceMeta`.\n", "properties": { "claim_id": { "type": "string", "description": "Backend grouping key (`(verb_pattern, slot_fillers)` hash)." }, "corroboration_count": { "type": "integer", "minimum": 1, "default": 1 }, "source_documents": { "type": "array", "items": { "type": "object", "required": [ "document_id", "document_label" ], "properties": { "document_id": { "type": "string" }, "document_label": { "type": "string" }, "credibility": { "oneOf": [ { "type": "null" }, { "type": "object", "description": "NATO admiralty grade — `notebook::profile::Credibility`.\n", "required": [ "reliability", "veracity", "rated_at" ], "properties": { "reliability": { "type": "string", "description": "Single uppercase character A..F.", "minLength": 1, "maxLength": 1 }, "veracity": { "type": "integer", "minimum": 1, "maximum": 6 }, "rated_by": { "type": [ "string", "null" ] }, "rated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } ] } } }, "default": [] }, "credibility": { "oneOf": [ { "type": "null" }, { "type": "object", "description": "NATO admiralty grade — `notebook::profile::Credibility`.\n", "required": [ "reliability", "veracity", "rated_at" ], "properties": { "reliability": { "type": "string", "description": "Single uppercase character A..F.", "minLength": 1, "maxLength": 1 }, "veracity": { "type": "integer", "minimum": 1, "maximum": 6 }, "rated_by": { "type": [ "string", "null" ] }, "rated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } ] }, "source_chunk_id": { "type": [ "string", "null" ] }, "span_start": { "type": [ "integer", "null" ], "minimum": 0 }, "span_end": { "type": [ "integer", "null" ], "minimum": 0 }, "merged_quotes": { "type": "array", "items": { "type": "object", "required": [ "raw_text", "created_at" ], "properties": { "raw_text": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "source_document_id": { "type": [ "string", "null" ] } } }, "default": [] }, "source_class": { "type": [ "string", "null" ], "description": "HUMINT / SIGINT / OSINT / IMINT / GEOINT / FININT / PERSONAL / OTHER." } } }, "temporal": { "type": "object", "description": "Temporal validity bounds — `notebook::profile::TemporalMeta`.\n", "properties": { "valid_from": { "type": [ "string", "null" ], "format": "date-time" }, "valid_to": { "type": [ "string", "null" ], "format": "date-time" } } }, "classification": { "oneOf": [ { "type": "null" }, { "type": "object", "description": "Classification level + compartments —\n`notebook::profile::ClassificationMeta`.\n", "required": [ "level" ], "properties": { "level": { "type": "string", "enum": [ "U", "CUI", "C", "S", "TS" ] }, "compartments": { "type": "array", "items": { "type": "string" }, "default": [] } } } ] }, "properties": { "description": "Arbitrary JSON value." } } } }, "total": { "type": "integer", "minimum": 0 }, "truncated": { "type": "boolean", "description": "True when `entries.len() < total` (hit render limit)." } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getContact_Crm", "resource_uri": "yf://agents/crm", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -G \\\n -H \"Authorization: Bearer $JWT\" \\\n \"https://agents.yieldfabric.com/api/crm/contacts/person:alex\"\n" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx\n\nresp = httpx.get(\n f\"https://agents.yieldfabric.com/api/crm/contacts/{contact_id}\",\n headers={\"Authorization\": f\"Bearer {jwt}\"},\n params={\"as_of\": \"2027-05-01T00:00:00Z\"},\n)\nresp.raise_for_status()\ndata = resp.json()\nprint(data[\"contact\"][\"display_name\"])\nfor claim in data[\"profile\"][\"claims\"]:\n print(\"-\", claim[\"text\"])\n" } ], "x-related": [ { "operationId": "createContact_Crm", "relation": "sibling" }, { "operationId": "listContacts_Crm", "relation": "sibling" }, { "operationId": "updateContact_Crm", "relation": "sibling" }, { "operationId": "archiveContact_Crm", "relation": "sibling" }, { "operationId": "getEntity_Notebook", "relation": "alternate" }, { "guide": "conversation", "relation": "concept" } ] }, "patch": { "operationId": "updateContact_Crm", "x-method": "PATCH", "x-path": "/api/crm/contacts/{id}", "x-handler": "handlers::crm::update_contact", "tags": [ "CRM" ], "summary": "Update a contact's identity fields, tags, no_auto_link, or platform_entity_id.", "description": "Partial update over a Person frame's properties. Accepts the same `ContactInput`\nshape as create — fields omitted leave their current value. Setting\n`no_auto_link=true` opts the contact out of automatic dispatcher routing from\nunrelated threads; `platform_entity_id` rebinds the contact to a platform user\nidentity (typically once after onboarding).\n\nAuth: bearer JWT. The observer becomes the row's `updated_by`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Contact frame id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Partial update — all fields optional. Used for create + update.", "properties": { "label": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "aliases": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "linkedin_url": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] }, "tags": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "platform_entity_id": { "type": [ "string", "null" ] }, "no_auto_link": { "type": [ "boolean", "null" ] } } }, "examples": { "rename": { "summary": "Edit display name + email", "value": { "display_name": "Alexandra Lender", "email": "alexandra@acme.fund" } }, "opt-out": { "summary": "Disable auto-routing", "value": { "no_auto_link": true } } } } } }, "responses": { "200": { "description": "The updated contact.", "content": { "application/json": { "schema": { "type": "object", "description": "Rendered contact projection — backed by an `entity` frame of\n`concept_type='person'` in the observer's notebook KG.\n", "required": [ "id", "label", "status", "archived", "created_at" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "aliases": { "type": "array", "items": { "type": "string" } }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "linkedin_url": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "external", "invited", "on_platform", "platform_user_removed" ] }, "platform_entity_id": { "type": [ "string", "null" ] }, "no_auto_link": { "type": "boolean", "default": false }, "archived": { "type": "boolean", "default": false }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_updateContact_Crm", "resource_uri": "yf://agents/crm", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PATCH \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"display_name\":\"Alexandra Lender\"}' \\\n https://agents.yieldfabric.com/api/crm/contacts/person:alex\n" } ], "x-related": [ { "operationId": "createContact_Crm", "relation": "sibling" }, { "operationId": "archiveContact_Crm", "relation": "sibling" }, { "operationId": "updateEntity_Notebook", "relation": "alternate" }, { "guide": "conversation", "relation": "concept" } ] }, "delete": { "operationId": "archiveContact_Crm", "x-method": "DELETE", "x-path": "/api/crm/contacts/{id}", "x-handler": "handlers::crm::archive_contact", "tags": [ "CRM" ], "summary": "Archive (soft-delete) a contact.", "description": "Marks the Person frame as archived by stamping `properties.archived=true`. The\ncontact stops appearing in default listings (still visible via\n`?include_archived=true`) and its observations are preserved for audit. The frame\nis not hard-deleted — its slot edges remain intact so any prior analytic linkage\nstays consistent.\n\nSide-effects: writes a property mutation only; observations on the contact are\nuntouched. Use `DELETE /api/crm/contacts/{id}/observations` to clear them\nseparately.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Contact frame id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Archive ack `{ ok: true }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_archiveContact_Crm", "resource_uri": "yf://agents/crm", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X DELETE \\\n -H \"Authorization: Bearer $JWT\" \\\n https://agents.yieldfabric.com/api/crm/contacts/person:alex\n" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx\n\nresp = httpx.delete(\n f\"https://agents.yieldfabric.com/api/crm/contacts/{contact_id}\",\n headers={\"Authorization\": f\"Bearer {jwt}\"},\n)\nresp.raise_for_status()\n" } ], "x-related": [ { "operationId": "createContact_Crm", "relation": "sibling" }, { "operationId": "updateContact_Crm", "relation": "sibling" }, { "operationId": "archiveEntity_Notebook", "relation": "alternate" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/crm/contacts/{id}/chat": { "post": { "operationId": "postChat_Crm", "x-method": "POST", "x-path": "/api/crm/contacts/{id}/chat", "x-handler": "handlers::crm::post_chat", "tags": [ "CRM" ], "summary": "Post a message to the contact's agent subthread and dispatch mentions.", "description": "Posts the user message to the (observer × contact) subthread inside the personal\nworkspace, then runs the chat pipeline which: (a) auto-fetches any URLs in the\ncontent, (b) detects @-mentions and routes them to other contacts'\nprofilers (high-confidence → `auto_routed`, ambiguous → `possible_mentions`),\nand (c) spawns the per-contact agent reply (delivered later over the SSE\nbroadcast).\n\nReturns the persisted user message + the dispatcher's routing summary so the UI\ncan immediately render the \"also routed to\" ribbon while awaiting the agent\nreply.\n\nSide-effects: lazy-mints the subthread on first call; persists chunks for any\nfetched URLs; emits async agent reply via the personal-workspace SSE stream.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Contact frame id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "User message body — mirrors\n`service::handlers::crm::chat::PostChatRequest`.\n", "required": [ "content" ], "properties": { "content": { "type": "string" } } }, "examples": { "minimal": { "summary": "Plain message", "value": { "content": "Reminder — Alex is the lead on the Acme deal." } }, "with-mention": { "summary": "Message mentioning another contact", "value": { "content": "Looping in @Sara on this thread." } } } } } }, "responses": { "200": { "description": "Persisted message + dispatch summary.", "content": { "application/json": { "schema": { "type": "object", "description": "Chat turn payload — emitted by\n`notebook::chat_pipeline::run_chat_pipeline`. Same shape the\nnotebook chat endpoint uses.\n", "required": [ "thread_id", "message" ], "properties": { "thread_id": { "type": "string", "format": "uuid" }, "message": { "type": "object", "description": "One message in a per-contact agent chat thread.\n", "required": [ "id", "role", "content", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "user", "assistant", "system" ] }, "content": { "type": "string" }, "metadata": { "description": "Arbitrary JSON value." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } }, "auto_routed": { "type": "array", "description": "Other contacts the agent dispatched its reply to.", "items": { "type": "object", "required": [ "entity_id", "label" ], "properties": { "entity_id": { "type": "string" }, "label": { "type": "string" } } } }, "possible_mentions": { "type": "array", "description": "Weak matches surfaced for user confirmation.", "items": { "type": "object", "required": [ "entity_id", "label", "score" ], "properties": { "entity_id": { "type": "string" }, "label": { "type": "string" }, "score": { "type": "number" } } } } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_postChat_Crm", "resource_uri": "yf://agents/crm", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"content\":\"Reminder — Alex is the lead on the Acme deal.\"}' \\\n https://agents.yieldfabric.com/api/crm/contacts/person:alex/chat\n" } ], "x-related": [ { "operationId": "listChat_Crm", "relation": "sibling" }, { "operationId": "postChat_Notebook", "relation": "alternate" }, { "guide": "conversation", "relation": "concept" } ] }, "get": { "operationId": "listChat_Crm", "x-method": "GET", "x-path": "/api/crm/contacts/{id}/chat", "x-handler": "handlers::crm::list_chat", "tags": [ "CRM" ], "summary": "List messages in the contact's private agent-chat subthread.", "description": "Returns the chronological message log for the (observer × contact) subthread\ninside the observer's personal workspace. Empty when no subthread has been\ncreated yet — the GET path deliberately does NOT lazy-mint a personal workspace\nfor a user who's never opened chat.\n\nResponse shape: `{ thread_id, messages: [...] }` where `thread_id` is null when\nno subthread exists. `limit` clamps to [1, 500] with a default of 100.\n\nAuth: bearer JWT. Read-only.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Contact frame id.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max messages to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ], "responses": { "200": { "description": "Subthread messages (possibly empty).", "content": { "application/json": { "schema": { "type": "object", "required": [ "messages" ], "properties": { "messages": { "type": "array", "items": { "type": "object", "description": "One message in a per-contact agent chat thread.\n", "required": [ "id", "role", "content", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "user", "assistant", "system" ] }, "content": { "type": "string" }, "metadata": { "description": "Arbitrary JSON value." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listChat_Crm", "resource_uri": "yf://agents/crm", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -G \\\n -H \"Authorization: Bearer $JWT\" \\\n \"https://agents.yieldfabric.com/api/crm/contacts/person:alex/chat?limit=50\"\n" } ], "x-related": [ { "operationId": "postChat_Crm", "relation": "sibling" }, { "operationId": "listChat_Notebook", "relation": "alternate" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/crm/contacts/{id}/observations": { "delete": { "operationId": "clearObservations_Crm", "x-method": "DELETE", "x-path": "/api/crm/contacts/{id}/observations", "x-handler": "handlers::crm::clear_observations", "tags": [ "CRM" ], "summary": "Drop every observation on this contact.", "description": "Bulk-deletes every accepted SpeechAct observation that targets this contact in\nthe observer's notebook KG. The contact frame itself is untouched (use\n`DELETE /api/crm/contacts/{id}` to archive the row). Useful when a user wants to\nreset the contact's profile while keeping the contact entity.\n\nReturns `{ deleted: }`. Idempotent — calling again on a clean contact is\na no-op returning `{ deleted: 0 }`.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Contact frame id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deletion ack `{ deleted: }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "cleared" ], "properties": { "cleared": { "type": "integer", "minimum": 0 } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_clearObservations_Crm", "resource_uri": "yf://agents/crm", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X DELETE \\\n -H \"Authorization: Bearer $JWT\" \\\n https://agents.yieldfabric.com/api/crm/contacts/person:alex/observations\n" } ], "x-related": [ { "operationId": "deleteObservation_Crm", "relation": "sibling" }, { "operationId": "acceptObservation_Crm", "relation": "sibling" }, { "operationId": "clearObservations_Notebook", "relation": "alternate" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/crm/contacts/{id}/observations/accept": { "post": { "operationId": "acceptObservation_Crm", "x-method": "POST", "x-path": "/api/crm/contacts/{id}/observations/accept", "x-handler": "handlers::crm::accept_observation", "tags": [ "CRM" ], "summary": "Persist an inline suggestion card as a typed SpeechAct observation on this contact.", "description": "Promotes an agent-proposed `AcceptSuggestion` payload (verb, quote, object label,\noptional slot bindings, validity window) into a permanent observation on the\ncontact's profile. The handler verifies the contact exists in the observer's\nnotebook KG (404 otherwise), then persists a new SpeechAct frame at\n`lifecycle=typed`, `graph_layer=user`, with the contact as the target and the\nobserver as `created_by`.\n\nSide-effects: appends to the contact's profile (visible on the next\n`GET /api/crm/contacts/{id}` call). Idempotent at the frame level — re-submitting\nthe same `frame_id` upserts rather than duplicates via the substrate's ON CONFLICT\nsemantics.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Contact frame id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Suggestion to accept — mirrors\n`notebook::observations::types::AcceptSuggestion`.\n", "required": [ "raw_text" ], "properties": { "label": { "type": [ "string", "null" ], "description": "Short display-only name shown in the accepted list." }, "stance": { "type": [ "string", "null" ], "enum": [ "support", "challenge", "question", "neutral", "uncertain", null ] }, "verb": { "type": [ "string", "null" ], "description": "2–5 word phrase the agent proposed." }, "object": { "type": [ "string", "null" ], "description": "Label of the entity the relational claim points at." }, "object_kind": { "type": [ "string", "null" ], "enum": [ "person", "organization", "document", null ] }, "raw_text": { "type": "string", "description": "Exact user quote the suggestion anchored against." }, "source_message_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "examples": { "minimal": { "summary": "Accept a suggested fact", "value": { "verb": "works at", "quote": "Alex mentioned he leads investing at Acme Capital.", "object_label": "Acme Capital" } }, "with-validity": { "summary": "With temporal validity bounds", "value": { "verb": "lives in", "quote": "He just moved to Lisbon last month.", "object_label": "Lisbon", "valid_from": "2027-04-01T00:00:00.000Z" } } } } } }, "responses": { "200": { "description": "The persisted SpeechAct frame summary.", "content": { "application/json": { "schema": { "type": "object", "required": [ "accepted" ], "properties": { "accepted": { "type": "boolean" }, "frame_id": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_acceptObservation_Crm", "resource_uri": "yf://agents/crm", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"verb\":\"works at\",\"quote\":\"...\",\"object_label\":\"Acme Capital\"}' \\\n https://agents.yieldfabric.com/api/crm/contacts/person:alex/observations/accept\n" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx\n\nresp = httpx.post(\n f\"https://agents.yieldfabric.com/api/crm/contacts/{contact_id}/observations/accept\",\n headers={\"Authorization\": f\"Bearer {jwt}\"},\n json={\n \"verb\": \"works at\",\n \"quote\": \"Alex mentioned he leads investing at Acme Capital.\",\n \"object_label\": \"Acme Capital\",\n },\n)\nresp.raise_for_status()\nprint(resp.json())\n" } ], "x-related": [ { "operationId": "backfillObservations_Crm", "relation": "sibling" }, { "operationId": "clearObservations_Crm", "relation": "sibling" }, { "operationId": "deleteObservation_Crm", "relation": "sibling" }, { "operationId": "acceptObservation_Notebook", "relation": "alternate" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/crm/contacts/{id}/observations/backfill": { "post": { "operationId": "backfillObservations_Crm", "x-method": "POST", "x-path": "/api/crm/contacts/{id}/observations/backfill", "x-handler": "handlers::crm::backfill_observations", "tags": [ "CRM" ], "summary": "Heuristically extract object_label + org/contact links on legacy observations.", "description": "Walks every observation on this contact whose `object_label` slot is empty and\nruns the deterministic heuristic extractor over the stored quote text to fill in\nthe company / contact mentioned. Used as a one-shot migration after a substrate\nupgrade or when a contact has pre-extractor observations on file.\n\nReturns `{ updated: }` — number of observations the backfill mutated. Safe\nto re-run (rows already populated are skipped).\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Contact frame id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Backfill report `{ updated: }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "backfilled" ], "properties": { "backfilled": { "type": "integer", "minimum": 0 } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_backfillObservations_Crm", "resource_uri": "yf://agents/crm", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \\\n -H \"Authorization: Bearer $JWT\" \\\n https://agents.yieldfabric.com/api/crm/contacts/person:alex/observations/backfill\n" } ], "x-related": [ { "operationId": "acceptObservation_Crm", "relation": "sibling" }, { "operationId": "clearObservations_Crm", "relation": "sibling" }, { "operationId": "backfillObservations_Notebook", "relation": "alternate" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/crm/contacts/{id}/observations/{frame_id}": { "delete": { "operationId": "deleteObservation_Crm", "x-method": "DELETE", "x-path": "/api/crm/contacts/{id}/observations/{frame_id}", "x-handler": "handlers::crm::delete_observation", "tags": [ "CRM" ], "summary": "Delete a single observation from a contact's profile.", "description": "Hard-deletes the SpeechAct frame identified by `frame_id`, plus its slot edges,\nfrom the observer's notebook KG. The contact frame itself is untouched. 404 when\nthe SpeechAct doesn't exist or isn't owned by this notebook.\n\nUse this when a single piece of stored knowledge is wrong; use\n`DELETE /api/crm/contacts/{id}/observations` to drop them all at once.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Contact frame id (currently informational — selection is by frame_id).", "schema": { "type": "string" } }, { "name": "frame_id", "in": "path", "required": true, "description": "SpeechAct frame id to delete.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delete ack `{ ok: true }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" }, "frame_id": { "type": "string" } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_deleteObservation_Crm", "resource_uri": "yf://agents/crm", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X DELETE \\\n -H \"Authorization: Bearer $JWT\" \\\n https://agents.yieldfabric.com/api/crm/contacts/person:alex/observations/sa:abc123\n" } ], "x-related": [ { "operationId": "clearObservations_Crm", "relation": "sibling" }, { "operationId": "acceptObservation_Crm", "relation": "sibling" }, { "operationId": "deleteObservation_Notebook", "relation": "alternate" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/economies": { "post": { "operationId": "registerEconomy_Economies", "x-method": "POST", "x-path": "/api/economies", "x-handler": "handlers::economies::register_economy", "tags": [ "Economies & Usage" ], "summary": "Register a new economy (or update an existing one by slug).", "description": "Persists an economy definition (slug, name, description, manifest, operator\nidentity, EKP endpoint URL, optional auth config) into the `economies` table and\nbinds an in-memory `RemoteEconomy` proxy at the returned id. Upserts by `slug` —\nre-posting the same slug refreshes the endpoint and manifest without minting a\nnew id. The slug `general` is reserved for the platform's built-in General\nEconomy and cannot be registered or replaced through this API.\n\n**Endpoint address policy (SSRF boundary):** `endpoint_url` drives persistent\noutbound EKP calls from the platform, so by default it must be a public\nhttp(s) URL — private, reserved, or internal destinations (localhost, RFC1918,\nlink-local/metadata, single-label or `.internal`-style hostnames) are rejected\nwith `400`. All later EKP calls to non-allowlisted endpoints are made through\nthe SSRF-safe pinned fetch boundary, so a public hostname that later resolves\nto private address space fails closed at call time. Deployments with\noperators on private networks allowlist their hosts on the agents service via\n`AGENTS_PRIVATE_ECONOMY_ENDPOINT_HOSTS=host-a,host-b` (exact host match);\nhermetic dev can disable the boundary entirely with\n`AGENTS_ALLOW_PRIVATE_ECONOMY_ENDPOINTS=on` (never in production).\n\nSide-effects: probes `/health` before persisting and logs the\nresult, but registers the economy regardless (the operator may bootstrap before\nthe host is reachable). After commit, the in-process `economy_registry` is\npopulated so subsequent agents-side calls can dispatch into the operator without\na round-trip to the DB.\n\nAuth: bearer JWT — typically called by an operator deploying their own economy\nmanifest. The handler enforces **identity binding**: the JWT's `sub` claim\nmust equal the `operator_entity_id` in the request body. Mismatch returns\n`403 FORBIDDEN`, preventing one authenticated operator from registering an\neconomy under another operator's identity.\n\nThe operator client should derive `operator_entity_id` from its own\n`POST /auth/login` response (the `user.id` field) so the two are always\nconsistent. Provisioning of the operator's user account is documented in\nthe operator README §Service Authentication.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "slug", "name", "endpoint_url", "operator_entity_id" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "endpoint_url": { "type": "string", "description": "The operator container's EKP endpoint URL." }, "auth_config": { "description": "Arbitrary JSON value." }, "manifest": { "description": "Arbitrary JSON value." }, "operator_entity_id": { "type": "string", "description": "Entity id of the operator owning this economy. **Must equal the\ncaller's JWT `sub` claim** — mismatch returns `403 FORBIDDEN`.\nThe operator client should source this from its own `POST /auth/login`\nresponse (`user.id` field) so the two values are always consistent\nfor legitimate calls. See operator README §Service Authentication.\n" } } }, "examples": { "minimal": { "summary": "New economy", "value": { "slug": "yf-default", "name": "YieldFabric default economy", "endpoint_url": "https://api.yieldfabric.com", "operator_entity_id": "7a9f1b2c-4e6d-4c2b-9f3a-5b8c1d0e2f3a" } }, "full": { "summary": "With manifest + auth", "value": { "slug": "yf-pilot", "name": "Pilot economy", "description": "Pilot deployment for Q2 partner pilots.", "endpoint_url": "https://pilot.example.com", "operator_entity_id": "7a9f1b2c-4e6d-4c2b-9f3a-5b8c1d0e2f3a", "auth_config": { "kind": "bearer", "token_env": "PILOT_OPERATOR_TOKEN" }, "manifest": { "version": 1, "concepts": [], "patterns": [] } } } } } } }, "responses": { "201": { "description": "The persisted economy.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "slug", "name", "status", "operator_entity_id", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "endpoint_url": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "operator_entity_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } }, "400": { "description": "Reserved slug (`general`), or `endpoint_url` fails the endpoint address\npolicy: not a parseable http(s) URL, carries credentials, or points at\nprivate/reserved/internal address space without the agents service\nallowlisting the host (`AGENTS_PRIVATE_ECONOMY_ENDPOINT_HOSTS`) or\nrunning with `AGENTS_ALLOW_PRIVATE_ECONOMY_ENDPOINTS=on`.\n", "content": { "text/plain": { "schema": { "type": "string", "example": "endpoint_url 'https://api.yieldfabric.com' is not allowed: refusing to fetch private, reserved, or internal address. Economy endpoints must be public http(s) URLs; ..." } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Caller's JWT `sub` does not match `operator_entity_id` in the request\nbody. Returned when an operator (or any authenticated caller) attempts\nto register an economy under an identity other than its own.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Caller entity '' cannot register an economy under entity '' (the JWT's sub must equal operator_entity_id)" } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_registerEconomy_Economies", "resource_uri": "yf://agents/economies", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"slug\":\"yf-default\",\"name\":\"YieldFabric default\",\"endpoint_url\":\"https://api.yieldfabric.com\",\"operator_entity_id\":\"7a9f...\"}' \\\n https://agents.yieldfabric.com/api/economies\n" } ], "x-related": [ { "operationId": "listEconomies_Economies", "relation": "sibling" }, { "operationId": "getEconomy_Economies", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] }, "get": { "operationId": "listEconomies_Economies", "x-method": "GET", "x-path": "/api/economies", "x-handler": "handlers::economies::list_economies", "tags": [ "Economies & Usage" ], "summary": "List active registered economies.", "description": "Returns every economy with `status='active'`, ordered by creation date (newest\nfirst). Filters out tombstoned / paused economies; use the database directly if\nyou need those. Service boot upserts the built-in `general` economy first, so\nthis list includes General Economy even when no operator economy has been\nregistered.\n\nAuth: bearer JWT. Read-only.\n", "responses": { "200": { "description": "Array of `EconomyResponse`.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "id", "slug", "name", "status", "operator_entity_id", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "endpoint_url": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "operator_entity_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listEconomies_Economies", "resource_uri": "yf://agents/economies", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -G \\\n -H \"Authorization: Bearer $JWT\" \\\n https://agents.yieldfabric.com/api/economies\n" } ], "x-related": [ { "operationId": "registerEconomy_Economies", "relation": "sibling" }, { "operationId": "getEconomy_Economies", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/economies/{id}": { "get": { "operationId": "getEconomy_Economies", "x-method": "GET", "x-path": "/api/economies/{id}", "x-handler": "handlers::economies::get_economy", "tags": [ "Economies & Usage" ], "summary": "Get one registered economy by id.", "description": "Fetches a single `EconomyResponse` by UUID. 404 when no row exists at that id —\nincluding for tombstoned / paused economies (the underlying query doesn't filter\non status).\n\nAuth: bearer JWT. Read-only.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Economy id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Economy detail.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "slug", "name", "status", "operator_entity_id", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "endpoint_url": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "operator_entity_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getEconomy_Economies", "resource_uri": "yf://agents/economies", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -G \\\n -H \"Authorization: Bearer $JWT\" \\\n https://agents.yieldfabric.com/api/economies/7a9f1b2c-4e6d-4c2b-9f3a-5b8c1d0e2f3a\n" } ], "x-related": [ { "operationId": "listEconomies_Economies", "relation": "sibling" }, { "operationId": "registerEconomy_Economies", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/lenses/visible-to-me": { "get": { "operationId": "visibleToMe_Misc", "x-method": "GET", "x-path": "/api/lenses/visible-to-me", "x-handler": "handlers::lenses::visible_to_me", "tags": [ "Lenses" ], "summary": "Lens visibility manifest for the caller", "description": "Returns the list of lenses (personal, crm, doc-tracker, intel, …)\nthe caller is allowed to see. The top nav reads this rather than a\nstatic frontend registry so RBAC is enforced server-side. Auth:\nbearer JWT.\n", "parameters": [], "responses": { "200": { "description": "Visible lenses for the authenticated caller.", "content": { "application/json": { "schema": { "type": "object", "required": [ "lenses" ], "properties": { "lenses": { "type": "array", "items": { "description": "Arbitrary JSON value." } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_visibleToMe_Misc", "resource_uri": "yf://agents/misc", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/api/lenses/visible-to-me" } ], "x-related": [ { "operationId": "checkLensAccess_Misc", "relation": "sibling" } ] } }, "/api/lenses/{lens_id}/access": { "get": { "operationId": "checkLensAccess_Misc", "x-method": "GET", "x-path": "/api/lenses/{lens_id}/access", "x-handler": "handlers::lenses::check_lens_access", "tags": [ "Lenses" ], "summary": "Per-lens RBAC gate", "description": "Server-side gate for a single lens. The frontend router checks this\nbefore mounting a restricted lens — a 403 surfaces as a \"not\npermitted\" route fallback. Substrate-level (one endpoint per\n`lens_id`, not lens-shaped data, just RBAC). Auth: bearer JWT.\n", "parameters": [ { "name": "lens_id", "in": "path", "required": true, "description": "Lens identifier (slug).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Caller may access this lens.", "content": { "application/json": { "schema": { "type": "object", "required": [ "access" ], "properties": { "access": { "type": "string", "enum": [ "allowed", "denied", "not_found" ] }, "reason": { "type": [ "string", "null" ] } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_checkLensAccess_Misc", "resource_uri": "yf://agents/misc", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/api/lenses/intel/access" } ], "x-related": [ { "operationId": "visibleToMe_Misc", "relation": "sibling" } ] } }, "/api/llm-credentials": { "get": { "operationId": "listCredentials_Misc", "x-method": "GET", "x-path": "/api/llm-credentials", "x-handler": "handlers::llm_credentials::list_credentials", "tags": [ "LLM Credentials" ], "summary": "List credential metadata for a user or a room.", "description": "Metadata only — provider, label, fingerprint, status, non-secret vendor\nconfig, and the last verify/use timestamps. **Never the key.**\n\n**Scope and access.** A caller addresses their OWN key by default, or a\nROOM's by passing `?group_id=`. The personal scope id always comes from\nthe verified JWT — never from a parameter — so it cannot be tampered\nwith; the room scope is authorized against `ManageGroup` on that room,\nthe same predicate every other room-management action uses. Both go\nthrough one helper, so the rule cannot be implemented four different\nways.\n\nRoom keys are manager-level deliberately: a room's key spends the\nROOM's money on every member's work, and routes their prompts into the\nroom owner's vendor account.\n", "parameters": [ { "name": "group_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Address a ROOM's key instead of your own. Requires `ManageGroup` on that room." } ], "responses": { "200": { "description": "Credentials in scope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "scope_kind", "scope_id", "provider", "key_fingerprint", "status", "config", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "scope_kind": { "type": "string", "enum": [ "user", "working_group" ] }, "scope_id": { "type": "string", "description": "The entity id or room id this key belongs to." }, "provider": { "type": "string", "enum": [ "openai", "azure_openai", "anthropic" ] }, "label": { "type": [ "string", "null" ] }, "key_fingerprint": { "type": "string", "description": "A stable digest for telling two keys apart in a UI. Not the key." }, "status": { "type": "string" }, "config": { "type": "object", "description": "Non-secret vendor settings — chat model or deployment, instance, api version, endpoint." }, "last_verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_error": { "type": [ "string", "null" ], "description": "Truncated vendor error from the last verify or use." }, "created_at": { "type": "string", "format": "date-time" } } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listCredentials_Misc", "resource_uri": "yf://agents/llm-credentials", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET \"https://agents.yieldfabric.com/api/llm-credentials\" \\\n -H \"Authorization: Bearer $JWT\"\n" } ], "x-related": [ { "operationId": "createCredential_Misc", "relation": "alternative" }, { "operationId": "verifyCredential_Misc", "relation": "sibling" } ] }, "post": { "operationId": "createCredential_Misc", "x-method": "POST", "x-path": "/api/llm-credentials", "x-handler": "handlers::llm_credentials::create_credential", "tags": [ "LLM Credentials" ], "summary": "Attach or replace a bring-your-own LLM key.", "description": "Stores an OpenAI, Azure OpenAI, or Anthropic key for a user or a room.\nThe secret is sealed at rest immediately.\n\n**The secret is write-only.** No endpoint on this surface returns it,\nand `CredentialSummary` has no field for one — so there is no code path\nthat can hand a key back out, not even by accident in a future edit.\nCallers get a `key_fingerprint` to tell two keys apart in a UI.\n\nUpserts: posting again for the same `(scope, provider)` replaces the\nlive key rather than accumulating rows.\n\n`azure_openai` additionally requires `chat_model` (the DEPLOYMENT name)\nand one of `instance_name` / `endpoint`. Azure addresses a deployment\nby name in the URL, so a credential without one cannot form a request\nat all — rejecting it here beats an opaque upstream `404` midway\nthrough a corpus ingest.\n\n**Scope and access.** A caller addresses their OWN key by default, or a\nROOM's by passing `?group_id=`. The personal scope id always comes from\nthe verified JWT — never from a parameter — so it cannot be tampered\nwith; the room scope is authorized against `ManageGroup` on that room,\nthe same predicate every other room-management action uses. Both go\nthrough one helper, so the rule cannot be implemented four different\nways.\n\nRoom keys are manager-level deliberately: a room's key spends the\nROOM's money on every member's work, and routes their prompts into the\nroom owner's vendor account.\n", "parameters": [ { "name": "group_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Address a ROOM's key instead of your own. Requires `ManageGroup` on that room." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "provider", "secret" ], "properties": { "provider": { "type": "string", "enum": [ "openai", "azure_openai", "anthropic" ] }, "secret": { "type": "string", "description": "The API key. Sealed at rest immediately and never returned." }, "label": { "type": "string" }, "chat_model": { "type": "string", "description": "Model id (OpenAI, Anthropic) or DEPLOYMENT name (Azure). Required for `azure_openai` — Azure addresses a deployment by name in the URL, so a credential without one cannot form a request at all, and rejecting it here beats an opaque upstream 404 at first chat." }, "instance_name": { "type": "string", "description": "Azure only: the resource instance. Supply this or `endpoint`." }, "api_version": { "type": "string", "description": "Azure only." }, "endpoint": { "type": "string", "description": "Azure only: full endpoint URL. Supply this or `instance_name`." } } } } } }, "responses": { "201": { "description": "The stored credential's metadata. Never the secret.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "scope_kind", "scope_id", "provider", "key_fingerprint", "status", "config", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "scope_kind": { "type": "string", "enum": [ "user", "working_group" ] }, "scope_id": { "type": "string", "description": "The entity id or room id this key belongs to." }, "provider": { "type": "string", "enum": [ "openai", "azure_openai", "anthropic" ] }, "label": { "type": [ "string", "null" ] }, "key_fingerprint": { "type": "string", "description": "A stable digest for telling two keys apart in a UI. Not the key." }, "status": { "type": "string" }, "config": { "type": "object", "description": "Non-secret vendor settings — chat model or deployment, instance, api version, endpoint." }, "last_verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_error": { "type": [ "string", "null" ], "description": "Truncated vendor error from the last verify or use." }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Unknown provider, empty secret, or a missing Azure deployment/instance." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_createCredential_Misc", "resource_uri": "yf://agents/llm-credentials", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \"https://agents.yieldfabric.com/api/llm-credentials\" \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"provider\":\"anthropic\",\"secret\":\"sk-ant-...\",\"chat_model\":\"claude-sonnet-5\"}'\n" } ], "x-related": [ { "operationId": "verifyCredential_Misc", "relation": "next" }, { "operationId": "listCredentials_Misc", "relation": "list" }, { "operationId": "deleteCredential_Misc", "relation": "alternative" } ] } }, "/api/llm-credentials/{id}": { "delete": { "operationId": "deleteCredential_Misc", "x-method": "DELETE", "x-path": "/api/llm-credentials/{id}", "x-handler": "handlers::llm_credentials::delete_credential", "tags": [ "LLM Credentials" ], "summary": "Revoke a stored credential.", "description": "Revokes the key. Work that was already billed against it stays\nattributed to it; revoking stops future use.\n\nThe revoke statement is scoped by the resolved scope, so it authorizes\nand looks up in one statement — another user's id simply does not\nmatch, and the answer is `404`.\n\n**Scope and access.** A caller addresses their OWN key by default, or a\nROOM's by passing `?group_id=`. The personal scope id always comes from\nthe verified JWT — never from a parameter — so it cannot be tampered\nwith; the room scope is authorized against `ManageGroup` on that room,\nthe same predicate every other room-management action uses. Both go\nthrough one helper, so the rule cannot be implemented four different\nways.\n\nRoom keys are manager-level deliberately: a room's key spends the\nROOM's money on every member's work, and routes their prompts into the\nroom owner's vendor account.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "group_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Address a ROOM's key instead of your own. Requires `ManageGroup` on that room." } ], "responses": { "204": { "description": "Revoked." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_deleteCredential_Misc", "resource_uri": "yf://agents/llm-credentials", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X DELETE \"https://agents.yieldfabric.com/api/llm-credentials/$ID\" \\\n -H \"Authorization: Bearer $JWT\"\n" } ], "x-related": [ { "operationId": "listCredentials_Misc", "relation": "list" }, { "operationId": "createCredential_Misc", "relation": "alternative" } ] } }, "/api/llm-credentials/{id}/verify": { "post": { "operationId": "verifyCredential_Misc", "x-method": "POST", "x-path": "/api/llm-credentials/{id}/verify", "x-handler": "handlers::llm_credentials::verify_credential", "tags": [ "LLM Credentials" ], "summary": "Probe the vendor with the smallest possible completion.", "description": "Sends a one-token completion to the vendor and records the outcome.\nCatching a bad key here means the user learns at the settings screen\ninstead of midway through ingesting a corpus.\n\nAnswers `200` with `ok: false` for a rejected key rather than an error\nstatus — the request succeeded; the key is what failed. `error` is the\nvendor's own message, truncated to 200 characters and echoed because it\nis the user's own key failing and they are the one who can fix it.\n\nThe credential is re-resolved from the database scoped to the caller,\nwhich authorizes and looks up in one step: someone else's credential\nsimply is not found. The secret is used without ever being exposed.\n\n**Scope and access.** A caller addresses their OWN key by default, or a\nROOM's by passing `?group_id=`. The personal scope id always comes from\nthe verified JWT — never from a parameter — so it cannot be tampered\nwith; the room scope is authorized against `ManageGroup` on that room,\nthe same predicate every other room-management action uses. Both go\nthrough one helper, so the rule cannot be implemented four different\nways.\n\nRoom keys are manager-level deliberately: a room's key spends the\nROOM's money on every member's work, and routes their prompts into the\nroom owner's vendor account.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "group_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Address a ROOM's key instead of your own. Requires `ManageGroup` on that room." } ], "responses": { "200": { "description": "The probe result. `ok: false` means the vendor rejected the key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "ok" ], "properties": { "id": { "type": "string", "format": "uuid" }, "ok": { "type": "boolean" }, "error": { "type": [ "string", "null" ], "maxLength": 200, "description": "The vendor's own error, truncated. Echoed because it is the user's own key failing and they are the one who can fix it." } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_verifyCredential_Misc", "resource_uri": "yf://agents/llm-credentials", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \"https://agents.yieldfabric.com/api/llm-credentials/$ID/verify\" \\\n -H \"Authorization: Bearer $JWT\"\n" } ], "x-related": [ { "operationId": "createCredential_Misc", "relation": "parent" }, { "operationId": "listCredentials_Misc", "relation": "list" } ] } }, "/api/models": { "get": { "operationId": "listModels_Misc", "x-method": "GET", "x-path": "/api/models", "x-handler": "handlers::models::list_models", "tags": [ "Chat" ], "summary": "List the chat + embedding models this deployment serves.", "description": "Returns the boot-time model registry: the default chat deployment,\nthe optional `mini` deployment (when\n`agents.azure_openai.deployment_name_mini` /\n`AZURE_OPENAI_API_DEPLOYMENT_NAME_MINI` is configured), and the\nembeddings deployment. Clients pass an entry's `id` (or any value\nin `aliases`, case-insensitively) as `ChatRequest.model` on\n`POST /chat` to select that deployment; unknown names there return\na 400 listing this catalog.\n\nAuth: bearer JWT. Read-only.\n", "parameters": [], "responses": { "200": { "description": "`{ data: [{ id, model, kind, aliases, default }] }` — `kind` is `chat` or `embedding`; `model` is the upstream deployment name.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "model", "kind", "aliases", "default" ], "properties": { "id": { "type": "string", "description": "Stable registry id: `default`, `mini`, or `embedding`." }, "model": { "type": "string", "description": "Upstream deployment/model name." }, "kind": { "type": "string", "enum": [ "chat", "embedding" ] }, "aliases": { "type": "array", "items": { "type": "string" }, "description": "Additional accepted names (the deployment name)." }, "default": { "type": "boolean", "description": "True for the deployment-default chat model." } } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listModels_Misc", "resource_uri": "yf://agents/misc", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" \\\n https://agents.yieldfabric.com/api/models\n" } ], "x-related": [ { "operationId": "assistantChatHandler_Misc", "relation": "sibling" }, { "operationId": "usageSummary_Usage", "relation": "concept" } ] } }, "/api/notebook/concepts": { "get": { "operationId": "listConcepts_Notebook", "x-method": "GET", "x-path": "/api/notebook/concepts", "x-handler": "handlers::notebook::entities::list_concepts", "tags": [ "Notebook" ], "summary": "List long-tail concept_type buckets discovered by extraction.", "description": "Returns `{ concepts: [{ concept_type, count }] }` sorted by count desc. The\nnotebook sidebar mounts each long-tail bucket as a clickable group below the\n\"Curated\" wired-kind grids — concept_types like `digital_instrument`,\n`account`, `loan` are LLM-extracted nouns that don't fit a wired kind.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "description": "Optional team-workspace scope.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "`{ concepts: [...] }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "concepts" ], "properties": { "concepts": { "type": "array", "items": { "type": "object", "required": [ "concept_type", "count" ], "properties": { "concept_type": { "type": "string" }, "count": { "type": "integer", "minimum": 0 } } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listConcepts_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -G -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/api/notebook/concepts" } ], "x-related": [ { "operationId": "listConceptEntities_Notebook", "relation": "sibling" }, { "operationId": "listEntities_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/concepts/{concept_type}": { "get": { "operationId": "listConceptEntities_Notebook", "x-method": "GET", "x-path": "/api/notebook/concepts/{concept_type}", "x-handler": "handlers::notebook::entities::list_concept_entities", "tags": [ "Notebook" ], "summary": "List entities under a long-tail concept_type bucket.", "description": "Lists entities whose `concept_type` matches the segment. 400 when the\nconcept_type is a wired kind (e.g. `person`) or reserved — those have dedicated\nroutes via `/api/notebook/entities/{kind}` and shouldn't be re-served here.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "concept_type", "in": "path", "required": true, "description": "Long-tail concept_type bucket (case-insensitive; lowercased server-side).", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Substring match over label + aliases.", "schema": { "type": "string" } }, { "name": "tag", "in": "query", "required": false, "description": "Filter to entities carrying this tag.", "schema": { "type": "string" } }, { "name": "include_archived", "in": "query", "required": false, "description": "Include archived entities.", "schema": { "type": "boolean", "default": false } }, { "name": "workspace_id", "in": "query", "required": false, "description": "Optional team-workspace scope.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "`{ concept_type, entities: [...] }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "entities" ], "properties": { "entities": { "type": "array", "items": { "type": "object", "description": "Rendered notebook entity — the wire shape of `Entity` from\n`src/notebook/entities.rs`. Backed by an `entity` frame whose\n`concept_type` is one of the supported kinds.\n", "required": [ "id", "kind", "label", "archived", "created_at" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "person", "organization", "document", "topic", "deal", "event", "goal", "place", "hypothesis", "rfi", "note" ] }, "label": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "aliases": { "type": "array", "items": { "type": "string" }, "default": [] }, "tags": { "type": "array", "items": { "type": "string" }, "default": [] }, "properties": { "description": "Arbitrary JSON value." }, "archived": { "type": "boolean", "default": false }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listConceptEntities_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -G -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/api/notebook/concepts/digital_instrument" } ], "x-related": [ { "operationId": "listConcepts_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/entities/by-frame-id/{id}": { "get": { "operationId": "getEntityByFrameId_Notebook", "x-method": "GET", "x-path": "/api/notebook/entities/by-frame-id/{id}", "x-handler": "handlers::notebook::entities::get_entity_by_frame_id", "tags": [ "Notebook" ], "summary": "Kind-agnostic entity lookup by frame_id.", "description": "Resolves an entity frame in the observer's notebook KG without requiring the\nkind segment up front. Used by the frontend for stale-URL recovery after a\nreclassify has flipped a row to a different kind or long-tail bucket.\n\nAuth: bearer JWT. Read-only.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Entity frame id.", "schema": { "type": "string" } }, { "name": "workspace_id", "in": "query", "required": false, "description": "Optional team-workspace scope.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Entity row with resolved kind/concept_type.", "content": { "application/json": { "schema": { "type": "object", "required": [ "entity" ], "properties": { "entity": { "type": "object", "description": "Rendered notebook entity — the wire shape of `Entity` from\n`src/notebook/entities.rs`. Backed by an `entity` frame whose\n`concept_type` is one of the supported kinds.\n", "required": [ "id", "kind", "label", "archived", "created_at" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "person", "organization", "document", "topic", "deal", "event", "goal", "place", "hypothesis", "rfi", "note" ] }, "label": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "aliases": { "type": "array", "items": { "type": "string" }, "default": [] }, "tags": { "type": "array", "items": { "type": "string" }, "default": [] }, "properties": { "description": "Arbitrary JSON value." }, "archived": { "type": "boolean", "default": false }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } }, "profile": { "type": "object", "description": "Rendered profile view — wire shape of\n`notebook::profile::ProfileView`. Entries are newest-first up to\n`PROFILE_RENDER_LIMIT` (500); `truncated` flags when paginated.\n", "required": [ "entity_id", "stance_counts", "entries", "total", "truncated" ], "properties": { "entity_id": { "type": "string" }, "stance_counts": { "type": "object", "description": "Per-stance counts across all entries.", "required": [ "support", "challenge", "question", "neutral", "uncertain" ], "properties": { "support": { "type": "integer", "minimum": 0 }, "challenge": { "type": "integer", "minimum": 0 }, "question": { "type": "integer", "minimum": 0 }, "neutral": { "type": "integer", "minimum": 0 }, "uncertain": { "type": "integer", "minimum": 0 } } }, "entries": { "type": "array", "items": { "type": "object", "description": "One entry in a rendered profile — `notebook::profile::ProfileEntry`.\n", "required": [ "frame_id", "kind", "created_at" ], "properties": { "frame_id": { "type": "string" }, "kind": { "type": "string", "enum": [ "observation", "relation_inbound", "platform_signal" ] }, "stance": { "type": [ "string", "null" ], "enum": [ "support", "challenge", "question", "neutral", "uncertain", null ] }, "verb": { "type": [ "string", "null" ] }, "raw_text": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "provenance": { "type": "object", "description": "Bundled provenance — `notebook::profile::ProvenanceMeta`.\n", "properties": { "claim_id": { "type": "string", "description": "Backend grouping key (`(verb_pattern, slot_fillers)` hash)." }, "corroboration_count": { "type": "integer", "minimum": 1, "default": 1 }, "source_documents": { "type": "array", "items": { "type": "object", "required": [ "document_id", "document_label" ], "properties": { "document_id": { "type": "string" }, "document_label": { "type": "string" }, "credibility": { "oneOf": [ { "type": "null" }, { "type": "object", "description": "NATO admiralty grade — `notebook::profile::Credibility`.\n", "required": [ "reliability", "veracity", "rated_at" ], "properties": { "reliability": { "type": "string", "description": "Single uppercase character A..F.", "minLength": 1, "maxLength": 1 }, "veracity": { "type": "integer", "minimum": 1, "maximum": 6 }, "rated_by": { "type": [ "string", "null" ] }, "rated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } ] } } }, "default": [] }, "credibility": { "oneOf": [ { "type": "null" }, { "type": "object", "description": "NATO admiralty grade — `notebook::profile::Credibility`.\n", "required": [ "reliability", "veracity", "rated_at" ], "properties": { "reliability": { "type": "string", "description": "Single uppercase character A..F.", "minLength": 1, "maxLength": 1 }, "veracity": { "type": "integer", "minimum": 1, "maximum": 6 }, "rated_by": { "type": [ "string", "null" ] }, "rated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } ] }, "source_chunk_id": { "type": [ "string", "null" ] }, "span_start": { "type": [ "integer", "null" ], "minimum": 0 }, "span_end": { "type": [ "integer", "null" ], "minimum": 0 }, "merged_quotes": { "type": "array", "items": { "type": "object", "required": [ "raw_text", "created_at" ], "properties": { "raw_text": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "source_document_id": { "type": [ "string", "null" ] } } }, "default": [] }, "source_class": { "type": [ "string", "null" ], "description": "HUMINT / SIGINT / OSINT / IMINT / GEOINT / FININT / PERSONAL / OTHER." } } }, "temporal": { "type": "object", "description": "Temporal validity bounds — `notebook::profile::TemporalMeta`.\n", "properties": { "valid_from": { "type": [ "string", "null" ], "format": "date-time" }, "valid_to": { "type": [ "string", "null" ], "format": "date-time" } } }, "classification": { "oneOf": [ { "type": "null" }, { "type": "object", "description": "Classification level + compartments —\n`notebook::profile::ClassificationMeta`.\n", "required": [ "level" ], "properties": { "level": { "type": "string", "enum": [ "U", "CUI", "C", "S", "TS" ] }, "compartments": { "type": "array", "items": { "type": "string" }, "default": [] } } } ] }, "properties": { "description": "Arbitrary JSON value." } } } }, "total": { "type": "integer", "minimum": 0 }, "truncated": { "type": "boolean", "description": "True when `entries.len() < total` (hit render limit)." } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getEntityByFrameId_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -G -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/api/notebook/entities/by-frame-id/person:alex" } ], "x-related": [ { "operationId": "getEntity_Notebook", "relation": "sibling" }, { "operationId": "reclassifyEntity_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/entities/by-frame-id/{id}/edges": { "get": { "operationId": "getEntityEdges_Notebook", "x-method": "GET", "x-path": "/api/notebook/entities/by-frame-id/{id}/edges", "x-handler": "handlers::notebook::entities::get_entity_edges", "tags": [ "Notebook" ], "summary": "Debug dump of every slot edge into or out of the entity.", "description": "Returns `{ edges: [...] }` — each slot edge into or out of the entity frame, with\nthe related frame's identifying fields. Surfaces what the substrate actually has\nlinked without dropping to SQL, useful for diagnosing why Sources is empty when\nit shouldn't be.\n\nAuth: bearer JWT. Read-only.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Entity frame id.", "schema": { "type": "string" } }, { "name": "workspace_id", "in": "query", "required": false, "description": "Optional team-workspace scope.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "`{ edges: [...] }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "edges" ], "properties": { "edges": { "type": "array", "items": { "description": "Arbitrary JSON value." } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getEntityEdges_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -G -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/api/notebook/entities/by-frame-id/person:alex/edges" } ], "x-related": [ { "operationId": "getEntityNeighbours_Notebook", "relation": "sibling" }, { "operationId": "getEntitySources_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/entities/by-frame-id/{id}/neighbours": { "get": { "operationId": "getEntityNeighbours_Notebook", "x-method": "GET", "x-path": "/api/notebook/entities/by-frame-id/{id}/neighbours", "x-handler": "handlers::notebook::entities::get_entity_neighbours", "tags": [ "Notebook" ], "summary": "Typed-entity neighbours discovered by walking slot edges.", "description": "Returns `{ neighbours: [...] }` — typed entities reachable from this frame by\nwalking slot edges through wrapper frames AND shared documents. The entity\ncard's \"Linked to\" panel uses this to surface relationship data the substrate\nalready holds without dropping to graph queries.\n\nAuth: bearer JWT. Read-only.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Entity frame id.", "schema": { "type": "string" } }, { "name": "workspace_id", "in": "query", "required": false, "description": "Optional team-workspace scope.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "`{ neighbours: [...] }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "neighbours" ], "properties": { "neighbours": { "type": "array", "items": { "description": "Arbitrary JSON value." } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getEntityNeighbours_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -G -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/api/notebook/entities/by-frame-id/person:alex/neighbours" } ], "x-related": [ { "operationId": "getEntityEdges_Notebook", "relation": "sibling" }, { "operationId": "getEntitySources_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/entities/by-frame-id/{id}/investigation/history": { "get": { "operationId": "entityResearchHistory_Notebook", "x-method": "GET", "x-path": "/api/notebook/entities/by-frame-id/{id}/investigation/history", "x-handler": "handlers::notebook::investigation::history", "summary": "Read saved public research without running another search.", "description": "No provider call or billing reservation. Available even when public research is\ndisabled. Rechecks live home access and actor/delegation case ownership. Returns\nnewest-first pages of ten receipts, including running/failed/interrupted work;\nexpired running receipts read as interrupted. Deleted receipts are omitted.\nCache-Control is no-store. Source text and citations are exact saved attribution.\n", "tags": [ "Notebook" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workspace_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "kg_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "offset", "in": "query", "description": "Clamped to 10000.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Authorized saved history; empty if no investigation exists.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "next_offset" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "status", "error", "created_at", "deadline", "question", "result" ], "properties": { "source": { "type": "object", "required": [ "kg_id", "frame_id", "revision" ], "properties": { "kg_id": { "type": "string", "format": "uuid" }, "frame_id": { "type": "string" }, "revision": { "type": "string" } } }, "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "running", "completed", "failed", "interrupted", "deleted" ] }, "error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "deadline": { "type": "string", "format": "date-time" }, "question": { "oneOf": [ { "type": "object", "required": [ "public_name", "public_context", "question" ], "properties": { "public_name": { "type": "string" }, "public_context": { "type": "string" }, "question": { "type": "string" } } }, { "type": "null" } ] }, "result": { "oneOf": [ { "type": "object", "required": [ "provider", "response_id", "generated_at", "status", "parts", "search_calls" ], "properties": { "provider": { "type": "string", "const": "azure_bing" }, "response_id": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "completed", "no_cited_sources" ] }, "search_calls": { "type": "integer" }, "parts": { "type": "array", "items": { "type": "object", "required": [ "text", "citations" ], "properties": { "text": { "type": "string" }, "citations": { "type": "array", "items": { "type": "object", "required": [ "url", "title", "start_index", "end_index" ], "properties": { "url": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" } } } } } } } } }, { "type": "null" } ] } } } }, "next_offset": { "type": [ "integer", "null" ] } } } } } }, "400": { "description": "Malformed or contradictory scope." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Home knowledge scope is not accessible." }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } } } }, "/api/notebook/entities/by-frame-id/{id}/investigation/history/{run}": { "delete": { "operationId": "deleteEntityResearch_Notebook", "x-method": "DELETE", "x-path": "/api/notebook/entities/by-frame-id/{id}/investigation/history/{run}", "x-handler": "handlers::notebook::investigation::delete_history", "summary": "Delete one saved public research work product and its claim reviews.", "description": "Person-only, live home-authorized deletion in the actor/delegation case. Removes\nthe saved question, answer/citations, hypotheses, assessments and associated\nreviews atomically. Derived notes retain provenance and become unavailable until\nexplicitly edited. Retains a content-free receipt/hash/idempotency tombstone;\nthe same request key cannot recreate content or dispatch another paid search.\nA running upstream call may incur cost but cannot save after deletion.\n", "tags": [ "Notebook" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workspace_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "kg_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "run", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted; repeated deletion is idempotent. Cache-Control is no-store.", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean", "const": true } } } } } }, "400": { "description": "Malformed or contradictory scope." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Home knowledge scope is not accessible." }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } } } }, "/api/notebook/entities/by-frame-id/{id}/investigation/status": { "get": { "operationId": "entityResearchStatus_Notebook", "x-method": "GET", "x-path": "/api/notebook/entities/by-frame-id/{id}/investigation/status", "x-handler": "handlers::notebook::investigation::availability", "tags": [ "Notebook" ], "summary": "Check availability of public research for an accessible entity.", "description": "Read-only, no model call. Resolves the entity in its home KG and checks live\nmembership, room terms and archive status. An explicit workspace and KG must\nagree. No scope selector means the caller's private notebook. Cache-Control is\nno-store. Availability means configuration exists, not a live Azure health probe.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workspace_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "kg_id", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Research configuration and home scope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "available", "scope", "kg_id", "max_search_calls", "retention" ], "properties": { "available": { "type": "boolean" }, "scope": { "type": "string", "enum": [ "private", "workspace" ] }, "kg_id": { "type": "string", "format": "uuid" }, "max_search_calls": { "type": "integer", "const": 4 }, "retention": { "type": "string", "const": "saved_research_brief" } } } } } }, "400": { "description": "Malformed or contradictory scope." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Home knowledge scope is not accessible." }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } } } }, "/api/notebook/entities/by-frame-id/{id}/investigation": { "post": { "operationId": "investigateEntity_Notebook", "x-method": "POST", "x-path": "/api/notebook/entities/by-frame-id/{id}/investigation", "x-handler": "handlers::notebook::investigation::investigate", "tags": [ "Notebook" ], "summary": "Investigate explicit public search terms with Azure web search.", "description": "Read-authorized, billable, bounded research for any pending or accepted ontology\nframe. Only explicit public terms and question reach Microsoft Foundry. No\nconversation history, entity properties, KG evidence or workspace IDs are sent.\nNo call-content logging, automatic crawling, embeddings or identity merging.\n\nBefore dispatch, reserve the daily budget and save a running receipt + question\natomically in the actor/home/delegation-scoped investigation. Idempotency-Key\nreuses the same receipt without another search; changed input under the same key\nconflicts. A deleted receipt remains a content-free retry fence. Only one public\nsearch per investigation can run at once, across replicas.\n\nA bounded background task saves the original answer/attributions as protected\nprovenance and each returned answer part as a reported hypothesis with an\nuncertain agent SpeechAct, through the shared frameset assessment writer.\nThese appear in the existing review API for Keep, Support, Challenge and Undo.\nA response part is not automatically split into verified facts or typed\nrelationships. This research cannot be published or fed back into model context\nas independently reusable source evidence.\n\nSSE observes the saved receipt: researching then one explicit final result or\nerror. The final success includes saved=true and the stored history entry. EOF\nwithout a final event is failure for that observer. Disconnect stops waiting;\nthe admitted search finishes and persists. Reload uses GET history, never a\npaid retry. Home access is checked again before saving and reading.\n\nLimits: existing caller/instance inference admission, four searches, 3,000 output\ntokens, 120 seconds including persistence, 1 MB upstream response, and durable\ndaily person/platform call caps. Model tokens and completed web searches use\nexisting usage metering. A BYO chat credential does not exempt this dedicated\nplatform-funded call. Clients preserve exact answer text and source URLs near\nthe answer; research remains distinct from accepted knowledge.\n", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "UUID for this explicit search; reuse only for retrying the same submission.", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workspace_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "kg_id", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "public_name", "question" ], "properties": { "public_name": { "type": "string", "minLength": 1, "maxLength": 200 }, "public_context": { "type": "string", "maxLength": 300, "default": "" }, "question": { "type": "string", "minLength": 1, "maxLength": 800 } } } } } }, "responses": { "200": { "description": "An observer SSE stream; inspect the terminal event for a saved result.", "content": { "text/event-stream": { "schema": { "type": "string" } } }, "x-event-types": { "researching": "{\"stage\":\"researching\",\"run_id\":\"uuid\"}", "result": "{\"is_final\":true,\"saved\":true,\"run_id\":\"uuid\",\"entry\":{\"id\":\"uuid\",\"status\":\"completed\",\"error\":null,\"created_at\":\"2026-09-07T10:00:00Z\",\"deadline\":\"2026-09-07T10:02:30Z\",\"question\":{\"public_name\":\"Example\",\"public_context\":\"\",\"question\":\"What is known?\"},\"result\":{\"provider\":\"azure_bing\",\"response_id\":\"resp_...\",\"generated_at\":\"2026-09-07T10:00:00Z\",\"status\":\"completed\",\"parts\":[{\"text\":\"...\",\"citations\":[{\"url\":\"https://example.org\",\"title\":\"Source\",\"start_index\":0,\"end_index\":3}]}],\"search_calls\":1}},\"result\":{\"provider\":\"azure_bing\",\"response_id\":\"resp_...\",\"generated_at\":\"2026-09-07T10:00:00Z\",\"status\":\"completed\",\"parts\":[{\"text\":\"...\",\"citations\":[{\"url\":\"https://example.org\",\"title\":\"Source\",\"start_index\":0,\"end_index\":3}]}],\"search_calls\":1}}", "error": "{\"is_final\":true,\"error\":\"Public research did not finish. Try a narrower question.\"}" }, "x-result-statuses": { "completed": "At least one source citation was returned with a completed search.", "no_cited_sources": "Completed search without citations; absence is not established." } }, "400": { "description": "Invalid public terms or scope." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "402": { "description": "AI billing gate denied the request." }, "403": { "description": "Home knowledge scope is not accessible." }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "409": { "description": "Idempotency input conflict or investigation changed." }, "429": { "description": "Caller velocity/concurrency or instance capacity exceeded." }, "503": { "description": "Public research has not been configured." } } } }, "/api/notebook/entities/by-frame-id/{id}/reclassify": { "post": { "operationId": "reclassifyEntity_Notebook", "x-method": "POST", "x-path": "/api/notebook/entities/by-frame-id/{id}/reclassify", "x-handler": "handlers::notebook::entities::reclassify_entity", "tags": [ "Notebook" ], "summary": "Flip an entity's concept_type to a new bucket.", "description": "Reclassifies the entity into a new `concept_type`. The new bucket may be a wired\nkind, an existing concept bucket, or a brand-new user-named one. The handler\nstamps `properties.user_classified=true` so re-extraction respects the user's\nchoice.\n\nStatus codes: 404 — frame missing; 403 — observer self-reclassify; 400 with\n`{ no_op: true }` body when the canonical equals the current type.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Entity frame id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target_kind" ], "properties": { "target_kind": { "type": "string" }, "reason": { "type": [ "string", "null" ] } } }, "examples": { "to-wired": { "summary": "Bucket into a wired kind", "value": { "new_concept_type": "organization" } }, "to-longtail": { "summary": "Bucket into a user-named concept", "value": { "new_concept_type": "digital_instrument" } } } } } }, "responses": { "200": { "description": "Reclassify outcome.", "content": { "application/json": { "schema": { "type": "object", "required": [ "reclassified" ], "properties": { "reclassified": { "type": "boolean" }, "new_frame_id": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_reclassifyEntity_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"new_concept_type\":\"organization\"}' \\\n https://agents.yieldfabric.com/api/notebook/entities/by-frame-id/topic:acme/reclassify\n" } ], "x-related": [ { "operationId": "getEntityByFrameId_Notebook", "relation": "sibling" }, { "operationId": "updateEntity_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/entities/by-frame-id/{id}/sources": { "get": { "operationId": "getEntitySources_Notebook", "x-method": "GET", "x-path": "/api/notebook/entities/by-frame-id/{id}/sources", "x-handler": "handlers::notebook::entities::get_entity_sources", "tags": [ "Notebook" ], "summary": "Every chunk + document the entity has provenance to.", "description": "Returns every chunk and document the entity is provenance-linked to, walked\nthrough the slot-edge graph. Independent of the claims profile so a freshly\nextracted entity surfaces its source chunks even before any claims have landed\nin the dossier.\n\nAuth: bearer JWT. Read-only.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Entity frame id.", "schema": { "type": "string" } }, { "name": "workspace_id", "in": "query", "required": false, "description": "Optional team-workspace scope.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Source documents + chunks.", "content": { "application/json": { "schema": { "type": "object", "required": [ "sources" ], "properties": { "sources": { "type": "array", "items": { "description": "Arbitrary JSON value." } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getEntitySources_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -G -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/api/notebook/entities/by-frame-id/person:alex/sources" } ], "x-related": [ { "operationId": "getEntityNeighbours_Notebook", "relation": "sibling" }, { "operationId": "getEntityEdges_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/entities/by-frame-id/{id}/summary": { "get": { "operationId": "getEntitySummary_Notebook", "x-method": "GET", "x-path": "/api/notebook/entities/by-frame-id/{id}/summary", "x-handler": "handlers::notebook::entities::get_entity_summary", "tags": [ "Notebook" ], "summary": "Cached LLM-synthesised paragraph about the entity.", "description": "Returns a substrate-grounded paragraph (claims + chunks + neighbours) about the\nentity. Cache-keyed on a `sources_hash`: if the cached summary's hash matches the\ncurrent substrate state it's returned as-is; otherwise the handler regenerates,\ncaches in `properties.summary`, and returns.\n\nUse `POST /api/notebook/entities/by-frame-id/{id}/summary` to force regeneration\nregardless of cache state.\n\nAuth: bearer JWT. Idempotent (cached read with lazy regeneration).\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Entity frame id.", "schema": { "type": "string" } }, { "name": "workspace_id", "in": "query", "required": false, "description": "Optional team-workspace scope.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Summary payload (text + cache metadata).", "content": { "application/json": { "schema": { "type": "object", "description": "LLM-synthesised entity summary —\n`notebook::handlers::summary::EntitySummary`.\n", "required": [ "text", "generated_at", "sources_hash", "source_count", "citations" ], "properties": { "text": { "type": "string", "description": "One-paragraph synthesised summary." }, "generated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "sources_hash": { "type": "string", "description": "Hash of the substrate state the summary was built from." }, "source_count": { "type": "integer", "minimum": 0 }, "citations": { "type": "array", "items": { "type": "object", "required": [ "n", "kind", "frame_id", "label" ], "properties": { "n": { "type": "integer", "minimum": 0 }, "kind": { "type": "string", "enum": [ "claim", "chunk", "document", "neighbour" ] }, "frame_id": { "type": "string" }, "label": { "type": "string" } } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getEntitySummary_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -G -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/api/notebook/entities/by-frame-id/person:alex/summary" } ], "x-related": [ { "operationId": "regenerateEntitySummary_Notebook", "relation": "sibling" }, { "operationId": "getEntity_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] }, "post": { "operationId": "regenerateEntitySummary_Notebook", "x-method": "POST", "x-path": "/api/notebook/entities/by-frame-id/{id}/summary", "x-handler": "handlers::notebook::entities::regenerate_entity_summary", "tags": [ "Notebook" ], "summary": "Force-regenerate the entity summary regardless of cache state.", "description": "Same response shape as `GET .../summary` but ignores the `sources_hash` and\nalways re-runs the LLM synthesis. Used when the cached summary is stale in a\nway the substrate hash can't see (e.g. the user pinned new evidence the\ngenerator should incorporate).\n\nSide-effect: writes the regenerated summary to `properties.summary`. LLM call is\nmetered.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Entity frame id.", "schema": { "type": "string" } }, { "name": "workspace_id", "in": "query", "required": false, "description": "Optional team-workspace scope.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Freshly-regenerated summary.", "content": { "application/json": { "schema": { "type": "object", "description": "LLM-synthesised entity summary —\n`notebook::handlers::summary::EntitySummary`.\n", "required": [ "text", "generated_at", "sources_hash", "source_count", "citations" ], "properties": { "text": { "type": "string", "description": "One-paragraph synthesised summary." }, "generated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "sources_hash": { "type": "string", "description": "Hash of the substrate state the summary was built from." }, "source_count": { "type": "integer", "minimum": 0 }, "citations": { "type": "array", "items": { "type": "object", "required": [ "n", "kind", "frame_id", "label" ], "properties": { "n": { "type": "integer", "minimum": 0 }, "kind": { "type": "string", "enum": [ "claim", "chunk", "document", "neighbour" ] }, "frame_id": { "type": "string" }, "label": { "type": "string" } } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_regenerateEntitySummary_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/api/notebook/entities/by-frame-id/person:alex/summary" } ], "x-related": [ { "operationId": "getEntitySummary_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/entities/pending/summary": { "get": { "operationId": "pendingSummary_Notebook", "x-method": "GET", "x-path": "/api/notebook/entities/pending/summary", "x-handler": "handlers::notebook::provisional::pending_summary", "tags": [ "Notebook" ], "summary": "Per-kind counts of PendingReview entities in the notebook.", "description": "Returns a map of `{ concept_type: count }` for every concept_type with at least\none `pending_review` entity in the observer's notebook. Powers the amber dot on\nthe Home sidebar — when any count is non-zero, the user has unfinished review\nwork.\n\nAuth: bearer JWT. Read-only.\n", "responses": { "200": { "description": "`{ : , ... }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "counts" ], "properties": { "counts": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "total": { "type": "integer", "minimum": 0 } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_pendingSummary_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -G -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/api/notebook/entities/pending/summary" } ], "x-related": [ { "operationId": "listPending_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/entities/{kind}": { "post": { "operationId": "createEntity_Notebook", "x-method": "POST", "x-path": "/api/notebook/entities/{kind}", "x-handler": "handlers::notebook::entities::create_entity", "tags": [ "Notebook" ], "summary": "Create an entity of the given kind in the observer's notebook KG.", "description": "Creates a new entity frame at `lifecycle=typed`, `graph_layer=user`. `{kind}` is\nthe URL-segment form of an [`EntityKind`] (`person`, `organization`/`org`,\n`document`, `topic`, `deal`, `event`, `goal`, `place`, `rfi`, `hypothesis`).\nUnknown kinds return 404.\n\nBody is an `EntityInput` shape — identity fields, tags, properties. The handler\nlazy-mints the observer's personal workspace + notebook KG if either is missing\nand stamps `created_by=observer`.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "kind", "in": "path", "required": true, "description": "Entity kind URL segment (e.g. `person`, `organization`, `document`).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Partial input — used for create + update. Mirrors\n`notebook::entities::EntityInput`.\n", "properties": { "label": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "aliases": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "tags": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "properties": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "suggested_id": { "type": [ "string", "null" ], "description": "On create, the caller may suggest an id (e.g. a Document URL\nhash). Ignored on update.\n" } } }, "examples": { "person": { "summary": "Create a person", "value": { "display_name": "Alex Lender", "tags": [ "investor" ] } }, "org": { "summary": "Create an organization", "value": { "display_name": "Acme Capital", "properties": { "website": "https://acme.fund" } } } } } } }, "responses": { "200": { "description": "The created entity.", "content": { "application/json": { "schema": { "type": "object", "description": "Rendered notebook entity — the wire shape of `Entity` from\n`src/notebook/entities.rs`. Backed by an `entity` frame whose\n`concept_type` is one of the supported kinds.\n", "required": [ "id", "kind", "label", "archived", "created_at" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "person", "organization", "document", "topic", "deal", "event", "goal", "place", "hypothesis", "rfi", "note" ] }, "label": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "aliases": { "type": "array", "items": { "type": "string" }, "default": [] }, "tags": { "type": "array", "items": { "type": "string" }, "default": [] }, "properties": { "description": "Arbitrary JSON value." }, "archived": { "type": "boolean", "default": false }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Unknown entity kind segment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_createEntity_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"display_name\":\"Acme Capital\"}' \\\n https://agents.yieldfabric.com/api/notebook/entities/organization\n" } ], "x-related": [ { "operationId": "listEntities_Notebook", "relation": "sibling" }, { "operationId": "getEntity_Notebook", "relation": "sibling" }, { "operationId": "updateEntity_Notebook", "relation": "sibling" }, { "operationId": "archiveEntity_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] }, "get": { "operationId": "listEntities_Notebook", "x-method": "GET", "x-path": "/api/notebook/entities/{kind}", "x-handler": "handlers::notebook::entities::list_entities", "tags": [ "Notebook" ], "summary": "List the observer's entities of a given kind.", "description": "Lists every entity frame of `{kind}` in the observer's notebook KG (or a team\nworkspace's KG when `workspace_id` is set and the observer is a member). Optional\nfilters narrow by free-text search, tag, classification ceiling, or\n`include_archived`. Members of a workspace whose KG hasn't been minted yet get an\nempty array (no lazy-mint on read).\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "kind", "in": "path", "required": true, "description": "Entity kind URL segment.", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Substring match over label + aliases.", "schema": { "type": "string" } }, { "name": "tag", "in": "query", "required": false, "description": "Filter to entities carrying this tag.", "schema": { "type": "string" } }, { "name": "include_archived", "in": "query", "required": false, "description": "Include archived entities.", "schema": { "type": "boolean", "default": false } }, { "name": "classification_ceiling", "in": "query", "required": false, "description": "Hide rows whose classification ranks above this level.", "schema": { "type": "string" } }, { "name": "workspace_id", "in": "query", "required": false, "description": "Optional team-workspace scope.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "`{ entities: [...] }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "entities" ], "properties": { "entities": { "type": "array", "items": { "type": "object", "description": "Rendered notebook entity — the wire shape of `Entity` from\n`src/notebook/entities.rs`. Backed by an `entity` frame whose\n`concept_type` is one of the supported kinds.\n", "required": [ "id", "kind", "label", "archived", "created_at" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "person", "organization", "document", "topic", "deal", "event", "goal", "place", "hypothesis", "rfi", "note" ] }, "label": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "aliases": { "type": "array", "items": { "type": "string" }, "default": [] }, "tags": { "type": "array", "items": { "type": "string" }, "default": [] }, "properties": { "description": "Arbitrary JSON value." }, "archived": { "type": "boolean", "default": false }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Unknown entity kind.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listEntities_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -G \\\n -H \"Authorization: Bearer $JWT\" \\\n https://agents.yieldfabric.com/api/notebook/entities/person\n" } ], "x-related": [ { "operationId": "createEntity_Notebook", "relation": "sibling" }, { "operationId": "getEntity_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/entities/{kind}/pending": { "get": { "operationId": "listPending_Notebook", "x-method": "GET", "x-path": "/api/notebook/entities/{kind}/pending", "x-handler": "handlers::notebook::provisional::list_pending", "tags": [ "Notebook" ], "summary": "List PendingReview entities of this kind, grouped by source document.", "description": "Lists every entity of `{kind}` whose lifecycle is `pending_review`, grouped by\nthe document they were extracted from. Powers the Home review banner: rows like\n\"3 new people from Q1 Memo.pdf · Review →\".\n\nResponse: `{ groups: [{ document_frame_id, document_label, entities: [...] }],\ntotal }`. Scoped to the observer's notebook KG only.\n\nAuth: bearer JWT. Read-only.\n", "parameters": [ { "name": "kind", "in": "path", "required": true, "description": "Entity kind URL segment.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`{ groups, total }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "entities" ], "properties": { "entities": { "type": "array", "items": { "type": "object", "description": "Rendered notebook entity — the wire shape of `Entity` from\n`src/notebook/entities.rs`. Backed by an `entity` frame whose\n`concept_type` is one of the supported kinds.\n", "required": [ "id", "kind", "label", "archived", "created_at" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "person", "organization", "document", "topic", "deal", "event", "goal", "place", "hypothesis", "rfi", "note" ] }, "label": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "aliases": { "type": "array", "items": { "type": "string" }, "default": [] }, "tags": { "type": "array", "items": { "type": "string" }, "default": [] }, "properties": { "description": "Arbitrary JSON value." }, "archived": { "type": "boolean", "default": false }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Unknown entity kind segment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listPending_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -G -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/api/notebook/entities/person/pending" } ], "x-related": [ { "operationId": "pendingSummary_Notebook", "relation": "sibling" }, { "operationId": "promoteOne_Notebook", "relation": "sibling" }, { "operationId": "rejectOne_Notebook", "relation": "sibling" }, { "operationId": "promoteAll_Notebook", "relation": "sibling" }, { "operationId": "rejectAll_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/entities/{kind}/pending/promote-all": { "post": { "operationId": "promoteAll_Notebook", "x-method": "POST", "x-path": "/api/notebook/entities/{kind}/pending/promote-all", "x-handler": "handlers::notebook::provisional::promote_all", "tags": [ "Notebook" ], "summary": "Bulk-promote PendingReview entities of a kind to Typed.", "description": "Iterates every pending entity of `{kind}` (optionally scoped to a single\n`document_frame_id`) and promotes each. Per-entity collisions do NOT roll back\nthe successful promotions; the response lists them under `conflicts` so the\nclient can show a per-row resolution dialog.\n\nReturns `{ promoted: [...], conflicts: [...], errors: [...] }`.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "kind", "in": "path", "required": true, "description": "Entity kind URL segment.", "schema": { "type": "string" } }, { "name": "document_frame_id", "in": "query", "required": false, "description": "Scope to entities extracted from this single document. Missing → all pending of this kind.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`{ promoted, conflicts, errors }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "promoted" ], "properties": { "promoted": { "type": "integer", "minimum": 0 } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Unknown entity kind.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_promoteAll_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/api/notebook/entities/person/pending/promote-all?document_frame_id=doc:memo\"" } ], "x-related": [ { "operationId": "promoteOne_Notebook", "relation": "sibling" }, { "operationId": "rejectAll_Notebook", "relation": "sibling" }, { "operationId": "listPending_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/entities/{kind}/pending/reject-all": { "post": { "operationId": "rejectAll_Notebook", "x-method": "POST", "x-path": "/api/notebook/entities/{kind}/pending/reject-all", "x-handler": "handlers::notebook::provisional::reject_all", "tags": [ "Notebook" ], "summary": "Bulk-reject PendingReview entities scoped to a single document.", "description": "Rejects every pending entity of `{kind}` extracted from the supplied\n`document_frame_id`. Requires the query param explicitly as a safety guard —\nreject-all without a document scope would silently zap every pending entity of\nthe kind across the notebook.\n\nReturns `{ rejected: [...], errors: [...] }`.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "kind", "in": "path", "required": true, "description": "Entity kind URL segment.", "schema": { "type": "string" } }, { "name": "document_frame_id", "in": "query", "required": true, "description": "Document frame id to scope the bulk reject.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`{ rejected, errors }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "rejected" ], "properties": { "rejected": { "type": "integer", "minimum": 0 } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Unknown entity kind.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_rejectAll_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/api/notebook/entities/person/pending/reject-all?document_frame_id=doc:memo\"" } ], "x-related": [ { "operationId": "rejectOne_Notebook", "relation": "sibling" }, { "operationId": "promoteAll_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/entities/{kind}/sweep-junk": { "post": { "operationId": "sweepJunk_Notebook", "x-method": "POST", "x-path": "/api/notebook/entities/{kind}/sweep-junk", "x-handler": "handlers::notebook::entities::sweep_junk", "tags": [ "Notebook" ], "summary": "Archive entities whose labels fail the proper-noun heuristic.", "description": "Archives every non-archived entity of `{kind}` whose label fails the proper-noun\nheuristic (sentence fragments, lowercase starts, verb clauses). Scoped in\npractice to Organization — that's the only kind where `resolve_object_target`\never auto-minted frames from agent output. Other kinds are accepted (and run\nthe same filter) but rarely find anything to sweep.\n\nReturns `{ archived: , labels: [...] }` so the UI can show the user which\nlabels went.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "kind", "in": "path", "required": true, "description": "Entity kind URL segment.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`{ archived, labels }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "archived" ], "properties": { "archived": { "type": "integer", "minimum": 0 }, "candidates": { "type": "array", "items": { "type": "string" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Unknown entity kind segment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_sweepJunk_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/api/notebook/entities/organization/sweep-junk" } ], "x-related": [ { "operationId": "archiveEntity_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/entities/{kind}/{id}": { "get": { "operationId": "getEntity_Notebook", "x-method": "GET", "x-path": "/api/notebook/entities/{kind}/{id}", "x-handler": "handlers::notebook::entities::get_entity", "tags": [ "Notebook" ], "summary": "Get an entity + its rendered observation profile.", "description": "Returns the entity frame plus the temporally-filtered profile rendered from every\nobservation that targets it across the observer's accessible KGs (personal +\nworkspaces they belong to). `as_of` cuts observations whose `valid_to` is before\nthe timestamp; `classification_ceiling` drops claims above the level.\n\n404 when the entity doesn't exist or kind doesn't match the frame's\n`concept_type`. Members of a workspace whose notebook KG hasn't been minted yet\nalso get 404 (the entity can't be in a KG that doesn't exist).\n\nAuth: bearer JWT. Read-only.\n", "parameters": [ { "name": "kind", "in": "path", "required": true, "description": "Entity kind URL segment.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Entity frame id.", "schema": { "type": "string" } }, { "name": "as_of", "in": "query", "required": false, "description": "ISO8601 timestamp — observations expired before this are hidden.", "schema": { "type": "string", "format": "date-time" } }, { "name": "classification_ceiling", "in": "query", "required": false, "description": "Server-side classification ceiling.", "schema": { "type": "string" } }, { "name": "workspace_id", "in": "query", "required": false, "description": "Optional team-workspace scope.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "`{ entity, profile }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "entity" ], "properties": { "entity": { "type": "object", "description": "Rendered notebook entity — the wire shape of `Entity` from\n`src/notebook/entities.rs`. Backed by an `entity` frame whose\n`concept_type` is one of the supported kinds.\n", "required": [ "id", "kind", "label", "archived", "created_at" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "person", "organization", "document", "topic", "deal", "event", "goal", "place", "hypothesis", "rfi", "note" ] }, "label": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "aliases": { "type": "array", "items": { "type": "string" }, "default": [] }, "tags": { "type": "array", "items": { "type": "string" }, "default": [] }, "properties": { "description": "Arbitrary JSON value." }, "archived": { "type": "boolean", "default": false }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } }, "profile": { "type": "object", "description": "Rendered profile view — wire shape of\n`notebook::profile::ProfileView`. Entries are newest-first up to\n`PROFILE_RENDER_LIMIT` (500); `truncated` flags when paginated.\n", "required": [ "entity_id", "stance_counts", "entries", "total", "truncated" ], "properties": { "entity_id": { "type": "string" }, "stance_counts": { "type": "object", "description": "Per-stance counts across all entries.", "required": [ "support", "challenge", "question", "neutral", "uncertain" ], "properties": { "support": { "type": "integer", "minimum": 0 }, "challenge": { "type": "integer", "minimum": 0 }, "question": { "type": "integer", "minimum": 0 }, "neutral": { "type": "integer", "minimum": 0 }, "uncertain": { "type": "integer", "minimum": 0 } } }, "entries": { "type": "array", "items": { "type": "object", "description": "One entry in a rendered profile — `notebook::profile::ProfileEntry`.\n", "required": [ "frame_id", "kind", "created_at" ], "properties": { "frame_id": { "type": "string" }, "kind": { "type": "string", "enum": [ "observation", "relation_inbound", "platform_signal" ] }, "stance": { "type": [ "string", "null" ], "enum": [ "support", "challenge", "question", "neutral", "uncertain", null ] }, "verb": { "type": [ "string", "null" ] }, "raw_text": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "provenance": { "type": "object", "description": "Bundled provenance — `notebook::profile::ProvenanceMeta`.\n", "properties": { "claim_id": { "type": "string", "description": "Backend grouping key (`(verb_pattern, slot_fillers)` hash)." }, "corroboration_count": { "type": "integer", "minimum": 1, "default": 1 }, "source_documents": { "type": "array", "items": { "type": "object", "required": [ "document_id", "document_label" ], "properties": { "document_id": { "type": "string" }, "document_label": { "type": "string" }, "credibility": { "oneOf": [ { "type": "null" }, { "type": "object", "description": "NATO admiralty grade — `notebook::profile::Credibility`.\n", "required": [ "reliability", "veracity", "rated_at" ], "properties": { "reliability": { "type": "string", "description": "Single uppercase character A..F.", "minLength": 1, "maxLength": 1 }, "veracity": { "type": "integer", "minimum": 1, "maximum": 6 }, "rated_by": { "type": [ "string", "null" ] }, "rated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } ] } } }, "default": [] }, "credibility": { "oneOf": [ { "type": "null" }, { "type": "object", "description": "NATO admiralty grade — `notebook::profile::Credibility`.\n", "required": [ "reliability", "veracity", "rated_at" ], "properties": { "reliability": { "type": "string", "description": "Single uppercase character A..F.", "minLength": 1, "maxLength": 1 }, "veracity": { "type": "integer", "minimum": 1, "maximum": 6 }, "rated_by": { "type": [ "string", "null" ] }, "rated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } ] }, "source_chunk_id": { "type": [ "string", "null" ] }, "span_start": { "type": [ "integer", "null" ], "minimum": 0 }, "span_end": { "type": [ "integer", "null" ], "minimum": 0 }, "merged_quotes": { "type": "array", "items": { "type": "object", "required": [ "raw_text", "created_at" ], "properties": { "raw_text": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "source_document_id": { "type": [ "string", "null" ] } } }, "default": [] }, "source_class": { "type": [ "string", "null" ], "description": "HUMINT / SIGINT / OSINT / IMINT / GEOINT / FININT / PERSONAL / OTHER." } } }, "temporal": { "type": "object", "description": "Temporal validity bounds — `notebook::profile::TemporalMeta`.\n", "properties": { "valid_from": { "type": [ "string", "null" ], "format": "date-time" }, "valid_to": { "type": [ "string", "null" ], "format": "date-time" } } }, "classification": { "oneOf": [ { "type": "null" }, { "type": "object", "description": "Classification level + compartments —\n`notebook::profile::ClassificationMeta`.\n", "required": [ "level" ], "properties": { "level": { "type": "string", "enum": [ "U", "CUI", "C", "S", "TS" ] }, "compartments": { "type": "array", "items": { "type": "string" }, "default": [] } } } ] }, "properties": { "description": "Arbitrary JSON value." } } } }, "total": { "type": "integer", "minimum": 0 }, "truncated": { "type": "boolean", "description": "True when `entries.len() < total` (hit render limit)." } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getEntity_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -G \\\n -H \"Authorization: Bearer $JWT\" \\\n https://agents.yieldfabric.com/api/notebook/entities/person/person:alex\n" } ], "x-related": [ { "operationId": "listEntities_Notebook", "relation": "sibling" }, { "operationId": "updateEntity_Notebook", "relation": "sibling" }, { "operationId": "archiveEntity_Notebook", "relation": "sibling" }, { "operationId": "getEntityByFrameId_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] }, "patch": { "operationId": "updateEntity_Notebook", "x-method": "PATCH", "x-path": "/api/notebook/entities/{kind}/{id}", "x-handler": "handlers::notebook::entities::update_entity", "tags": [ "Notebook" ], "summary": "Partial update of an entity's identity, tags, and properties.", "description": "Patches the entity frame with an `EntityInput` shape. Omitted fields keep their\ncurrent value. 404 when the entity doesn't exist or kind doesn't match.\n\nSide-effects: writes to the entity frame's properties + label / aliases columns\nand stamps `updated_by=observer`. Does not modify observations.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "kind", "in": "path", "required": true, "description": "Entity kind URL segment.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Entity frame id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Partial input — used for create + update. Mirrors\n`notebook::entities::EntityInput`.\n", "properties": { "label": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "aliases": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "tags": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "properties": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "suggested_id": { "type": [ "string", "null" ], "description": "On create, the caller may suggest an id (e.g. a Document URL\nhash). Ignored on update.\n" } } }, "examples": { "rename": { "summary": "Rename + add a tag", "value": { "display_name": "Acme Capital Partners", "tags": [ "investor", "warm" ] } } } } } }, "responses": { "200": { "description": "The updated entity.", "content": { "application/json": { "schema": { "type": "object", "description": "Rendered notebook entity — the wire shape of `Entity` from\n`src/notebook/entities.rs`. Backed by an `entity` frame whose\n`concept_type` is one of the supported kinds.\n", "required": [ "id", "kind", "label", "archived", "created_at" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "person", "organization", "document", "topic", "deal", "event", "goal", "place", "hypothesis", "rfi", "note" ] }, "label": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "aliases": { "type": "array", "items": { "type": "string" }, "default": [] }, "tags": { "type": "array", "items": { "type": "string" }, "default": [] }, "properties": { "description": "Arbitrary JSON value." }, "archived": { "type": "boolean", "default": false }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_updateEntity_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PATCH \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"display_name\":\"Acme Capital Partners\"}' \\\n https://agents.yieldfabric.com/api/notebook/entities/organization/org:acme\n" } ], "x-related": [ { "operationId": "getEntity_Notebook", "relation": "sibling" }, { "operationId": "archiveEntity_Notebook", "relation": "sibling" }, { "operationId": "reclassifyEntity_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] }, "delete": { "operationId": "archiveEntity_Notebook", "x-method": "DELETE", "x-path": "/api/notebook/entities/{kind}/{id}", "x-handler": "handlers::notebook::entities::archive_entity", "tags": [ "Notebook" ], "summary": "Archive (soft-delete) an entity.", "description": "Marks the entity frame as archived (`properties.archived=true`). The row drops\nout of default listings (still visible with `?include_archived=true`) but slot\nedges and observations remain intact for audit. Use the observation-clear\nendpoint separately to scrub the profile.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "kind", "in": "path", "required": true, "description": "Entity kind URL segment.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Entity frame id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`{ ok: true }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_archiveEntity_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X DELETE \\\n -H \"Authorization: Bearer $JWT\" \\\n https://agents.yieldfabric.com/api/notebook/entities/organization/org:acme\n" } ], "x-related": [ { "operationId": "getEntity_Notebook", "relation": "sibling" }, { "operationId": "updateEntity_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/entities/{kind}/{id}/ach": { "get": { "operationId": "getHypothesisAch_Notebook", "x-method": "GET", "x-path": "/api/notebook/entities/{kind}/{id}/ach", "x-handler": "handlers::notebook::entities::get_hypothesis_ach", "tags": [ "Notebook" ], "summary": "ACH (Analysis of Competing Hypotheses) matrix for a hypothesis.", "description": "Returns the ACH matrix payload (`AchMatrix`) for the focal hypothesis — claims\nversus alternative hypotheses, with cell-level supports/contradicts ratings.\n\nWired only on `{kind} = hypothesis`. 404 when the focal frame doesn't exist or\nisn't a user-authored hypothesis (extracted-text \"hypothesis\" mentions are\nfiltered out by the `user_authored` gate that the list endpoint uses).\nSubstrate-level read (no per-lens endpoint).\n\nAuth: bearer JWT. Read-only.\n", "parameters": [ { "name": "kind", "in": "path", "required": true, "description": "Must be `hypothesis`.", "schema": { "type": "string", "enum": [ "hypothesis" ] } }, { "name": "id", "in": "path", "required": true, "description": "Hypothesis frame id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "ACH matrix payload.", "content": { "application/json": { "schema": { "type": "object", "description": "ACH matrix payload — wire shape of `notebook::ach::AchMatrix`.\n", "required": [ "focal_hypothesis_id", "hypotheses", "claims" ], "properties": { "focal_hypothesis_id": { "type": "string" }, "question_id": { "type": [ "string", "null" ], "description": "`properties.question_id` shared by the focal hypothesis and its\nsiblings; null when the focal stands alone.\n" }, "hypotheses": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "is_focal" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "is_focal": { "type": "boolean", "default": false } } } }, "claims": { "type": "array", "items": { "type": "object", "required": [ "frame_id", "label", "stance_by_hypothesis", "diagnostic_value" ], "properties": { "frame_id": { "type": "string" }, "label": { "type": "string" }, "stance_by_hypothesis": { "type": "object", "description": "hypothesis_id → support / challenge / none.", "additionalProperties": { "type": "string", "enum": [ "support", "challenge", "none" ] } }, "diagnostic_value": { "type": "number", "description": "[0.0, 1.0] — higher = more disambiguating." } } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getHypothesisAch_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -G -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/api/notebook/entities/hypothesis/hyp:thesis/ach" } ], "x-related": [ { "operationId": "scoreHypothesisHandler_Notebook", "relation": "sibling" }, { "operationId": "composeHypothesisMemo_Notebook", "relation": "sibling" }, { "operationId": "addHypothesisLink_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/entities/{kind}/{id}/chat": { "post": { "operationId": "postChat_Notebook", "x-method": "POST", "x-path": "/api/notebook/entities/{kind}/{id}/chat", "x-handler": "handlers::notebook::entities::post_chat", "tags": [ "Notebook" ], "summary": "Post a message to an entity's agent subthread.", "description": "Posts a user message to the (observer × entity) subthread inside the personal\nworkspace, then runs the chat pipeline: URL auto-fetch, mention dispatcher,\nspawn the per-entity agent reply (delivered later via SSE).\n\nReturns `{ thread_id, message, auto_routed, possible_mentions }` for the UI's\n\"also routed to\" ribbon. `?lens=intel` routes through the named lens's default\nagent prompt (currently `intel-analyst`); absent → kind-default agent.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "kind", "in": "path", "required": true, "description": "Entity kind URL segment.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Entity frame id.", "schema": { "type": "string" } }, { "name": "lens", "in": "query", "required": false, "description": "Lens-scoped agent prompt selector (e.g. `intel`).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string" } } }, "examples": { "minimal": { "summary": "Plain message", "value": { "content": "What did Alex commit to last week?" } } } } } }, "responses": { "200": { "description": "`{ thread_id, message, auto_routed, possible_mentions }`.", "content": { "application/json": { "schema": { "type": "object", "description": "Chat turn payload — emitted by\n`notebook::chat_pipeline::run_chat_pipeline`.\n", "required": [ "thread_id", "message" ], "properties": { "thread_id": { "type": "string", "format": "uuid" }, "message": { "type": "object", "required": [ "id", "role", "content", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "user", "assistant", "system" ] }, "content": { "type": "string" }, "metadata": { "description": "Arbitrary JSON value." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } }, "auto_routed": { "type": "array", "description": "Notebook entities the agent dispatched its reply to.", "items": { "type": "object", "required": [ "entity_id", "label", "kind" ], "properties": { "entity_id": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string" } } } }, "possible_mentions": { "type": "array", "description": "Weak matches surfaced for user confirmation.", "items": { "type": "object", "required": [ "entity_id", "label", "kind", "score" ], "properties": { "entity_id": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string" }, "score": { "type": "number" } } } } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_postChat_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"content\":\"What did Alex commit to last week?\"}' \\\n https://agents.yieldfabric.com/api/notebook/entities/person/person:alex/chat\n" } ], "x-related": [ { "operationId": "listChat_Notebook", "relation": "sibling" }, { "operationId": "postChat_Crm", "relation": "alternate" }, { "guide": "conversation", "relation": "concept" } ] }, "get": { "operationId": "listChat_Notebook", "x-method": "GET", "x-path": "/api/notebook/entities/{kind}/{id}/chat", "x-handler": "handlers::notebook::entities::list_chat", "tags": [ "Notebook" ], "summary": "List subthread messages for an entity's agent chat.", "description": "Returns `{ thread_id, messages: [...] }`. The kind segment is informational —\nselection uses the entity frame_id, which is unique across kinds within a\nnotebook. Empty when no subthread has been created (no lazy-mint on read).\n`limit` clamps to [1, 500] with default 100.\n\nAuth: bearer JWT. Read-only.\n", "parameters": [ { "name": "kind", "in": "path", "required": true, "description": "Entity kind URL segment.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Entity frame id.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max messages to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ], "responses": { "200": { "description": "`{ thread_id, messages }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "messages" ], "properties": { "messages": { "type": "array", "items": { "type": "object", "required": [ "id", "role", "content", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "user", "assistant", "system" ] }, "content": { "type": "string" }, "metadata": { "description": "Arbitrary JSON value." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listChat_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -G -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/api/notebook/entities/person/person:alex/chat" } ], "x-related": [ { "operationId": "postChat_Notebook", "relation": "sibling" }, { "operationId": "listChat_Crm", "relation": "alternate" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/entities/{kind}/{id}/classification": { "patch": { "operationId": "updateEntityClassification_Notebook", "x-method": "PATCH", "x-path": "/api/notebook/entities/{kind}/{id}/classification", "x-handler": "handlers::notebook::entities::update_entity_classification", "tags": [ "Notebook" ], "summary": "Write the classification slot on an entity frame.", "description": "Phase 5.1 — sets `properties.classification = { level, compartments }` on the\nentity frame, or clears the key when `level=\"\"` or `compartments=[]`.\n`level` must be one of `U` / `CUI` / `C` / `S` / `TS`.\n\nSource documents are typically classified once on ingest; SpeechActs inherit\nfrom their source via the lazy walk in `render_profile`. Use this endpoint on a\nSpeechAct frame_id when an analyst upgrades a particular claim above its source\nclassification.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "kind", "in": "path", "required": true, "description": "Entity kind URL segment.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Entity frame id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Patch the entity's classification slot —\n`notebook::handlers::ClassificationPatch`. Empty string / empty\narray clears; missing → no change.\n", "properties": { "level": { "type": [ "string", "null" ], "enum": [ "U", "CUI", "C", "S", "TS", "", null ] }, "compartments": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } } }, "examples": { "set": { "summary": "Set classification level + compartments", "value": { "level": "C", "compartments": [ "NF", "ORCON" ] } }, "clear": { "summary": "Clear classification", "value": { "level": "" } } } } } }, "responses": { "200": { "description": "`{ ok: true }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "updated" ], "properties": { "updated": { "type": "boolean" } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_updateEntityClassification_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PATCH \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"level\":\"C\",\"compartments\":[\"NF\"]}' \\\n https://agents.yieldfabric.com/api/notebook/entities/document/doc:report/classification\n" } ], "x-related": [ { "operationId": "updateEntity_Notebook", "relation": "sibling" }, { "operationId": "updateObservationValidity_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/entities/{kind}/{id}/evidence": { "get": { "operationId": "getRfiEvidence_Notebook", "x-method": "GET", "x-path": "/api/notebook/entities/{kind}/{id}/evidence", "x-handler": "handlers::notebook::entities::get_rfi_evidence", "tags": [ "Notebook" ], "summary": "Evidence view for an RFI (accepted + pending ` answers ` relations).", "description": "Wired only on `{kind} = rfi`. Returns the RFI's evidence view: accepted matches\n(lifecycle=typed) plus pending matcher proposals (lifecycle=pending_review). 404\nwhen the focal frame doesn't exist or isn't a user-authored RFI (extracted-text\n\"rfi\" mentions are filtered out by the same `user_authored` gate the list\nendpoint uses).\n\nAuth: bearer JWT. Read-only.\n", "parameters": [ { "name": "kind", "in": "path", "required": true, "description": "Must be `rfi`.", "schema": { "type": "string", "enum": [ "rfi" ] } }, { "name": "id", "in": "path", "required": true, "description": "RFI frame id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "RFI evidence view.", "content": { "application/json": { "schema": { "type": "object", "description": "Evidence view for an RFI — wire shape of `notebook::rfi::RfiEvidenceView`.\n", "required": [ "rfi_id", "rfi_label", "collected", "pending" ], "properties": { "rfi_id": { "type": "string" }, "rfi_label": { "type": "string" }, "rfi_description": { "type": [ "string", "null" ] }, "priority": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "due_date": { "type": [ "string", "null" ] }, "collected": { "type": "array", "items": { "type": "object", "required": [ "relation_frame_id", "lifecycle", "document_id", "document_label", "created_at" ], "properties": { "relation_frame_id": { "type": "string" }, "lifecycle": { "type": "string", "enum": [ "pending_review", "typed" ] }, "document_id": { "type": "string" }, "document_label": { "type": "string" }, "confidence": { "type": [ "number", "null" ], "description": "[0.0, 1.0] matcher confidence; absent for user-authored matches." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "auto_matched": { "type": "boolean", "default": false }, "cited_chunk_ids": { "type": "array", "items": { "type": "string" }, "default": [] } } } }, "pending": { "type": "array", "items": { "type": "object", "required": [ "relation_frame_id", "lifecycle", "document_id", "document_label", "created_at" ], "properties": { "relation_frame_id": { "type": "string" }, "lifecycle": { "type": "string", "enum": [ "pending_review", "typed" ] }, "document_id": { "type": "string" }, "document_label": { "type": "string" }, "confidence": { "type": [ "number", "null" ], "description": "[0.0, 1.0] matcher confidence; absent for user-authored matches." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "auto_matched": { "type": "boolean", "default": false }, "cited_chunk_ids": { "type": "array", "items": { "type": "string" }, "default": [] } } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getRfiEvidence_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -G -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/api/notebook/entities/rfi/rfi:onboarding/evidence" } ], "x-related": [ { "operationId": "addRfiLink_Notebook", "relation": "sibling" }, { "operationId": "runRfiMatch_Notebook", "relation": "sibling" }, { "operationId": "acceptRfiMatch_Notebook", "relation": "sibling" }, { "operationId": "rejectRfiMatch_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/entities/{kind}/{id}/links": { "post": { "operationId": "addHypothesisLink_Notebook", "x-method": "POST", "x-path": "/api/notebook/entities/{kind}/{id}/links", "x-handler": "handlers::notebook::entities::add_hypothesis_link", "tags": [ "Notebook" ], "summary": "Manually link a claim to a hypothesis as supports / contradicts.", "description": "Adds a user-authored ` supports ` or ` contradicts\n` relation between an existing claim frame (typically a SpeechAct)\nand this hypothesis. Wired only on `{kind} = hypothesis`.\n\nIdempotent on (claim, hypothesis): a second link of the same pair returns the\nexisting relation id rather than creating a duplicate. Returns\n`{ relation_frame_id }`.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "kind", "in": "path", "required": true, "description": "Must be `hypothesis`.", "schema": { "type": "string", "enum": [ "hypothesis" ] } }, { "name": "id", "in": "path", "required": true, "description": "Hypothesis frame id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target_frame_id", "role" ], "properties": { "target_frame_id": { "type": "string" }, "role": { "type": "string", "description": "e.g. evidence, source, refutes." }, "strength": { "type": [ "number", "null" ] } } }, "examples": { "support": { "summary": "Claim supports hypothesis", "value": { "claim_frame_id": "sa:claim_abc", "stance": "support" } }, "contradict": { "summary": "Claim contradicts hypothesis", "value": { "claim_frame_id": "sa:claim_xyz", "stance": "contradict" } } } } } }, "responses": { "200": { "description": "`{ relation_frame_id }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "linked" ], "properties": { "linked": { "type": "boolean" }, "link_id": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_addHypothesisLink_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"claim_frame_id\":\"sa:claim_abc\",\"stance\":\"support\"}' \\\n https://agents.yieldfabric.com/api/notebook/entities/hypothesis/hyp:thesis/links\n" } ], "x-related": [ { "operationId": "getHypothesisAch_Notebook", "relation": "sibling" }, { "operationId": "scoreHypothesisHandler_Notebook", "relation": "sibling" }, { "operationId": "composeHypothesisMemo_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/entities/{kind}/{id}/matches/{relation_frame_id}/accept": { "post": { "operationId": "acceptRfiMatch_Notebook", "x-method": "POST", "x-path": "/api/notebook/entities/{kind}/{id}/matches/{relation_frame_id}/accept", "x-handler": "handlers::notebook::entities::accept_rfi_match", "tags": [ "Notebook" ], "summary": "Accept a pending ` answers ` match (lifecycle pending_review → typed).", "description": "Flips a ` answers ` relation from `pending_review` to `typed`,\npromoting it from a matcher proposal into accepted evidence on the RFI. The\nendpoint verifies both that the kind is `rfi` and that the RFI exists in the\nnotebook before mutating the relation (prevents probing arbitrary\nrelation_frame_ids against arbitrary RFIs). Idempotent — calling on an\nalready-typed match is a no-op.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "kind", "in": "path", "required": true, "description": "Must be `rfi`.", "schema": { "type": "string", "enum": [ "rfi" ] } }, { "name": "id", "in": "path", "required": true, "description": "RFI frame id.", "schema": { "type": "string" } }, { "name": "relation_frame_id", "in": "path", "required": true, "description": "Frame id of the ` answers ` relation.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "No request body. The relation transitions from `pending_review` to\n`typed`.\n", "properties": {} }, "examples": { "minimal": { "summary": "No body", "value": {} } } } } }, "responses": { "200": { "description": "`{ ok: true }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "accepted" ], "properties": { "accepted": { "type": "boolean" }, "frame_id": { "type": [ "string", "null" ] } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_acceptRfiMatch_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/api/notebook/entities/rfi/rfi:onboarding/matches/rfi_link:abc/accept" } ], "x-related": [ { "operationId": "rejectRfiMatch_Notebook", "relation": "sibling" }, { "operationId": "runRfiMatch_Notebook", "relation": "sibling" }, { "operationId": "getRfiEvidence_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/entities/{kind}/{id}/matches/{relation_frame_id}/reject": { "post": { "operationId": "rejectRfiMatch_Notebook", "x-method": "POST", "x-path": "/api/notebook/entities/{kind}/{id}/matches/{relation_frame_id}/reject", "x-handler": "handlers::notebook::entities::reject_rfi_match", "tags": [ "Notebook" ], "summary": "Soft-archive a pending ` answers ` match.", "description": "Stamps `properties.archived=true` + `properties.rejected_match=true` on the\nrelation so it drops out of both pending and accepted lists. Soft-archive\n(rather than hard-delete) because the auto-match log will eventually want to\nshow \"rejected\" decisions for audit.\n\nWired only on `{kind} = rfi`.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "kind", "in": "path", "required": true, "description": "Must be `rfi`.", "schema": { "type": "string", "enum": [ "rfi" ] } }, { "name": "id", "in": "path", "required": true, "description": "RFI frame id.", "schema": { "type": "string" } }, { "name": "relation_frame_id", "in": "path", "required": true, "description": "Frame id of the ` answers ` relation.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "No request body. The pending ` answers ` relation is\nsoft-archived so it drops out of both the pending and accepted lists.\n", "properties": {} }, "examples": { "minimal": { "summary": "No body", "value": {} } } } } }, "responses": { "200": { "description": "`{ ok: true }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "rejected" ], "properties": { "rejected": { "type": "boolean" } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_rejectRfiMatch_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/api/notebook/entities/rfi/rfi:onboarding/matches/rfi_link:abc/reject" } ], "x-related": [ { "operationId": "acceptRfiMatch_Notebook", "relation": "sibling" }, { "operationId": "getRfiEvidence_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/entities/{kind}/{id}/memo": { "get": { "operationId": "composeHypothesisMemo_Notebook", "x-method": "GET", "x-path": "/api/notebook/entities/{kind}/{id}/memo", "x-handler": "handlers::notebook::entities::compose_hypothesis_memo", "tags": [ "Notebook" ], "summary": "Compose a deterministic tear-line memo draft for the hypothesis.", "description": "Phase 5.3 draft memo composer — deterministically assembles the memo from the\nhypothesis's ACH matrix + linked claims + supporting chunks. Optional\n`?ceiling=` applies the tear-line filter so the response is the\nreleasable view at that classification.\n\nWired only on `{kind} = hypothesis`. Read-only — no LLM call, no DB write.\nSee `POST .../memo` to persist the draft as a SpeechAct.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "kind", "in": "path", "required": true, "description": "Must be `hypothesis`.", "schema": { "type": "string", "enum": [ "hypothesis" ] } }, { "name": "id", "in": "path", "required": true, "description": "Hypothesis frame id.", "schema": { "type": "string" } }, { "name": "ceiling", "in": "query", "required": false, "description": "Apply tear-line filter at this classification ceiling.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Memo draft payload.", "content": { "application/json": { "schema": { "type": "object", "description": "Composed memo draft — wire shape of `notebook::memo::MemoDraft`.\n", "required": [ "subject", "bluf", "sections", "cited_chunk_ids" ], "properties": { "subject": { "type": "string" }, "bluf": { "type": "string", "description": "One-line bottom-line-up-front summary." }, "sections": { "type": "array", "items": { "type": "object", "required": [ "heading", "body" ], "properties": { "heading": { "type": "string", "description": "e.g. BLUF / Key Judgment / Evidence / Sources." }, "body": { "type": "string", "description": "Markdown body." }, "max_classification": { "oneOf": [ { "type": "null" }, { "type": "object", "description": "Classification level + compartments —\n`notebook::profile::ClassificationMeta`.\n", "required": [ "level" ], "properties": { "level": { "type": "string", "enum": [ "U", "CUI", "C", "S", "TS" ] }, "compartments": { "type": "array", "items": { "type": "string" }, "default": [] } } } ] }, "cited_chunk_ids": { "type": "array", "items": { "type": "string" }, "default": [] } } } }, "cited_chunk_ids": { "type": "array", "items": { "type": "string" } }, "classification": { "oneOf": [ { "type": "null" }, { "type": "object", "description": "Classification level + compartments —\n`notebook::profile::ClassificationMeta`.\n", "required": [ "level" ], "properties": { "level": { "type": "string", "enum": [ "U", "CUI", "C", "S", "TS" ] }, "compartments": { "type": "array", "items": { "type": "string" }, "default": [] } } } ] } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_composeHypothesisMemo_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -G -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/api/notebook/entities/hypothesis/hyp:thesis/memo?ceiling=S\"" } ], "x-related": [ { "operationId": "saveHypothesisMemo_Notebook", "relation": "sibling" }, { "operationId": "getHypothesisAch_Notebook", "relation": "sibling" }, { "operationId": "scoreHypothesisHandler_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] }, "post": { "operationId": "saveHypothesisMemo_Notebook", "x-method": "POST", "x-path": "/api/notebook/entities/{kind}/{id}/memo", "x-handler": "handlers::notebook::entities::save_hypothesis_memo", "tags": [ "Notebook" ], "summary": "Persist the deterministic memo draft as a SpeechAct on the hypothesis.", "description": "Rebuilds the memo draft server-side (same composition as the GET) and persists\nit as a SpeechAct frame attached to the hypothesis. The frontend posts an empty\nbody to opt in to save; Phase 5+ will accept user edits in the body, but for\nnow the deterministic composition + classification rollup are the invariants\npreserved.\n\nReturns `{ frame_id }` of the persisted memo SpeechAct. Wired only on\n`{kind} = hypothesis`.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "kind", "in": "path", "required": true, "description": "Must be `hypothesis`.", "schema": { "type": "string", "enum": [ "hypothesis" ] } }, { "name": "id", "in": "path", "required": true, "description": "Hypothesis frame id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`{ frame_id }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "saved" ], "properties": { "saved": { "type": "boolean" }, "frame_id": { "type": [ "string", "null" ] } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_saveHypothesisMemo_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/api/notebook/entities/hypothesis/hyp:thesis/memo" } ], "x-related": [ { "operationId": "composeHypothesisMemo_Notebook", "relation": "sibling" }, { "operationId": "scoreHypothesisHandler_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/entities/{kind}/{id}/observations": { "delete": { "operationId": "clearObservations_Notebook", "x-method": "DELETE", "x-path": "/api/notebook/entities/{kind}/{id}/observations", "x-handler": "handlers::notebook::entities::clear_observations", "tags": [ "Notebook" ], "summary": "Drop every observation on this entity.", "description": "Bulk-deletes every accepted SpeechAct observation that targets this entity. The\nentity frame itself is untouched. Returns `{ deleted: }`.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "kind", "in": "path", "required": true, "description": "Entity kind URL segment.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Entity frame id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`{ deleted: }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "cleared" ], "properties": { "cleared": { "type": "integer", "minimum": 0 } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_clearObservations_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X DELETE -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/api/notebook/entities/person/person:alex/observations" } ], "x-related": [ { "operationId": "deleteObservation_Notebook", "relation": "sibling" }, { "operationId": "clearObservations_Crm", "relation": "alternate" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/entities/{kind}/{id}/observations/accept": { "post": { "operationId": "acceptObservation_Notebook", "x-method": "POST", "x-path": "/api/notebook/entities/{kind}/{id}/observations/accept", "x-handler": "handlers::notebook::entities::accept_observation", "tags": [ "Notebook" ], "summary": "Persist an inline suggestion card as a typed SpeechAct observation.", "description": "Generic version of the CRM accept-observation endpoint, parameterised on\n`EntityKind`. Verifies the target entity exists and belongs to this kind (404\notherwise), then persists a new SpeechAct frame at `lifecycle=typed`,\n`graph_layer=user`, with the entity as the target.\n\nIdempotent at the frame level — re-submitting the same `frame_id` upserts via\nthe substrate's ON CONFLICT semantics.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "kind", "in": "path", "required": true, "description": "Entity kind URL segment.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Entity frame id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Suggestion to accept — mirrors\n`notebook::observations::types::AcceptSuggestion`.\n", "required": [ "raw_text" ], "properties": { "label": { "type": [ "string", "null" ], "description": "Short display-only name shown in the accepted list." }, "stance": { "type": [ "string", "null" ], "enum": [ "support", "challenge", "question", "neutral", "uncertain", null ] }, "verb": { "type": [ "string", "null" ], "description": "2–5 word phrase the agent proposed." }, "object": { "type": [ "string", "null" ], "description": "Label of the entity the relational claim points at." }, "object_kind": { "type": [ "string", "null" ], "enum": [ "person", "organization", "document", null ] }, "raw_text": { "type": "string", "description": "Exact user quote the suggestion anchored against." }, "source_message_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "examples": { "minimal": { "summary": "Accept a suggested fact", "value": { "verb": "works at", "quote": "Alex mentioned he leads investing at Acme.", "object_label": "Acme Capital" } } } } } }, "responses": { "200": { "description": "The persisted SpeechAct.", "content": { "application/json": { "schema": { "type": "object", "required": [ "frame_id" ], "properties": { "frame_id": { "type": "string", "description": "Frame id of the persisted accepted observation." } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_acceptObservation_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"verb\":\"works at\",\"quote\":\"...\",\"object_label\":\"Acme\"}' \\\n https://agents.yieldfabric.com/api/notebook/entities/person/person:alex/observations/accept\n" } ], "x-related": [ { "operationId": "backfillObservations_Notebook", "relation": "sibling" }, { "operationId": "clearObservations_Notebook", "relation": "sibling" }, { "operationId": "deleteObservation_Notebook", "relation": "sibling" }, { "operationId": "acceptObservation_Crm", "relation": "alternate" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/entities/{kind}/{id}/observations/backfill": { "post": { "operationId": "backfillObservations_Notebook", "x-method": "POST", "x-path": "/api/notebook/entities/{kind}/{id}/observations/backfill", "x-handler": "handlers::notebook::entities::backfill_observations", "tags": [ "Notebook" ], "summary": "Heuristically extract object_label + org links on legacy observations.", "description": "Walks every observation on this entity whose `object_label` is empty and runs the\ndeterministic heuristic extractor over the stored quote text. Returns\n`{ updated: }`. Idempotent — rows already populated are skipped.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "kind", "in": "path", "required": true, "description": "Entity kind URL segment.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Entity frame id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`{ updated: }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "backfilled" ], "properties": { "backfilled": { "type": "integer", "minimum": 0 } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_backfillObservations_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/api/notebook/entities/person/person:alex/observations/backfill" } ], "x-related": [ { "operationId": "acceptObservation_Notebook", "relation": "sibling" }, { "operationId": "backfillObservations_Crm", "relation": "alternate" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/entities/{kind}/{id}/observations/{frame_id}": { "delete": { "operationId": "deleteObservation_Notebook", "x-method": "DELETE", "x-path": "/api/notebook/entities/{kind}/{id}/observations/{frame_id}", "x-handler": "handlers::notebook::entities::delete_observation", "tags": [ "Notebook" ], "summary": "Delete a single observation from an entity's profile.", "description": "Hard-deletes the SpeechAct frame identified by `frame_id`, plus its slot edges,\nfrom the notebook KG. 404 when the SpeechAct doesn't exist. Returns `{ ok: true }`\non success.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "kind", "in": "path", "required": true, "description": "Entity kind URL segment.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Entity frame id (informational — selection is by frame_id).", "schema": { "type": "string" } }, { "name": "frame_id", "in": "path", "required": true, "description": "SpeechAct frame id to delete.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`{ ok: true }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_deleteObservation_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X DELETE -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/api/notebook/entities/person/person:alex/observations/sa:abc123" } ], "x-related": [ { "operationId": "clearObservations_Notebook", "relation": "sibling" }, { "operationId": "deleteObservation_Crm", "relation": "alternate" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/entities/{kind}/{id}/observations/{frame_id}/validity": { "patch": { "operationId": "updateObservationValidity_Notebook", "x-method": "PATCH", "x-path": "/api/notebook/entities/{kind}/{id}/observations/{frame_id}/validity", "x-handler": "handlers::notebook::entities::update_observation_validity", "tags": [ "Notebook" ], "summary": "Stamp temporal validity (valid_from / valid_to) on a SpeechAct.", "description": "Patches `valid_from` / `valid_to` on the SpeechAct's `properties` JSONB. Each\nfield uses string-as-convention:\n- missing → no change\n- empty string `\"\"` → clear (delete the JSONB key)\n- non-empty RFC3339 → set\n\nThe entity in the path is verified to exist in the notebook so callers can't\nprobe arbitrary frame_ids. We don't verify the SpeechAct actually targets that\nentity (over-strict for branch (d) doc-extraction observations where the target\nis a relation, not the entity).\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "kind", "in": "path", "required": true, "description": "Entity kind URL segment.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Entity frame id.", "schema": { "type": "string" } }, { "name": "frame_id", "in": "path", "required": true, "description": "SpeechAct frame id to patch.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Patch validity bounds — `notebook::handlers::ValidityPatch`. Empty\nstring clears the field; missing → no change; ISO8601 → set.\n", "properties": { "valid_from": { "type": [ "string", "null" ], "description": "ISO8601 datetime, empty string to clear, or absent for no-change." }, "valid_to": { "type": [ "string", "null" ], "description": "ISO8601 datetime, empty string to clear, or absent for no-change." } } }, "examples": { "set-window": { "summary": "Set valid_from + valid_to", "value": { "valid_from": "2027-04-01T00:00:00.000Z", "valid_to": "2026-12-31T23:59:59.000Z" } }, "clear-end": { "summary": "Clear valid_to", "value": { "valid_to": "" } } } } } }, "responses": { "200": { "description": "`{ ok: true }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "updated" ], "properties": { "updated": { "type": "boolean" } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_updateObservationValidity_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PATCH \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"valid_from\":\"2027-04-01T00:00:00Z\"}' \\\n https://agents.yieldfabric.com/api/notebook/entities/person/person:alex/observations/sa:abc123/validity\n" } ], "x-related": [ { "operationId": "acceptObservation_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/entities/{kind}/{id}/promote": { "post": { "operationId": "promoteOne_Notebook", "x-method": "POST", "x-path": "/api/notebook/entities/{kind}/{id}/promote", "x-handler": "handlers::notebook::provisional::promote_one", "tags": [ "Notebook" ], "summary": "Promote a single PendingReview entity to Typed.", "description": "Flips a `pending_review` entity to `typed`, optionally applying edits first\n(rename, description change, property tweaks via `edits: EntityInput`). When the\neffective label collides with an existing Typed entity of the same kind, returns\n409 with `existing_entity_id` + `existing_label` so the UI can show a\nmerge/rename dialog.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "kind", "in": "path", "required": true, "description": "Entity kind URL segment.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Entity frame id (pending).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "Optional per-entity overrides applied during promotion —\n`notebook::handlers::provisional::PromoteBody`. `edits` is the same\n`EntityInput` shape used by create/update; absent fields preserve\nthe pending entity's current values.\n", "properties": { "edits": { "oneOf": [ { "type": "null" }, { "type": "object", "description": "Partial input — used for create + update. Mirrors\n`notebook::entities::EntityInput`.\n", "properties": { "label": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "aliases": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "tags": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "properties": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "suggested_id": { "type": [ "string", "null" ], "description": "On create, the caller may suggest an id (e.g. a Document URL\nhash). Ignored on update.\n" } } } ] } } }, "examples": { "plain": { "summary": "Promote as-is", "value": {} }, "with-edits": { "summary": "Edit before promoting", "value": { "edits": { "display_name": "Acme Capital Partners", "tags": [ "investor" ] } } } } } } }, "responses": { "200": { "description": "`{ outcome: \"promoted\", entity }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "promoted", "frame_id" ], "properties": { "promoted": { "type": "boolean" }, "frame_id": { "type": "string" } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "409": { "description": "Label collides with an existing Typed entity.", "content": { "application/json": { "schema": { "type": "object", "required": [ "promoted", "frame_id" ], "properties": { "promoted": { "type": "boolean" }, "frame_id": { "type": "string" } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_promoteOne_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/api/notebook/entities/person/person:pending_abc/promote" } ], "x-related": [ { "operationId": "promoteAll_Notebook", "relation": "sibling" }, { "operationId": "rejectOne_Notebook", "relation": "sibling" }, { "operationId": "listPending_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/entities/{kind}/{id}/reject": { "post": { "operationId": "rejectOne_Notebook", "x-method": "POST", "x-path": "/api/notebook/entities/{kind}/{id}/reject", "x-handler": "handlers::notebook::provisional::reject_one", "tags": [ "Notebook" ], "summary": "Reject a single PendingReview entity (record + soft-delete).", "description": "Records a per-document rejection so re-extracting the source doc is a no-op for\nthis label, then soft-deletes the pending frame. Returns `{ ok: true }`.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "kind", "in": "path", "required": true, "description": "Entity kind URL segment.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Entity frame id (pending).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "No request body. The reject is recorded against the caller and the\npending frame is soft-deleted.\n", "properties": {} }, "examples": { "minimal": { "summary": "No body", "value": {} } } } } }, "responses": { "200": { "description": "`{ ok: true }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "rejected" ], "properties": { "rejected": { "type": "boolean" } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_rejectOne_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/api/notebook/entities/person/person:pending_abc/reject" } ], "x-related": [ { "operationId": "rejectAll_Notebook", "relation": "sibling" }, { "operationId": "promoteOne_Notebook", "relation": "sibling" }, { "operationId": "listPending_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/entities/{kind}/{id}/rfi-links": { "post": { "operationId": "addRfiLink_Notebook", "x-method": "POST", "x-path": "/api/notebook/entities/{kind}/{id}/rfi-links", "x-handler": "handlers::notebook::entities::add_rfi_link", "tags": [ "Notebook" ], "summary": "Manually link a document as evidence for an RFI.", "description": "Emits a ` answers ` relation with `lifecycle=typed` (user-authored,\nnot matcher-proposed — goes straight into \"Evidence collected\"). Wired only on\n`{kind} = rfi`. Idempotent on (doc, rfi): a second link of the same pair\nreturns the existing id.\n\nReturns `{ relation_frame_id }`.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "kind", "in": "path", "required": true, "description": "Must be `rfi`.", "schema": { "type": "string", "enum": [ "rfi" ] } }, { "name": "id", "in": "path", "required": true, "description": "RFI frame id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target_frame_id" ], "properties": { "target_frame_id": { "type": "string" }, "role": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] } } }, "examples": { "minimal": { "summary": "Link a document", "value": { "document_frame_id": "doc:onboarding_form" } } } } } }, "responses": { "200": { "description": "`{ relation_frame_id }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "linked" ], "properties": { "linked": { "type": "boolean" }, "link_id": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_addRfiLink_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"document_frame_id\":\"doc:onboarding_form\"}' \\\n https://agents.yieldfabric.com/api/notebook/entities/rfi/rfi:onboarding/rfi-links\n" } ], "x-related": [ { "operationId": "runRfiMatch_Notebook", "relation": "sibling" }, { "operationId": "getRfiEvidence_Notebook", "relation": "sibling" }, { "operationId": "acceptRfiMatch_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/entities/{kind}/{id}/score": { "post": { "operationId": "scoreHypothesisHandler_Notebook", "x-method": "POST", "x-path": "/api/notebook/entities/{kind}/{id}/score", "x-handler": "handlers::notebook::entities::score_hypothesis_handler", "tags": [ "Notebook" ], "summary": "LLM-score a hypothesis given its ACH matrix (emits a fresh SpeechAct).", "description": "Invokes the Weaver to score the focal hypothesis given its accumulated\nsupports/contradicts evidence (ACH matrix). Persists a NEW SpeechAct frame\nciting the chunks the model used; never mutates the hypothesis frame itself.\n\nRound-trip integrity (citations non-empty, citations resolve to real chunk\nframes) enforced server-side. 404 — focal missing; 502 — LLM/citation contract\nviolation; 500 — DB.\n\nWired only on `{kind} = hypothesis`. LLM call metered.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "kind", "in": "path", "required": true, "description": "Must be `hypothesis`.", "schema": { "type": "string", "enum": [ "hypothesis" ] } }, { "name": "id", "in": "path", "required": true, "description": "Hypothesis frame id.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "No request body. The scorer uses the live ACH matrix as context.\n", "properties": {} }, "examples": { "minimal": { "summary": "No body", "value": {} } } } } }, "responses": { "200": { "description": "Score output (verdict + citations + new SpeechAct frame_id).", "content": { "application/json": { "schema": { "type": "object", "description": "Score outcome — wire shape of\n`notebook::hypothesis_score::ScoredHypothesisOutcome`.\n", "required": [ "speech_act_frame_id", "score", "rationale", "citations" ], "properties": { "speech_act_frame_id": { "type": "string", "description": "Frame id of the SpeechAct persisted with the score." }, "score": { "type": "number", "description": "Calibrated probability in [0.0, 1.0]." }, "rationale": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" }, "description": "Chunk frame_ids the LLM cited as evidence." } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "502": { "description": "LLM contract violation (citations missing or unresolvable).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_scoreHypothesisHandler_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/api/notebook/entities/hypothesis/hyp:thesis/score" } ], "x-related": [ { "operationId": "getHypothesisAch_Notebook", "relation": "sibling" }, { "operationId": "composeHypothesisMemo_Notebook", "relation": "sibling" }, { "operationId": "addHypothesisLink_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/me": { "get": { "operationId": "me_Notebook", "x-method": "GET", "x-path": "/api/notebook/me", "x-handler": "handlers::notebook::me", "tags": [ "Notebook" ], "summary": "Get the observer's id + personal workspace + notebook KG ids.", "description": "Returns `{ observer, personal_ws_id, notebook_kg_id }` after lazy-minting the\nobserver's personal workspace and notebook KG on first call. Used by the\nfrontend's Home / personal-workspace shell to know which working group is\n\"yours\" and where to send notebook reads / writes.\n\nAuth: bearer JWT.\n", "responses": { "200": { "description": "Observer identity envelope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "observer" ], "properties": { "observer": { "type": "string" }, "notebook_kg_id": { "type": "string", "format": "uuid" }, "personal_workspace_id": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_me_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -G \\\n -H \"Authorization: Bearer $JWT\" \\\n https://agents.yieldfabric.com/api/notebook/me\n" } ], "x-related": [ { "operationId": "getWorkspaceNotebookKg_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/notes": { "post": { "operationId": "createNote_Notebook", "x-method": "POST", "x-path": "/api/notebook/notes", "x-handler": "handlers::notebook::notes::create_note", "tags": [ "Notebook" ], "summary": "Create a free-form prose note in the notebook.", "description": "Persists a chunk + user-picked mention SpeechActs synchronously into the\nobserver's notebook KG (or a team workspace's KG when `workspace_id` is set),\nthen spawns extraction in the background so the HTTP response ships in ~300 ms\nwhile the discovery pass for additional entities runs out-of-band.\n\nInputs: `text` (required, non-empty), `mentions` (already-known entity frame ids\nto pin), optional `confidence` and `source_class` annotations. Side-effects:\nlazy-mints the notebook KG; persists a doc + chunk; spawns async extraction over\nthe new chunk.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "description": "Optional team-workspace scope.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string" }, "mentions": { "type": "array", "items": { "type": "string" }, "description": "Pre-tagged entity ids (pin-as-mention)." }, "confidence": { "type": [ "string", "null" ] }, "source_class": { "type": [ "string", "null" ] } } }, "examples": { "minimal": { "summary": "Plain note", "value": { "text": "Reminder — call Alex about the Acme term sheet." } }, "with-mentions": { "summary": "Note with pre-pinned mentions", "value": { "text": "Alex confirmed Acme will lead the round.", "mentions": [ "person:alex", "org:acme" ], "confidence": "high", "source_class": "chat" } } } } } }, "responses": { "201": { "description": "`{ chunk_frame_id, document_frame_id, resolved_mentions }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "chunk_frame_id", "document_frame_id", "resolved_mentions" ], "properties": { "chunk_frame_id": { "type": "string" }, "document_frame_id": { "type": "string" }, "resolved_mentions": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_createNote_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"text\":\"Reminder — call Alex about the Acme term sheet.\",\"mentions\":[\"person:alex\"]}' \\\n https://agents.yieldfabric.com/api/notebook/notes\n" } ], "x-related": [ { "operationId": "listNotes_Notebook", "relation": "sibling" }, { "operationId": "updateNote_Notebook", "relation": "sibling" }, { "operationId": "deleteNote_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] }, "get": { "operationId": "listNotes_Notebook", "x-method": "GET", "x-path": "/api/notebook/notes", "x-handler": "handlers::notebook::notes::list_notes", "tags": [ "Notebook" ], "summary": "List the observer's saved notes (most recent first).", "description": "Returns `{ notes: [{ frame_id, text, created_at, source_class, confidence,\nmentions }] }`. Empty when the observer has no notes-doc yet — lazy-create only\nhappens on write. When `?doc=` is set, scopes to that document instead\nof resolving the observer's canonical notes doc.\n\n`workspace_id` opts in to a team workspace's notes-doc; read-only (does not\nlazy-mint the workspace KG).\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "doc", "in": "query", "required": false, "description": "Explicit document frame_id to list chunks under (overrides notes-doc lookup).", "schema": { "type": "string" } }, { "name": "workspace_id", "in": "query", "required": false, "description": "Optional team-workspace scope.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "`{ notes: [...] }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "notes" ], "properties": { "notes": { "type": "array", "items": { "type": "object", "required": [ "frame_id", "text", "created_at", "mentions" ], "properties": { "frame_id": { "type": "string" }, "text": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "source_class": { "type": [ "string", "null" ] }, "confidence": { "type": [ "string", "null" ] }, "mentions": { "type": "array", "items": { "type": "object", "required": [ "entity_id", "label", "concept_type" ], "properties": { "entity_id": { "type": "string" }, "label": { "type": "string" }, "concept_type": { "type": "string" } } } } } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listNotes_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -G \\\n -H \"Authorization: Bearer $JWT\" \\\n https://agents.yieldfabric.com/api/notebook/notes\n" } ], "x-related": [ { "operationId": "createNote_Notebook", "relation": "sibling" }, { "operationId": "updateNote_Notebook", "relation": "sibling" }, { "operationId": "deleteNote_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/notes/{frame_id}": { "patch": { "operationId": "updateNote_Notebook", "x-method": "PATCH", "x-path": "/api/notebook/notes/{frame_id}", "x-handler": "handlers::notebook::notes::update_note", "tags": [ "Notebook" ], "summary": "Edit a note's prose, metadata, and pinned mentions.", "description": "Re-embeds the chunk, reconciles user-pin SpeechActs against the new pick set,\nthen spawns a background re-extraction pass over the updated prose. Previously\nextracted SpeechActs on the chunk are wiped by the extractor's prefix-delete;\nuser-pins survive because their frame_id format puts the chunk id in the middle.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "frame_id", "in": "path", "required": true, "description": "Note chunk frame id.", "schema": { "type": "string" } }, { "name": "workspace_id", "in": "query", "required": false, "description": "Optional team-workspace scope.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string" }, "mentions": { "type": "array", "items": { "type": "string" }, "description": "Pre-tagged entity ids (pin-as-mention)." }, "confidence": { "type": [ "string", "null" ] }, "source_class": { "type": [ "string", "null" ] } } }, "examples": { "edit-text": { "summary": "Replace the prose", "value": { "text": "Updated reminder — Acme term sheet due Friday.", "mentions": [ "person:alex", "org:acme" ] } } } } } }, "responses": { "200": { "description": "`{ chunk_frame_id, document_frame_id, resolved_mentions }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "chunk_frame_id", "document_frame_id", "resolved_mentions" ], "properties": { "chunk_frame_id": { "type": "string" }, "document_frame_id": { "type": "string" }, "resolved_mentions": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_updateNote_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PATCH \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"text\":\"Updated reminder.\"}' \\\n https://agents.yieldfabric.com/api/notebook/notes/note_chunk_abc\n" } ], "x-related": [ { "operationId": "createNote_Notebook", "relation": "sibling" }, { "operationId": "deleteNote_Notebook", "relation": "sibling" }, { "operationId": "listNotes_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] }, "delete": { "operationId": "deleteNote_Notebook", "x-method": "DELETE", "x-path": "/api/notebook/notes/{frame_id}", "x-handler": "handlers::notebook::notes::delete_note", "tags": [ "Notebook" ], "summary": "Permanently delete a note + its extracted SpeechActs.", "description": "Hard-deletes the note's chunk frame and cascades through every extracted\nSpeechAct, user-pin, and structural Relation attached to it so no dangling\nprovenance remains.\n\nReturns 204 on success (no body). Use with care — there's no undo.\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "frame_id", "in": "path", "required": true, "description": "Note chunk frame id.", "schema": { "type": "string" } }, { "name": "workspace_id", "in": "query", "required": false, "description": "Optional team-workspace scope.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted (no body)." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_deleteNote_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X DELETE \\\n -H \"Authorization: Bearer $JWT\" \\\n https://agents.yieldfabric.com/api/notebook/notes/note_chunk_abc\n" } ], "x-related": [ { "operationId": "createNote_Notebook", "relation": "sibling" }, { "operationId": "updateNote_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/observations": { "post": { "operationId": "submit_Notebook", "x-method": "POST", "x-path": "/api/notebook/observations", "x-handler": "handlers::notebook::unified_observation::submit", "tags": [ "Notebook" ], "summary": "Append a practitioner assertion to a knowledge graph", "description": "Persists a fresh typed SpeechAct against any target frame in the named KG.\nEvery successful submission creates a new `usa:…` frame, so repeated text\nremains append-only for audit and e-discovery. The caller is registered as a\nhuman speaker; optional `asserted_at`, `supersedes_frame_id`, and free-form\nproperties preserve effective-time and correction provenance.\n\nThe KG's owning working group is authoritative for authorization. The caller\nmust hold the `UploadDocuments` action in that group; readable platform\nknowledge does not become writable. Auth: bearer JWT.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Practitioner-authored typed assertion against any frame in an accessible\nknowledge graph. Mirrors `SubmitObservationBody` flattened with\n`UnifiedObservationInput`.\n", "required": [ "kg_id", "target_frame_id", "verb", "raw_text" ], "properties": { "kg_id": { "type": "string", "format": "uuid", "description": "Target knowledge graph; working-group write access is enforced." }, "target_frame_id": { "type": "string", "minLength": 1, "description": "Any existing frame id in the target KG." }, "verb": { "type": "string", "minLength": 1, "description": "Communicative verb. Common values are `characterises`, `challenges`, `supersedes`, and `annotates`; the substrate intentionally accepts other non-empty values for forward compatibility." }, "stance": { "type": [ "string", "null" ], "description": "`support`, `challenge`, `question`, or `neutral`; absent, null, and unrecognised values are persisted as `uncertain`." }, "raw_text": { "type": "string", "minLength": 1, "description": "Exact practitioner assertion text." }, "asserted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Effective time of the assertion, independent of write time." }, "supersedes_frame_id": { "type": [ "string", "null" ], "description": "Optional frame this assertion replaces or corrects." }, "properties": { "type": "object", "additionalProperties": true, "default": {}, "description": "Free-form assertion metadata such as `correction_reason`." } } }, "examples": { "challenge-clause": { "value": { "kg_id": "11111111-1111-1111-1111-111111111111", "target_frame_id": "clause:minimum-liquidity", "verb": "challenges", "stance": "challenge", "raw_text": "The threshold should be measured on a consolidated basis.", "asserted_at": "2026-07-15T00:00:00Z", "properties": { "correction_reason": "Drafting review" } } } } } } }, "responses": { "201": { "description": "Fresh SpeechAct frame persisted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "frame_id" ], "properties": { "frame_id": { "type": "string", "description": "Fresh append-only SpeechAct frame id (`usa:…`)." } } } } } }, "400": { "description": "Malformed input, blank assertion fields, or substrate write failure." }, "401": { "description": "Missing or invalid bearer credential." }, "403": { "description": "Caller lacks write authority for the KG's owning working group." }, "404": { "description": "Target knowledge graph does not exist." } }, "x-mcp": { "tool_name": "yieldfabric_agents_submit_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST https://agents.yieldfabric.com/api/notebook/observations \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"kg_id\":\"11111111-1111-1111-1111-111111111111\",\"target_frame_id\":\"clause:minimum-liquidity\",\"verb\":\"challenges\",\"stance\":\"challenge\",\"raw_text\":\"Measure this on a consolidated basis.\"}'\n" } ], "x-related": [ { "guide": "pipelines-and-kgs", "relation": "concept" } ] } }, "/api/notebook/rfi-match/{document_frame_id}": { "post": { "operationId": "runRfiMatch_Notebook", "x-method": "POST", "x-path": "/api/notebook/rfi-match/{document_frame_id}", "x-handler": "handlers::notebook::entities::run_rfi_match", "tags": [ "Notebook" ], "summary": "Run the Weaver auto-matcher over one document against every open RFI.", "description": "Runs the LLM-driven Weaver against this document's chunks for every open RFI in\nthe observer's notebook. Confidence-floor (0.7), per-RFI cap (5), per-doc cap\n(20), and `pending_review` default lifecycle are all enforced server-side.\n\nIdempotent at the (doc, rfi) granularity — re-running won't duplicate existing\nmatches. 502 on LLM contract violations (citations missing or unresolvable);\n500 on DB errors.\n\nAuth: bearer JWT. Substrate-level (no per-lens endpoint).\n", "parameters": [ { "name": "document_frame_id", "in": "path", "required": true, "description": "Source document frame id.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "No request body. The matcher uses the document's chunks + every RFI\nin the observer's notebook as context.\n", "properties": {} }, "examples": { "minimal": { "summary": "No body", "value": {} } } } } }, "responses": { "200": { "description": "Match summary (created / skipped / per-RFI breakdown).", "content": { "application/json": { "schema": { "type": "object", "description": "Match run outcome — wire shape of\n`notebook::rfi_match::RfiMatchOutcome`.\n", "required": [ "emitted", "suppressed", "emitted_relation_ids" ], "properties": { "emitted": { "type": "integer", "minimum": 0 }, "suppressed": { "type": "integer", "minimum": 0 }, "emitted_relation_ids": { "type": "array", "items": { "type": "string" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "502": { "description": "LLM contract violation (e.g. citations missing).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_runRfiMatch_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/api/notebook/rfi-match/doc:onboarding_form" } ], "x-related": [ { "operationId": "getRfiEvidence_Notebook", "relation": "sibling" }, { "operationId": "acceptRfiMatch_Notebook", "relation": "sibling" }, { "operationId": "rejectRfiMatch_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/notebook/workspaces/{workspace_id}/notebook-kg": { "get": { "operationId": "getWorkspaceNotebookKg_Notebook", "x-method": "GET", "x-path": "/api/notebook/workspaces/{workspace_id}/notebook-kg", "x-handler": "handlers::notebook::get_workspace_notebook_kg", "tags": [ "Notebook" ], "summary": "Resolve (and lazy-mint) the notebook KG id for a team workspace.", "description": "Returns `{ notebook_kg_id }` for the given workspace, lazy-minting the KG on\nfirst call. Membership-checked — non-members get 403. The frontend's team\nworkspace shell calls this on mount so document uploads can target the team\nnotebook KG (same flow personal `/home` uses for the user's personal notebook).\n\nAuth: bearer JWT.\n", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "`{ notebook_kg_id }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "kg_id" ], "properties": { "kg_id": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getWorkspaceNotebookKg_Notebook", "resource_uri": "yf://agents/notebook", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -G \\\n -H \"Authorization: Bearer $JWT\" \\\n https://agents.yieldfabric.com/api/notebook/workspaces/7a9f1b2c-4e6d-4c2b-9f3a-5b8c1d0e2f3a/notebook-kg\n" } ], "x-related": [ { "operationId": "me_Notebook", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/usage/aggregate": { "get": { "operationId": "usageAggregate_Usage", "x-method": "GET", "x-path": "/api/usage/aggregate", "x-handler": "handlers::usage::usage_aggregate", "tags": [ "Economies & Usage" ], "summary": "Live cross-surface usage aggregation, grouped by feature + model.", "description": "Aggregates the RAW `llm_usage` table (NOT the daily rollup) grouped\nby `(feature, model)` over a date window — so the result is\nup-to-the-second, **includes failed calls** (`error_count`), and\ncovers EVERY surface the caller touched: native chat (`chat`),\nthe OpenAI-compatible `/v1` endpoint (`compat_chat`,\n`compat_embed`), RAG (`rag_query`), workflows, and so on. This is\nthe one query a \"see everything\" usage UI needs — contrast\n`/api/usage/summary`, which is the day-bucketed rollup (lags a few\nminutes and excludes errors).\n\nReturns per-group counts/tokens/errors/avg-latency plus overall\n`totals`. Entity-scoped exactly like the other usage reads: staff\nmay pass `entity_id`; everyone else sees their own rows only.\n\nAuth: bearer JWT. Read-only.\n", "parameters": [ { "name": "entity_id", "in": "query", "required": false, "description": "Filter to one entity. Staff may name any entity; non-staff only their own (else 403).", "schema": { "type": "string" } }, { "name": "working_group_id", "in": "query", "required": false, "description": "Filter to one working group.", "schema": { "type": "string", "format": "uuid" } }, { "name": "feature", "in": "query", "required": false, "description": "Narrow to one surface/feature. Omit for ALL surfaces.", "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "required": false, "description": "Lower bound (YYYY-MM-DD, inclusive). Default `2020-01-01`.", "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "required": false, "description": "Upper bound (YYYY-MM-DD, inclusive). Default `2099-12-31`.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "`{ data: [{feature, model, calls, prompt/completion/total_tokens, error_count, avg_latency_ms}], group_count, totals }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "group_count", "totals" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "One (feature, model) group from the live aggregation.", "required": [ "feature", "model", "calls", "prompt_tokens", "completion_tokens", "total_tokens", "web_searches", "error_count", "avg_latency_ms" ], "properties": { "feature": { "type": "string", "description": "Metering feature / surface (`chat`, `compat_chat`, `compat_embed`, `rag_query`, …)." }, "model": { "type": "string" }, "calls": { "type": "integer", "minimum": 0 }, "prompt_tokens": { "type": "integer", "minimum": 0 }, "completion_tokens": { "type": "integer", "minimum": 0 }, "total_tokens": { "type": "integer", "minimum": 0 }, "web_searches": { "type": "integer", "minimum": 0, "description": "Web searches the calls in this group ran (public research)." }, "error_count": { "type": "integer", "minimum": 0, "description": "Calls with success = false in this group." }, "avg_latency_ms": { "type": "integer", "minimum": 0 } } } }, "group_count": { "type": "integer", "minimum": 0 }, "totals": { "type": "object", "required": [ "calls", "prompt_tokens", "completion_tokens", "total_tokens", "web_searches", "error_count" ], "properties": { "calls": { "type": "integer", "minimum": 0 }, "prompt_tokens": { "type": "integer", "minimum": 0 }, "completion_tokens": { "type": "integer", "minimum": 0 }, "total_tokens": { "type": "integer", "minimum": 0 }, "web_searches": { "type": "integer", "minimum": 0, "description": "Web searches across every group in the window." }, "error_count": { "type": "integer", "minimum": 0 } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_usageAggregate_Usage", "resource_uri": "yf://agents/usage", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -G -H \"Authorization: Bearer $JWT\" \\\n --data-urlencode \"start_date=2026-06-01\" \\\n --data-urlencode \"end_date=2026-06-13\" \\\n https://agents.yieldfabric.com/api/usage/aggregate\n" } ], "x-related": [ { "operationId": "usageSummary_Usage", "relation": "sibling" }, { "operationId": "usageDetail_Usage", "relation": "sibling" } ] } }, "/api/usage/calls/{usage_event_id}/log": { "get": { "operationId": "getCallLog_Usage", "x-method": "GET", "x-path": "/api/usage/calls/{usage_event_id}/log", "x-handler": "handlers::usage::get_call_log", "tags": [ "Economies & Usage" ], "summary": "Audit view — the exact prompt and output of one metered LLM call.", "description": "Returns the full prompt messages and output persisted for one\n`llm_usage` event — the per-call audit trail behind the token\nnumbers. Pair with `GET /api/usage/detail?thread_id=…`: each\ndetail row's `id` is the `usage_event_id` here.\n\nOwnership-scoped like every usage read: non-staff callers may only\nopen calls whose usage event belongs to their entity (else 403).\n404 when the event id is unknown, when call logging is disabled\n(`agents.metering.call_log_enabled: false`), or when the row aged\nout of retention (`call_log_retention_days`, default 30).\n\nAuth: bearer JWT. Read-only.\n", "parameters": [ { "name": "usage_event_id", "in": "path", "required": true, "description": "The `id` of an llm_usage event (from `GET /api/usage/detail`).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The persisted prompt + output for the call.", "content": { "application/json": { "schema": { "type": "object", "description": "The audit view of one metered call: the exact prompt messages sent upstream and the output produced. Persisted to `llm_call_log` when `agents.metering.call_log_enabled` is on (default), retained per `call_log_retention_days` (default 30).", "required": [ "usage_event_id", "prompt_messages", "output" ], "properties": { "usage_event_id": { "type": "string", "format": "uuid" }, "prompt_messages": { "description": "The serialized prompt messages (JSON array as sent upstream)." }, "output": { "type": "string" }, "max_tokens_requested": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getCallLog_Usage", "resource_uri": "yf://agents/usage", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" \\\n https://agents.yieldfabric.com/api/usage/calls/$USAGE_EVENT_ID/log\n" } ], "x-related": [ { "operationId": "usageDetail_Usage", "relation": "sibling" }, { "operationId": "usageSummary_Usage", "relation": "sibling" } ] } }, "/api/usage/detail": { "get": { "operationId": "usageDetail_Usage", "x-method": "GET", "x-path": "/api/usage/detail", "x-handler": "handlers::usage::usage_detail", "tags": [ "Economies & Usage" ], "summary": "Raw LLM-usage events with per-call provenance.", "description": "Returns rows from `llm_usage` (one record per LLM call) including the request id,\ncall_type, model, prompt/completion/total tokens, latency, success bool, and\ncontext ids (document, kg, agent, thread, workflow). Use this for debugging,\naudit, or tracing a request id end-to-end across the substrate.\n\nPagination: `limit` (default 100, capped at 500) and `offset`. Date window\ninclusive on both ends.\n\nAuth: bearer JWT. Read-only. **Entity-scoped**: staff roles\n(SuperAdmin/Admin/Manager/Operator, or a service token) may filter\narbitrarily including the org-wide no-filter view; all other callers\nare pinned to their own entity — omitting `entity_id` scopes to\nself, and requesting another entity returns 403.\n", "parameters": [ { "name": "entity_id", "in": "query", "required": false, "description": "Filter to one entity. Staff may name any entity; non-staff only their own (else 403).", "schema": { "type": "string" } }, { "name": "working_group_id", "in": "query", "required": false, "description": "Filter to one working group.", "schema": { "type": "string", "format": "uuid" } }, { "name": "economy_id", "in": "query", "required": false, "description": "Filter to one economy.", "schema": { "type": "string" } }, { "name": "feature", "in": "query", "required": false, "description": "Filter to one feature label.", "schema": { "type": "string" } }, { "name": "request_id", "in": "query", "required": false, "description": "Look up a single request by its id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "thread_id", "in": "query", "required": false, "description": "Filter to one conversation thread. Group the returned events on `request_id` to reconstruct per-message token costs (all LLM calls of one chat invocation share a request_id).", "schema": { "type": "string", "format": "uuid" } }, { "name": "start_date", "in": "query", "required": false, "description": "Lower bound (YYYY-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "required": false, "description": "Upper bound (YYYY-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "description": "Max events to return (capped at 500).", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "`{ data: [...], count, limit, offset }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "count", "limit", "offset" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "One metered LLM call from `llm_usage`. All calls made while answering one chat message share a `request_id`; chat calls carry the conversation `thread_id` — group on `request_id` for per-message costs.", "required": [ "feature", "model", "call_type", "prompt_tokens", "cached_prompt_tokens", "completion_tokens", "total_tokens", "latency_ms", "success" ], "properties": { "id": { "type": [ "string", "null" ], "format": "uuid" }, "feature": { "type": "string" }, "entity_id": { "type": [ "string", "null" ] }, "working_group_id": { "type": [ "string", "null" ], "format": "uuid" }, "economy_id": { "type": [ "string", "null" ], "format": "uuid" }, "model": { "type": "string" }, "request_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Correlates every call of one handler invocation (one chat message)." }, "call_type": { "type": "string", "description": "`complete`, `complete_stream`, `complete_tools`, `embed`, …" }, "prompt_tokens": { "type": "integer", "minimum": 0 }, "cached_prompt_tokens": { "type": "integer", "minimum": 0, "description": "Provider-reported cached subset of prompt_tokens." }, "completion_tokens": { "type": "integer", "minimum": 0 }, "total_tokens": { "type": "integer", "minimum": 0 }, "web_searches": { "type": "integer", "minimum": 0, "description": "Web searches the call ran (public research); billed beside the tokens." }, "latency_ms": { "type": "integer", "minimum": 0 }, "success": { "type": "boolean" }, "error_type": { "type": [ "string", "null" ] }, "document_id": { "type": [ "string", "null" ], "format": "uuid" }, "kg_id": { "type": [ "string", "null" ], "format": "uuid" }, "agent_id": { "type": [ "string", "null" ] }, "thread_id": { "type": [ "string", "null" ], "format": "uuid" }, "workflow_id": { "type": [ "string", "null" ], "format": "uuid" }, "sponsor_group_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Session payer override for platform-sponsored usage." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } } }, "count": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 0 }, "offset": { "type": "integer", "minimum": 0 } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_usageDetail_Usage", "resource_uri": "yf://agents/usage", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -G \\\n -H \"Authorization: Bearer $JWT\" \\\n --data-urlencode \"feature=user_note\" \\\n --data-urlencode \"limit=50\" \\\n https://agents.yieldfabric.com/api/usage/detail\n" } ], "x-related": [ { "operationId": "usageSummary_Usage", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/api/usage/export": { "get": { "operationId": "usageExport_Usage", "x-method": "GET", "x-path": "/api/usage/export", "x-handler": "handlers::usage::usage_export", "tags": [ "Economies & Usage" ], "summary": "Export stable LLM usage for billing ingestion", "description": "Staff/service-token keyset export of metered provider calls older than two minutes. Includes provider-reported cached prompt tokens, session sponsorship, context pointers, resolved custom AI rate/agent author, and priced cross-group knowledge retrieval. Cursor ordering is `(created_at, id)`; consumers must persist the cursor atomically with their idempotent ingest.", "parameters": [ { "in": "query", "name": "after_created_at", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "after_id", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 500 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "rows" ], "properties": { "rows": { "type": "array", "items": { "type": "object", "description": "Billing-ingest row exported after the two-minute stability lag.", "required": [ "id", "feature", "model", "call_type", "prompt_tokens", "cached_prompt_tokens", "completion_tokens", "success", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "entity_id": { "type": [ "string", "null" ] }, "working_group_id": { "type": [ "string", "null" ], "format": "uuid" }, "auth_group_id": { "type": [ "string", "null" ], "format": "uuid" }, "economy_id": { "type": [ "string", "null" ], "format": "uuid" }, "feature": { "type": "string" }, "model": { "type": "string" }, "call_type": { "type": "string" }, "prompt_tokens": { "type": "integer", "minimum": 0 }, "cached_prompt_tokens": { "type": "integer", "minimum": 0, "description": "Provider-reported cached subset of prompt_tokens." }, "completion_tokens": { "type": "integer", "minimum": 0 }, "web_searches": { "type": "integer", "minimum": 0, "description": "Completed web searches the call ran (public research). Billing prices each as units of the LLM product at the token markup. Absent on older builds = 0." }, "success": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "request_id": { "type": [ "string", "null" ], "format": "uuid" }, "thread_id": { "type": [ "string", "null" ], "format": "uuid" }, "document_id": { "type": [ "string", "null" ], "format": "uuid" }, "kg_id": { "type": [ "string", "null" ], "format": "uuid" }, "agent_id": { "type": [ "string", "null" ] }, "workflow_id": { "type": [ "string", "null" ], "format": "uuid" }, "sponsor_group_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Group that pays for this sponsored session row." }, "unit_usd_per_minute": { "type": [ "number", "null" ] }, "rate_source": { "type": [ "string", "null" ], "enum": [ "room_agent", "agent", "room", null ] }, "agent_author_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Author beneficiary when rate_source is agent." }, "kg_access": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "kg_id": { "type": "string", "format": "uuid" }, "kg_name": { "type": [ "string", "null" ] }, "chars": { "type": "number" }, "usd_per_page": { "type": "number" }, "owner_working_group_id": { "type": [ "string", "null" ], "format": "uuid" }, "owner_auth_group_id": { "type": [ "string", "null" ], "format": "uuid" } } } } } } }, "next_cursor": { "type": [ "object", "null" ], "properties": { "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": [ "string", "null" ], "format": "uuid" } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_usageExport_Usage", "resource_uri": "yf://agents/usage", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/api/usage/export" } ], "x-related": [] } }, "/api/usage/summary": { "get": { "operationId": "usageSummary_Usage", "x-method": "GET", "x-path": "/api/usage/summary", "x-handler": "handlers::usage::usage_summary", "tags": [ "Economies & Usage" ], "summary": "Aggregated daily LLM-usage totals (call count, prompt/completion/total tokens).", "description": "Returns the daily totals materialised in `llm_usage_daily` (one row per\n(date, entity_id, working_group_id, economy_id, feature, model) tuple). Query\nparams narrow on any combination of those dimensions plus an explicit\n`start_date`/`end_date` window. Ordering: by date descending then total_tokens\ndescending, capped at 1000 rows.\n\nAuth: bearer JWT. Read-only. **Entity-scoped**: staff roles\n(SuperAdmin/Admin/Manager/Operator, or a service token) may filter\narbitrarily including the org-wide no-filter view; all other callers\nare pinned to their own entity — omitting `entity_id` scopes to\nself, and requesting another entity returns 403.\n", "parameters": [ { "name": "entity_id", "in": "query", "required": false, "description": "Filter to one entity. Staff may name any entity; non-staff only their own (else 403).", "schema": { "type": "string" } }, { "name": "working_group_id", "in": "query", "required": false, "description": "Filter to one working group.", "schema": { "type": "string", "format": "uuid" } }, { "name": "economy_id", "in": "query", "required": false, "description": "Filter to one economy.", "schema": { "type": "string" } }, { "name": "feature", "in": "query", "required": false, "description": "Filter to one feature label (e.g. `user_note`, `rfi_match`, `analyze`).", "schema": { "type": "string" } }, { "name": "model", "in": "query", "required": false, "description": "Filter to one model identifier.", "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "required": false, "description": "Lower bound (YYYY-MM-DD, inclusive). Default `2020-01-01`.", "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "required": false, "description": "Upper bound (YYYY-MM-DD, inclusive). Default `2099-12-31`.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "`{ data: [{ date, entity_id, working_group_id, economy_id, feature, model, call_count, total_prompt_tokens, total_completion_tokens, total_tokens }], count }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "count" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "One daily rollup row from `llm_usage_daily` — the grain is (date, entity_id, working_group_id, economy_id, feature, model). Rollups are advanced by a background task (~every 5 minutes) and aggregate successful calls.", "required": [ "date", "feature", "model", "call_count", "total_prompt_tokens", "total_completion_tokens", "total_tokens" ], "properties": { "date": { "type": "string", "format": "date" }, "entity_id": { "type": [ "string", "null" ] }, "working_group_id": { "type": [ "string", "null" ] }, "economy_id": { "type": [ "string", "null" ] }, "feature": { "type": "string", "description": "Metering feature label (`chat`, `compat_chat`, `rag_query`, …)." }, "model": { "type": "string", "description": "Upstream deployment/model name." }, "call_count": { "type": "integer", "minimum": 0 }, "total_prompt_tokens": { "type": "integer", "minimum": 0 }, "total_completion_tokens": { "type": "integer", "minimum": 0 }, "total_tokens": { "type": "integer", "minimum": 0 } } } }, "count": { "type": "integer", "minimum": 0 } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_usageSummary_Usage", "resource_uri": "yf://agents/usage", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -G \\\n -H \"Authorization: Bearer $JWT\" \\\n --data-urlencode \"start_date=2027-05-01\" \\\n --data-urlencode \"end_date=2027-05-17\" \\\n https://agents.yieldfabric.com/api/usage/summary\n" } ], "x-related": [ { "operationId": "usageDetail_Usage", "relation": "sibling" }, { "guide": "conversation", "relation": "concept" } ] } }, "/chat": { "post": { "operationId": "assistantChatHandler_Misc", "x-method": "POST", "x-path": "/chat", "x-handler": "handlers::assistant_chat_handler", "tags": [ "Chat" ], "summary": "UI-context-aware assistant chat (SSE or JSON)", "description": "Runs an authenticated conversation through one execution and persistence\npath for JSON and SSE. A supplied thread is authorized using its stored\ngroup and private-owner scope, including required room terms. A supplied\ngroup is a consistency assertion; it cannot authorize a different thread.\nCaller-supplied context KGs are checked before rendering or inference.\n\nOmit thread_id to create a private conversation in the requested group\nor the caller's personal workspace. The returned ID is resumable. The\nserver saves one human message and one assistant outcome per accepted\nrequest. Persisted history is authoritative even on the first turn;\nconversationHistory is accepted for compatibility but ignored. Failed and\ninterrupted assistant outcomes remain visible in history but do not enter\nfuture model context. Clients must not separately post the human message\nbefore calling this endpoint.\n\nThe one thread-less case is an ephemeral chat: `context: \"fabric\"` with no\nthread_id — the terminal's ambient \"dream\" voice, which sends a\nself-contained systemPrompt on a timer and never reads a reply back. It\nis authorized, terms-gated and attributed to the same workspace as any\nother chat, but no thread is created, nothing is loaded as prior context,\nnothing is persisted, and the reply carries `thread_id: null`. A supplied\nthread_id is always resumed and persisted, whatever the context label.\n\nasAgent resolves the visible registry specification, including model, prompt,\neffort, output limit, tool grants and caller-private memory. Empty grants\ndeny tools. The default assistant supports configured model selection and\nnative knowledge tools when AGENTS_AGENTIC_CHAT is enabled. Builder and\nmarket-research surfaces retain their domain adapters when no agent is selected.\n\nAccept: text/event-stream returns incremental chunks/tool steps and an\nexplicit is_final frame with the complete answer, sender, sources and\ncompletion outcome. JSON carries the same final outcome. A disconnected\nreader does not cancel authorized inference; reopen history to recover\nits saved result. Partial results and provider failures never become a\nsuccessful completion just because the stream closed. Bearer identity is\ntaken from the authenticated header, never from UI-context token fields.\n", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "description": "Mirrors `ChatRequest` in src/service/types.rs.\n", "properties": { "message": { "type": "string", "minLength": 1, "description": "Nonblank input; at most 64000 UTF-8 bytes." }, "context": { "type": "string", "default": "chat", "description": "Caller surface label. `fabric` with no `thread_id` marks an ephemeral chat — no thread is created or persisted and the reply's `thread_id` is null; every other value keeps the stored thread." }, "thread_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Existing authorized thread. Omit to create a private conversation in the requested group or the caller's personal workspace (or, with `context: fabric`, to run an ephemeral chat with no thread at all)." }, "uiContext": { "description": "Arbitrary JSON value." }, "viewContext": { "oneOf": [ { "type": "object", "description": "Validated dashboard context accepted by the public macro assistant. The\nhandler allow-lists tab ids and validates compare-series values before\nusing them as prompt hints.\n", "properties": { "tab": { "type": [ "string", "null" ] }, "compareSeries": { "type": "array", "items": { "type": "string" }, "default": [] }, "compareMode": { "type": [ "string", "null" ], "description": "Recognized client modes are `pct`, `index`, and `levels`." }, "compareRange": { "type": [ "string", "null" ] }, "compareSpread": { "type": "boolean", "default": false }, "compareShift": { "type": [ "integer", "null" ], "format": "int64" } } }, { "type": "null" } ] }, "workingGroupId": { "type": [ "string", "null" ] }, "kgId": { "type": [ "string", "null" ] }, "systemPrompt": { "type": [ "string", "null" ] }, "conversationHistory": { "description": "Accepted for compatibility but ignored; persisted thread messages are the only prior conversation context.", "deprecated": true, "oneOf": [ { "type": "array", "items": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string" }, "content": { "type": "string" } } } }, { "type": "null" } ] }, "reasoning": { "type": [ "boolean", "null" ], "description": "False omits automatic retrieval tools for the default assistant. A selected agent retains its configured tools and effort; no intent-classifier call is performed." }, "skipRag": { "type": "boolean", "default": false }, "asAgent": { "type": [ "string", "null" ], "description": "Invoke a caller-visible registered agent with its composed prompt, configured model, effort, output limit, grants and caller-private memory. Unknown agents return 404." }, "model": { "type": [ "string", "null" ], "description": "Which configured chat model serves this request: a registry id (`default`, `mini`) or a deployment name, case-insensitively. Unknown values are a 400 listing the servable models (see `GET /api/models`). Omit for the deployment default. An explicit model selector on the selected agent takes precedence." }, "maxOutputTokens": { "type": [ "integer", "null" ], "minimum": 1, "description": "Per-request output-token cap (server-clamped to 32000). Omit to use api.yieldfabric.com for the default assistant. Selected agents also enforce their own cap." }, "temperature": { "type": [ "number", "null" ], "description": "Sampling temperature, forwarded verbatim when present. Models that reject explicit temperatures (reasoning family) surface the upstream error. Omit for the upstream default." } } }, "examples": { "plain": { "summary": "Plain chat turn (JSON response)", "value": { "message": "How does our credit policy treat sovereigns?", "thread_id": "7c1fc4a9-45bb-4220-b8bf-2c11e10bf211" } }, "ephemeral": { "summary": "Ambient voice — no thread is created or persisted", "value": { "message": "Share a thought or observation", "system_prompt": "You are Fabric — a sharp, concise AI voice in the terminal. ONE sentence.", "context": "fabric" } }, "with-ui-context": { "summary": "With UI context", "value": { "message": "Summarize this page", "ui_context": { "page_context": { "url": "/dashboard/credit" }, "view_mode": "dashboard" } } } } } } }, "responses": { "200": { "description": "Assistant reply. SSE stream when `Accept: text/event-stream`, otherwise plain JSON.", "content": { "application/json": { "schema": { "type": "object", "required": [ "response", "thread_id", "is_final", "completion" ], "properties": { "response": { "type": "string" }, "chunk": { "type": "string", "description": "Full answer on the terminal frame; incremental text on earlier SSE frames." }, "thread_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The resumable thread this turn was persisted into; null for an ephemeral chat (`context: fabric` without a thread), which persists nothing." }, "is_final": { "type": "boolean" }, "is_partial": { "type": "boolean" }, "model": { "type": "string" }, "sender": { "description": "Arbitrary JSON value." }, "sources": { "type": "array", "items": { "description": "Arbitrary JSON value." } }, "completion": { "type": "object", "required": [ "stop_reason", "truncated" ], "description": "The actual execution boundary, persisted with the assistant message.\nA truncated result needs follow-up; it is not a complete answer. Usage\naccumulates across server and durable browser tool rounds. Native provider\nreasoning state is never included in this public object.\n", "properties": { "stop_reason": { "type": "string", "enum": [ "answered", "awaiting_tool_results", "rounds_exhausted", "budget_exhausted", "output_limit", "empty", "failed", "interrupted" ] }, "truncated": { "type": "boolean" }, "rounds_used": { "type": "integer", "minimum": 0 }, "prompt_tokens": { "type": "integer", "minimum": 0 }, "completion_tokens": { "type": "integer", "minimum": 0 }, "reasoning_tokens": { "type": "integer", "minimum": 0, "description": "Subset of completion_tokens, never additional billed tokens." }, "elided_groups": { "type": "integer", "minimum": 0 }, "reused_calls": { "type": "integer", "minimum": 0 } } }, "error": { "type": "string", "description": "User-facing failure; a JSON failure responds with 502 and an SSE failure is in-band." } } } }, "text/event-stream": { "schema": { "type": "object", "description": "Each SSE event has an `event` name (the wire-level `event:` line) and a\n`data` JSON payload (the wire-level `data:` line, JSON-decoded). The exact\nschemas for each event variant are documented in the operation's\n`x-event-types` extension.\n", "required": [ "event", "data" ], "properties": { "event": { "type": "string", "description": "Event name from the operation's `x-event-types` enumeration." }, "data": { "description": "JSON payload. Shape depends on `event` — see `x-event-types`." }, "id": { "type": [ "string", "null" ], "description": "Optional SSE event id (used for resume cursors)." } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "429": { "description": "Per-entity concurrency, per-entity recent starts, or instance capacity exceeded. Retry after the indicated number of seconds.", "headers": { "Retry-After": { "description": "Suggested retry delay in seconds; capacity may still be busy at retry time.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "inference_limit" ] } } } } } }, "502": { "description": "The JSON reply could not be completed or saved. SSE callers receive an explicit terminal error frame." } }, "x-mcp": { "tool_name": "yieldfabric_agents_assistantChatHandler_Misc", "resource_uri": "yf://agents/misc", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"message\":\"hello\"}' \\\n https://agents.yieldfabric.com/chat\n" } ], "x-related": [ { "operationId": "chatHistoryHandler_Misc", "relation": "sibling" }, { "guide": "streaming", "relation": "concept" } ] } }, "/chat/history/{thread_id}": { "get": { "operationId": "chatHistoryHandler_Misc", "x-method": "GET", "x-path": "/chat/history/{thread_id}", "x-handler": "handlers::chat_history_handler", "tags": [ "Chat" ], "summary": "Return assistant-chat history for a thread", "description": "Returns recent messages from the canonical authorized discussion thread in\nchronological order, with sender, sources and completion metadata. Checks\nthe stored group, membership/role, room terms and private-thread owner.\nThe legacy unscoped conversation_history table is not exposed. The optional\ncontext parameter is accepted for wire compatibility and ignored.\nAuth: bearer JWT.\n", "parameters": [ { "name": "thread_id", "in": "path", "required": true, "description": "Saved discussion thread UUID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of recent rows to return; server-clamped to 1–200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "context", "in": "query", "required": false, "description": "Legacy parameter, ignored; only the authorized thread is read.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Conversation history.", "content": { "application/json": { "schema": { "type": "object", "required": [ "messages" ], "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "role": { "type": "string" }, "content": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "sender": { "description": "Arbitrary JSON value." }, "sources": { "type": "array", "items": { "description": "Arbitrary JSON value." } }, "completion": { "oneOf": [ { "type": "object", "required": [ "stop_reason", "truncated" ], "description": "The actual execution boundary, persisted with the assistant message.\nA truncated result needs follow-up; it is not a complete answer. Usage\naccumulates across server and durable browser tool rounds. Native provider\nreasoning state is never included in this public object.\n", "properties": { "stop_reason": { "type": "string", "enum": [ "answered", "awaiting_tool_results", "rounds_exhausted", "budget_exhausted", "output_limit", "empty", "failed", "interrupted" ] }, "truncated": { "type": "boolean" }, "rounds_used": { "type": "integer", "minimum": 0 }, "prompt_tokens": { "type": "integer", "minimum": 0 }, "completion_tokens": { "type": "integer", "minimum": 0 }, "reasoning_tokens": { "type": "integer", "minimum": 0, "description": "Subset of completion_tokens, never additional billed tokens." }, "elided_groups": { "type": "integer", "minimum": 0 }, "reused_calls": { "type": "integer", "minimum": 0 } } }, { "type": "null" } ] }, "msg_references": { "description": "Arbitrary JSON value." } } } } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_chatHistoryHandler_Misc", "resource_uri": "yf://agents/misc", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/chat/history/{thread_id}?limit=50\"" } ], "x-related": [ { "operationId": "assistantChatHandler_Misc", "relation": "sibling" } ] } }, "/chunks/{chunk_id}": { "get": { "operationId": "getChunk_Kgs", "x-method": "GET", "x-path": "/chunks/{chunk_id}", "x-handler": "handlers::chunks::get_chunk", "tags": [ "Knowledge Graphs" ], "summary": "Fetch a uniquely resolvable chunk (legacy compatibility route).", "description": "Compatibility adapter for clients that only carry a chunk UUID. It searches\nexclusively inside knowledge graphs the caller may read. One accessible\nmatch returns the unchanged chunk-detail response; no accessible match is\n404, and multiple accessible matches are 409 because frame ids are unique\nonly per KG. New clients should call\n`GET /kgs/{kg_id}/chunks/{chunk_id}`. Auth: bearer JWT.\n", "parameters": [ { "name": "chunk_id", "in": "path", "required": true, "description": "Chunk id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Chunk content + neighbours.", "content": { "application/json": { "schema": { "type": "object", "required": [ "chunk_id", "content", "position" ], "properties": { "chunk_id": { "type": "string", "format": "uuid" }, "content": { "type": "string" }, "position": { "type": "integer", "minimum": 0 }, "document_id": { "type": [ "string", "null" ], "format": "uuid" }, "document_label": { "type": [ "string", "null" ] }, "prev_chunk_id": { "type": [ "string", "null" ], "format": "uuid" }, "next_chunk_id": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "409": { "description": "Conflicting state (e.g. step already completed, intent already cancelled, duplicate idempotency key with different body).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getChunk_Kgs", "resource_uri": "yf://agents/chunks/{chunk_id}", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/chunks/$CHUNK_ID\"" } ], "x-related": [ { "operationId": "updateChunk_Kgs", "relation": "sibling" }, { "operationId": "getScopedChunk_Kgs", "relation": "successor" }, { "operationId": "getStitchedDocument_Kgs", "relation": "sibling" }, { "operationId": "getKgChunks_Kgs", "relation": "sibling" }, { "guide": "knowledge", "relation": "concept" } ] }, "post": { "operationId": "updateChunk_Kgs", "x-method": "POST", "x-path": "/chunks/{chunk_id}", "x-handler": "handlers::chunks::update_chunk", "tags": [ "Knowledge Graphs" ], "summary": "Edit a uniquely resolvable chunk (legacy compatibility route).", "description": "Compatibility adapter for clients that only carry a chunk UUID. It first\nresolves the id inside the caller's readable KGs. No match is 404; multiple\naccessible matches are 409 and require the canonical\n`POST /kgs/{kg_id}/chunks/{chunk_id}` route. The selected KG then enforces\nthe same write-role check and returns the existing response shape. It never\nupdates or triggers extraction in another KG that happens to reuse the same\nframe id. Auth: bearer JWT.\n", "parameters": [ { "name": "chunk_id", "in": "path", "required": true, "description": "Chunk id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string" } } }, "examples": { "typo_fix": { "summary": "Fix a typo in a paragraph", "value": { "content": "Lender ACME Capital LLC agrees to lend USD 5,000,000 to Beta Industries Inc." } } } } } }, "responses": { "200": { "description": "Chunk updated; re-extraction completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "chunk_id", "affected_kgs", "pending_run_ids", "orphaned_nodes" ], "properties": { "chunk_id": { "type": "string", "format": "uuid" }, "affected_kgs": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "pending_run_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "orphaned_nodes": { "type": "integer", "minimum": 0 } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "409": { "description": "Ambiguous legacy id, or another extraction is in flight on the selected KG.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_updateChunk_Kgs", "resource_uri": "yf://agents/chunks/{chunk_id}", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" \\\n \"https://agents.yieldfabric.com/chunks/$CHUNK_ID\" \\\n -d '{\"content\": \"Updated note text.\"}'\n" } ], "x-related": [ { "operationId": "getChunk_Kgs", "relation": "sibling" }, { "operationId": "updateScopedChunk_Kgs", "relation": "successor" }, { "operationId": "createChunk_Kgs", "relation": "sibling" }, { "operationId": "pruneOrphans_Kgs", "relation": "sibling" }, { "guide": "knowledge", "relation": "concept" } ] } }, "/deal-templates": { "get": { "operationId": "listMyDealTemplates_DealTemplates", "x-method": "GET", "x-path": "/deal-templates", "x-handler": "wg_templates::list_my_deal_templates", "tags": [ "Deal Templates" ], "summary": "List the caller's deal-template versions", "description": "Returns up to 200 templates owned by the authenticated entity. Rows are\nordered by template name and then newest version first. Draft, approved,\nand retired versions are all included; this is the owner's authoring view,\nnot the room-visible approved catalog.\n", "parameters": [], "responses": { "200": { "description": "The caller's template versions.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "templates" ], "properties": { "templates": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "owner_entity_id", "name", "extends", "version", "status", "spec", "created_at", "approved_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "owner_entity_id": { "type": "string" }, "name": { "type": "string" }, "extends": { "type": "string" }, "version": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "draft", "approved", "retired" ] }, "spec": { "type": "object", "additionalProperties": false, "required": [ "name", "extends" ], "description": "Canonical template definition. At least one `panel` group or `cps` item\nis required, field and CP ids must be unique, and there may be no more\nthan 120 fields across all panel groups. `extends` must resolve to a\nplatform deal-type id; the token pattern alone is not sufficient.\n", "anyOf": [ { "required": [ "panel" ], "properties": { "panel": { "type": "array", "minItems": 1 } } }, { "required": [ "cps" ], "properties": { "cps": { "type": "array", "minItems": 1 } } } ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "extends": { "type": "string", "pattern": "^[a-z0-9_]{1,48}$", "description": "Existing platform deal-type id, for example `abs` or `repo`." }, "description": { "type": [ "string", "null" ], "maxLength": 300 }, "panel": { "type": "array", "maxItems": 12, "default": [], "items": { "type": "object", "additionalProperties": false, "required": [ "category", "title", "fields" ], "properties": { "category": { "type": "string", "pattern": "^[a-z0-9_]{1,48}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "fields": { "type": "array", "minItems": 1, "maxItems": 24, "default": [], "items": { "type": "object", "additionalProperties": false, "required": [ "id", "label" ], "properties": { "id": { "type": "string", "pattern": "^[a-z0-9_]{1,48}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "facet": { "type": [ "string", "null" ], "enum": [ "terms", "financialActions", "tranches", "poolFacts", "keyDates", "dealParties", null ] }, "key": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$" }, "role": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$" }, "hint": { "type": [ "string", "null" ], "maxLength": 300 }, "required": { "type": "boolean", "default": false }, "confirm_role": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$" }, "confirmRole": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$", "description": "Input alias for `confirm_role`; responses use snake_case." } } } } } } }, "cps": { "type": "array", "maxItems": 64, "default": [], "items": { "type": "object", "additionalProperties": false, "required": [ "id", "title" ], "properties": { "id": { "type": "string", "pattern": "^[a-z0-9_]{1,48}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "source_hint": { "type": [ "string", "null" ], "maxLength": 120 }, "sourceHint": { "type": [ "string", "null" ], "maxLength": 120, "description": "Input alias for `source_hint`; responses use snake_case." }, "responsible_role": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$" }, "responsibleRole": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$", "description": "Input alias for `responsible_role`; responses use snake_case." }, "confirm_role": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$" }, "confirmRole": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$", "description": "Input alias for `confirm_role`; responses use snake_case." }, "closing_dependency": { "type": "boolean", "default": false }, "closingDependency": { "type": "boolean", "description": "Input alias for `closing_dependency`; responses use snake_case." } } } } } }, "created_at": { "type": "string", "format": "date-time" }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } } } } }, "401": { "description": "Missing or invalid bearer credential.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Database read failed.", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listMyDealTemplates_DealTemplates", "resource_uri": "yf://agents/deal-templates", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/deal-templates" } ], "x-related": [ { "operationId": "createDealTemplate_DealTemplates", "relation": "create" }, { "operationId": "listRoomDealTemplates_DealTemplates", "relation": "room-catalog" } ] }, "post": { "operationId": "createDealTemplate_DealTemplates", "x-method": "POST", "x-path": "/deal-templates", "x-handler": "wg_templates::create_deal_template", "tags": [ "Deal Templates" ], "summary": "Create a draft deal-template version", "description": "Validates a JSON or YAML template definition against the closed deal facet\nvocabulary and the platform deal-type registry, then creates the next draft\nversion for `(caller, template name)`. Approved versions are immutable; an\nedit is represented by another call that creates v2, v3, and so on.\n\nThis operation is not retry-idempotent: repeating a successful request\ncreates another version. Concurrent creates for the same owner/name may\nreturn 409; reload the owner's list before deciding whether to retry.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "description": "Supply the definition as JSON in `spec` or as a YAML string in\n`spec_yaml`. When both are present, `spec` is authoritative. The decoded\ndefinition is limited to 128 KiB.\n", "anyOf": [ { "required": [ "spec" ] }, { "required": [ "spec_yaml" ] } ], "properties": { "spec": { "type": "object", "additionalProperties": false, "required": [ "name", "extends" ], "description": "Canonical template definition. At least one `panel` group or `cps` item\nis required, field and CP ids must be unique, and there may be no more\nthan 120 fields across all panel groups. `extends` must resolve to a\nplatform deal-type id; the token pattern alone is not sufficient.\n", "anyOf": [ { "required": [ "panel" ], "properties": { "panel": { "type": "array", "minItems": 1 } } }, { "required": [ "cps" ], "properties": { "cps": { "type": "array", "minItems": 1 } } } ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "extends": { "type": "string", "pattern": "^[a-z0-9_]{1,48}$", "description": "Existing platform deal-type id, for example `abs` or `repo`." }, "description": { "type": [ "string", "null" ], "maxLength": 300 }, "panel": { "type": "array", "maxItems": 12, "default": [], "items": { "type": "object", "additionalProperties": false, "required": [ "category", "title", "fields" ], "properties": { "category": { "type": "string", "pattern": "^[a-z0-9_]{1,48}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "fields": { "type": "array", "minItems": 1, "maxItems": 24, "default": [], "items": { "type": "object", "additionalProperties": false, "required": [ "id", "label" ], "properties": { "id": { "type": "string", "pattern": "^[a-z0-9_]{1,48}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "facet": { "type": [ "string", "null" ], "enum": [ "terms", "financialActions", "tranches", "poolFacts", "keyDates", "dealParties", null ] }, "key": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$" }, "role": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$" }, "hint": { "type": [ "string", "null" ], "maxLength": 300 }, "required": { "type": "boolean", "default": false }, "confirm_role": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$" }, "confirmRole": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$", "description": "Input alias for `confirm_role`; responses use snake_case." } } } } } } }, "cps": { "type": "array", "maxItems": 64, "default": [], "items": { "type": "object", "additionalProperties": false, "required": [ "id", "title" ], "properties": { "id": { "type": "string", "pattern": "^[a-z0-9_]{1,48}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "source_hint": { "type": [ "string", "null" ], "maxLength": 120 }, "sourceHint": { "type": [ "string", "null" ], "maxLength": 120, "description": "Input alias for `source_hint`; responses use snake_case." }, "responsible_role": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$" }, "responsibleRole": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$", "description": "Input alias for `responsible_role`; responses use snake_case." }, "confirm_role": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$" }, "confirmRole": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$", "description": "Input alias for `confirm_role`; responses use snake_case." }, "closing_dependency": { "type": "boolean", "default": false }, "closingDependency": { "type": "boolean", "description": "Input alias for `closing_dependency`; responses use snake_case." } } } } } }, "spec_yaml": { "type": "string", "maxLength": 131072 } } }, "examples": { "json": { "value": { "spec": { "name": "AMAL Term Standard", "extends": "abs", "panel": [ { "category": "core_identity", "title": "Core deal identity", "fields": [ { "id": "issuer", "label": "Issuer", "facet": "dealParties", "role": "issuer", "required": true } ] } ], "cps": [ { "id": "cp_ratings", "title": "Ratings delivered", "responsible_role": "arranger", "closing_dependency": true } ] } } } } } } }, "responses": { "200": { "description": "Newly created draft version.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "id", "owner_entity_id", "name", "extends", "version", "status", "spec", "created_at", "approved_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "owner_entity_id": { "type": "string" }, "name": { "type": "string" }, "extends": { "type": "string" }, "version": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "draft", "approved", "retired" ] }, "spec": { "type": "object", "additionalProperties": false, "required": [ "name", "extends" ], "description": "Canonical template definition. At least one `panel` group or `cps` item\nis required, field and CP ids must be unique, and there may be no more\nthan 120 fields across all panel groups. `extends` must resolve to a\nplatform deal-type id; the token pattern alone is not sufficient.\n", "anyOf": [ { "required": [ "panel" ], "properties": { "panel": { "type": "array", "minItems": 1 } } }, { "required": [ "cps" ], "properties": { "cps": { "type": "array", "minItems": 1 } } } ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "extends": { "type": "string", "pattern": "^[a-z0-9_]{1,48}$", "description": "Existing platform deal-type id, for example `abs` or `repo`." }, "description": { "type": [ "string", "null" ], "maxLength": 300 }, "panel": { "type": "array", "maxItems": 12, "default": [], "items": { "type": "object", "additionalProperties": false, "required": [ "category", "title", "fields" ], "properties": { "category": { "type": "string", "pattern": "^[a-z0-9_]{1,48}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "fields": { "type": "array", "minItems": 1, "maxItems": 24, "default": [], "items": { "type": "object", "additionalProperties": false, "required": [ "id", "label" ], "properties": { "id": { "type": "string", "pattern": "^[a-z0-9_]{1,48}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "facet": { "type": [ "string", "null" ], "enum": [ "terms", "financialActions", "tranches", "poolFacts", "keyDates", "dealParties", null ] }, "key": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$" }, "role": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$" }, "hint": { "type": [ "string", "null" ], "maxLength": 300 }, "required": { "type": "boolean", "default": false }, "confirm_role": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$" }, "confirmRole": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$", "description": "Input alias for `confirm_role`; responses use snake_case." } } } } } } }, "cps": { "type": "array", "maxItems": 64, "default": [], "items": { "type": "object", "additionalProperties": false, "required": [ "id", "title" ], "properties": { "id": { "type": "string", "pattern": "^[a-z0-9_]{1,48}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "source_hint": { "type": [ "string", "null" ], "maxLength": 120 }, "sourceHint": { "type": [ "string", "null" ], "maxLength": 120, "description": "Input alias for `source_hint`; responses use snake_case." }, "responsible_role": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$" }, "responsibleRole": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$", "description": "Input alias for `responsible_role`; responses use snake_case." }, "confirm_role": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$" }, "confirmRole": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$", "description": "Input alias for `confirm_role`; responses use snake_case." }, "closing_dependency": { "type": "boolean", "default": false }, "closingDependency": { "type": "boolean", "description": "Input alias for `closing_dependency`; responses use snake_case." } } } } } }, "created_at": { "type": "string", "format": "date-time" }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "400": { "description": "The template definition is absent, malformed, out of bounds, or references an unknown deal type/facet.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing or invalid bearer credential.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "A concurrent request allocated the same next version; reload and retry if another version is still needed.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "422": { "description": "JSON was syntactically valid but could not be deserialized as the request shape.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Serialization or database write failed.", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_createDealTemplate_DealTemplates", "resource_uri": "yf://agents/deal-templates", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"spec\":{\"name\":\"AMAL Term Standard\",\"extends\":\"abs\",\"cps\":[{\"id\":\"cp_ratings\",\"title\":\"Ratings delivered\"}]}}' \\\n https://agents.yieldfabric.com/deal-templates\n" } ], "x-related": [ { "operationId": "listMyDealTemplates_DealTemplates", "relation": "list" }, { "operationId": "approveDealTemplate_DealTemplates", "relation": "next-step" } ] } }, "/deal-templates/{id}/approve": { "post": { "operationId": "approveDealTemplate_DealTemplates", "x-method": "POST", "x-path": "/deal-templates/{id}/approve", "x-handler": "wg_templates::approve_deal_template", "tags": [ "Deal Templates" ], "summary": "Approve an owned draft template", "description": "Performs the owner-only `draft` to `approved` transition and stamps the\napproval time. An approved template becomes visible in rooms where its\nowner is an active member. The handler deliberately returns the same 404\nfor an unknown id, a template owned by another entity, and an invalid\ncurrent state.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Deal-template row id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Approved template row.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "id", "owner_entity_id", "name", "extends", "version", "status", "spec", "created_at", "approved_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "owner_entity_id": { "type": "string" }, "name": { "type": "string" }, "extends": { "type": "string" }, "version": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "draft", "approved", "retired" ] }, "spec": { "type": "object", "additionalProperties": false, "required": [ "name", "extends" ], "description": "Canonical template definition. At least one `panel` group or `cps` item\nis required, field and CP ids must be unique, and there may be no more\nthan 120 fields across all panel groups. `extends` must resolve to a\nplatform deal-type id; the token pattern alone is not sufficient.\n", "anyOf": [ { "required": [ "panel" ], "properties": { "panel": { "type": "array", "minItems": 1 } } }, { "required": [ "cps" ], "properties": { "cps": { "type": "array", "minItems": 1 } } } ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "extends": { "type": "string", "pattern": "^[a-z0-9_]{1,48}$", "description": "Existing platform deal-type id, for example `abs` or `repo`." }, "description": { "type": [ "string", "null" ], "maxLength": 300 }, "panel": { "type": "array", "maxItems": 12, "default": [], "items": { "type": "object", "additionalProperties": false, "required": [ "category", "title", "fields" ], "properties": { "category": { "type": "string", "pattern": "^[a-z0-9_]{1,48}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "fields": { "type": "array", "minItems": 1, "maxItems": 24, "default": [], "items": { "type": "object", "additionalProperties": false, "required": [ "id", "label" ], "properties": { "id": { "type": "string", "pattern": "^[a-z0-9_]{1,48}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "facet": { "type": [ "string", "null" ], "enum": [ "terms", "financialActions", "tranches", "poolFacts", "keyDates", "dealParties", null ] }, "key": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$" }, "role": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$" }, "hint": { "type": [ "string", "null" ], "maxLength": 300 }, "required": { "type": "boolean", "default": false }, "confirm_role": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$" }, "confirmRole": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$", "description": "Input alias for `confirm_role`; responses use snake_case." } } } } } } }, "cps": { "type": "array", "maxItems": 64, "default": [], "items": { "type": "object", "additionalProperties": false, "required": [ "id", "title" ], "properties": { "id": { "type": "string", "pattern": "^[a-z0-9_]{1,48}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "source_hint": { "type": [ "string", "null" ], "maxLength": 120 }, "sourceHint": { "type": [ "string", "null" ], "maxLength": 120, "description": "Input alias for `source_hint`; responses use snake_case." }, "responsible_role": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$" }, "responsibleRole": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$", "description": "Input alias for `responsible_role`; responses use snake_case." }, "confirm_role": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$" }, "confirmRole": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$", "description": "Input alias for `confirm_role`; responses use snake_case." }, "closing_dependency": { "type": "boolean", "default": false }, "closingDependency": { "type": "boolean", "description": "Input alias for `closing_dependency`; responses use snake_case." } } } } } }, "created_at": { "type": "string", "format": "date-time" }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "400": { "description": "The path id is not a UUID.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing or invalid bearer credential.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Template absent, not owned by the caller, or not currently a draft.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Database transition failed.", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_approveDealTemplate_DealTemplates", "resource_uri": "yf://agents/deal-templates/{id}", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/deal-templates/$TEMPLATE_ID/approve" } ], "x-related": [ { "operationId": "createDealTemplate_DealTemplates", "relation": "prerequisite" }, { "operationId": "retireDealTemplate_DealTemplates", "relation": "lifecycle" } ] } }, "/deal-templates/{id}/retire": { "post": { "operationId": "retireDealTemplate_DealTemplates", "x-method": "POST", "x-path": "/deal-templates/{id}/retire", "x-handler": "wg_templates::retire_deal_template", "tags": [ "Deal Templates" ], "summary": "Retire an owned draft or approved template", "description": "Performs the owner-only `draft|approved` to `retired` transition. Retired\nrows remain in the owner's version history but no longer appear in room\ncatalogs. The handler deliberately returns the same 404 for an unknown id,\na template owned by another entity, and an invalid current state.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Deal-template row id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Retired template row.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "id", "owner_entity_id", "name", "extends", "version", "status", "spec", "created_at", "approved_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "owner_entity_id": { "type": "string" }, "name": { "type": "string" }, "extends": { "type": "string" }, "version": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "draft", "approved", "retired" ] }, "spec": { "type": "object", "additionalProperties": false, "required": [ "name", "extends" ], "description": "Canonical template definition. At least one `panel` group or `cps` item\nis required, field and CP ids must be unique, and there may be no more\nthan 120 fields across all panel groups. `extends` must resolve to a\nplatform deal-type id; the token pattern alone is not sufficient.\n", "anyOf": [ { "required": [ "panel" ], "properties": { "panel": { "type": "array", "minItems": 1 } } }, { "required": [ "cps" ], "properties": { "cps": { "type": "array", "minItems": 1 } } } ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "extends": { "type": "string", "pattern": "^[a-z0-9_]{1,48}$", "description": "Existing platform deal-type id, for example `abs` or `repo`." }, "description": { "type": [ "string", "null" ], "maxLength": 300 }, "panel": { "type": "array", "maxItems": 12, "default": [], "items": { "type": "object", "additionalProperties": false, "required": [ "category", "title", "fields" ], "properties": { "category": { "type": "string", "pattern": "^[a-z0-9_]{1,48}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "fields": { "type": "array", "minItems": 1, "maxItems": 24, "default": [], "items": { "type": "object", "additionalProperties": false, "required": [ "id", "label" ], "properties": { "id": { "type": "string", "pattern": "^[a-z0-9_]{1,48}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "facet": { "type": [ "string", "null" ], "enum": [ "terms", "financialActions", "tranches", "poolFacts", "keyDates", "dealParties", null ] }, "key": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$" }, "role": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$" }, "hint": { "type": [ "string", "null" ], "maxLength": 300 }, "required": { "type": "boolean", "default": false }, "confirm_role": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$" }, "confirmRole": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$", "description": "Input alias for `confirm_role`; responses use snake_case." } } } } } } }, "cps": { "type": "array", "maxItems": 64, "default": [], "items": { "type": "object", "additionalProperties": false, "required": [ "id", "title" ], "properties": { "id": { "type": "string", "pattern": "^[a-z0-9_]{1,48}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "source_hint": { "type": [ "string", "null" ], "maxLength": 120 }, "sourceHint": { "type": [ "string", "null" ], "maxLength": 120, "description": "Input alias for `source_hint`; responses use snake_case." }, "responsible_role": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$" }, "responsibleRole": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$", "description": "Input alias for `responsible_role`; responses use snake_case." }, "confirm_role": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$" }, "confirmRole": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$", "description": "Input alias for `confirm_role`; responses use snake_case." }, "closing_dependency": { "type": "boolean", "default": false }, "closingDependency": { "type": "boolean", "description": "Input alias for `closing_dependency`; responses use snake_case." } } } } } }, "created_at": { "type": "string", "format": "date-time" }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "400": { "description": "The path id is not a UUID.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing or invalid bearer credential.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Template absent, not owned by the caller, or not in draft/approved state.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Database transition failed.", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_retireDealTemplate_DealTemplates", "resource_uri": "yf://agents/deal-templates/{id}", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/deal-templates/$TEMPLATE_ID/retire" } ], "x-related": [ { "operationId": "listMyDealTemplates_DealTemplates", "relation": "list" }, { "operationId": "approveDealTemplate_DealTemplates", "relation": "lifecycle" } ] } }, "/dm": { "post": { "operationId": "getOrCreateDm_Misc", "x-method": "POST", "x-path": "/dm", "x-handler": "wg::get_or_create_dm", "tags": [ "Direct Messages" ], "summary": "Get or create a 1:1 DM conversation with a peer", "description": "Returns (creating if absent) the canonical DM group between the\ncaller and `peer_entity_id`. Identifies the DM by a sorted\n`dm:+` group name so the lookup is idempotent regardless of\ncall order. On first creation a 2-member, lightweight working group\nis provisioned and both peers added as `member`. The handler also\nensures the shared DM thread exists and returns its id. Auth:\nbearer JWT.\n", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "peer_entity_id" ], "properties": { "peer_entity_id": { "type": "string" }, "peer_display_name": { "type": [ "string", "null" ] } } }, "examples": { "peer": { "summary": "Open a DM with usr_bob", "value": { "peer_entity_id": "usr_bob", "peer_display_name": "Bob Trader" } } } } } }, "responses": { "200": { "description": "DM (group + thread + peer profile).", "content": { "application/json": { "schema": { "type": "object", "required": [ "group_id", "thread_id", "peer" ], "properties": { "group_id": { "type": "string", "format": "uuid" }, "thread_id": { "type": "string", "format": "uuid" }, "peer": { "type": "object", "required": [ "entity_id", "display_name" ], "properties": { "entity_id": { "type": "string" }, "display_name": { "type": "string" } } } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getOrCreateDm_Misc", "resource_uri": "yf://agents/misc", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"peer_entity_id\":\"usr_bob\"}' \\\n https://agents.yieldfabric.com/dm\n" } ], "x-related": [ { "operationId": "listDmConversations_Misc", "relation": "sibling" }, { "operationId": "postMessage_Threads", "relation": "next-step" }, { "guide": "threads", "relation": "concept" } ] } }, "/dm/conversations": { "get": { "operationId": "listDmConversations_Misc", "x-method": "GET", "x-path": "/dm/conversations", "x-handler": "wg::list_dm_conversations", "tags": [ "Direct Messages" ], "summary": "List the caller's DM conversations", "description": "Returns every DM group the caller participates in, ordered by latest\nactivity. Each row carries the peer's `entity_id` + `display_name`,\nthe thread id, an `unread_count` (messages after the caller's\n`last_read_message_id`), and the latest message preview. Auth:\nbearer JWT.\n", "parameters": [], "responses": { "200": { "description": "DM conversation list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "conversations" ], "properties": { "conversations": { "type": "array", "items": { "type": "object", "required": [ "group_id", "thread_id", "peer" ], "properties": { "group_id": { "type": "string", "format": "uuid" }, "thread_id": { "type": "string", "format": "uuid" }, "peer": { "type": "object", "required": [ "entity_id", "display_name" ], "properties": { "entity_id": { "type": "string" }, "display_name": { "type": "string" } } }, "last_message": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "content": { "type": "string" }, "sender_entity_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } ] }, "unread_count": { "type": "integer", "minimum": 0 } } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listDmConversations_Misc", "resource_uri": "yf://agents/misc", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/dm/conversations" } ], "x-related": [ { "operationId": "getOrCreateDm_Misc", "relation": "sibling" }, { "guide": "threads", "relation": "concept" } ] } }, "/documents/process": { "post": { "operationId": "processDocument_Misc", "x-method": "POST", "x-path": "/documents/process", "x-handler": "handlers::process_document", "tags": [ "Documents" ], "summary": "Vision-API document extraction (multipart upload)", "description": "Takes a multipart upload (`file` part — image or PDF, max 10MB) and\nruns it through the Vision API to extract structured document data\n(degree certificate, ID, etc.). Returns the extracted fields plus\nthe raw OCR text. Used by the degree-verification UX. Auth: bearer\nJWT.\n", "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } }, "required": [ "file" ] } } } }, "responses": { "200": { "description": "Extraction result. `success=false` carries an error message instead.", "content": { "application/json": { "schema": { "type": "object", "description": "Legacy document processing result — shape is set by the configured\nupstream adapter (one of several DMS / extraction backends). Opaque.\n", "additionalProperties": true } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_processDocument_Misc", "resource_uri": "yf://agents/misc", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -F \"file=@/path/to/degree.jpg\" \\\n https://agents.yieldfabric.com/documents/process\n" } ], "x-related": [ { "operationId": "updateGroupDocument_GroupDocuments", "relation": "alternative" } ] } }, "/domain/extract": { "post": { "operationId": "handleDomainExtract_Domain", "x-method": "POST", "x-path": "/domain/extract", "x-handler": "handlers::domain_kg::handle_domain_extract", "tags": [ "Domain" ], "summary": "Schema-guided extraction of nodes, edges, and chunks from a document.", "description": "Receives a document body and a domain KG schema (node types, edge\ntypes, optional property types) from the operator (typically called\nvia reverse EKP from another service) and runs `chunk → embed →\nschema-guided LLM extraction`. Returns the extracted nodes\n(with key, type, label, description, properties, confidence,\nembedding), edges (with key, type, endpoints, properties, strength),\nper-chunk embeddings, and the total entity count. The supplied\n`existing_entity_keys` list lets the LLM reuse / deduplicate against\ncaller-side entities the service does not know about. Auth: bearer\nJWT.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "document", "domain_kg_schema" ], "description": "Operator-driven extraction request — body conforms to\n`DomainExtractionRequest` in src/economy/domain_extraction.rs.\n`domain_kg_schema` is an opaque per-operator manifest; the request\nenvelope tolerates unknown top-level keys so operators can pass\nbespoke routing hints alongside the canonical fields.\n", "additionalProperties": true, "properties": { "document": { "type": "object", "required": [ "id", "text" ], "properties": { "id": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "text": { "type": "string" }, "metadata": { "description": "Arbitrary JSON value." } } }, "domain_kg_schema": { "description": "Arbitrary JSON value." }, "options": { "description": "Arbitrary JSON value." } } }, "examples": { "loan_doc": { "summary": "Extract over a loan document with a tiny schema", "value": { "document_id": "9c1a4b2d-1f5a-4f6c-8c8b-1a2b3c4d5e6f", "content": "ACME Capital LLC agrees to lend Beta Industries Inc. USD 5,000,000.", "domain_kg_schema": { "description": "Loan-flow contracts", "node_types": [ { "name": "Party", "description": "Legal entity in the transaction." }, { "name": "Loan", "description": "A lending instrument with principal and rate." } ], "edge_types": [ { "name": "lends_to", "from_types": [ "Party" ], "to_types": [ "Party" ], "description": "Lender → Borrower" } ], "property_types": [ { "name": "principal_amount", "applies_to": [ "Loan" ], "data_type": "number" } ] }, "existing_entity_keys": [ "party:acme_capital" ] } } } } } }, "responses": { "200": { "description": "Extracted nodes, edges, and chunk embeddings.", "content": { "application/json": { "schema": { "type": "object", "description": "Extraction result — nodes, edges, and chunks-with-embeddings the\noperator can persist into its own KG. `additionalProperties` is\nopen because per-operator extraction adapters may surface extra\ndiagnostic blocks (e.g. `bootstrap`, `consolidation`) the operator\nschema hasn't formalised yet.\n", "additionalProperties": true, "properties": { "nodes": { "type": "array", "items": { "description": "Arbitrary JSON value." } }, "edges": { "type": "array", "items": { "description": "Arbitrary JSON value." } }, "chunks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": "string" }, "embedding": { "type": "array", "items": { "type": "number" } } } } } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_handleDomainExtract_Domain", "resource_uri": "yf://agents/domain/extract", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" \\\n \"https://agents.yieldfabric.com/domain/extract\" -d @domain_request.json\n" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx, os\npayload = {\n \"document_id\": os.environ[\"DOC_ID\"],\n \"content\": \"ACME Capital LLC agrees to lend Beta Industries Inc. USD 5,000,000.\",\n \"domain_kg_schema\": {\n \"description\": \"Loan-flow contracts\",\n \"node_types\": [\n {\"name\": \"Party\", \"description\": \"Legal entity.\"},\n {\"name\": \"Loan\", \"description\": \"Lending instrument.\"},\n ],\n \"edge_types\": [\n {\"name\": \"lends_to\", \"from_types\": [\"Party\"], \"to_types\": [\"Party\"], \"description\": \"\"},\n ],\n },\n \"existing_entity_keys\": [],\n}\nr = httpx.post(\n \"https://agents.yieldfabric.com/domain/extract\",\n json=payload,\n headers={\"Authorization\": f\"Bearer {os.environ['JWT']}\"},\n timeout=120.0,\n)\nr.raise_for_status()\nresult = r.json()\n" } ], "x-related": [ { "operationId": "extract_Kgs", "relation": "concept" }, { "guide": "pipelines-and-kgs", "relation": "concept" } ] } }, "/embeddings": { "post": { "operationId": "handleEmbed_Misc", "x-method": "POST", "x-path": "/embeddings", "x-handler": "handlers::domain_kg::handle_embed", "tags": [ "Embeddings" ], "summary": "Compute embedding vectors for strings", "description": "Returns the embedding vector for one or more strings using the\nconfigured embedding provider. Output vectors contain exactly 1,536\nelements. Used by the operator-side\ndomain-KG pipeline. Auth: bearer JWT.\n", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string" } } }, "examples": { "single": { "summary": "Single string", "value": { "input": "hello world" } }, "batch": { "summary": "Batch", "value": { "input": [ "hello", "world" ] } } } } } }, "responses": { "200": { "description": "Embedding vector(s).", "content": { "application/json": { "schema": { "type": "object", "required": [ "embedding" ], "properties": { "embedding": { "type": "array", "minItems": 1536, "maxItems": 1536, "items": { "type": "number" } } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_handleEmbed_Misc", "resource_uri": "yf://agents/misc", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"input\":\"hello\"}' \\\n https://agents.yieldfabric.com/embeddings\n" } ], "x-related": [] } }, "/graphql": { "post": { "operationId": "graphqlHandler_Misc", "x-method": "POST", "x-path": "/graphql", "x-handler": "graphql::graphql_handler", "tags": [ "GraphQL" ], "summary": "GraphQL endpoint for deal-flow + reads", "description": "Async-graphql endpoint shared with the GraphQL gateway. Carries the\ndeal-flow mutations (`createDeal`, `acceptDeal`,\n`activateDeal`, `processDealPeriod`, `completePartyAction`, etc.)\nand the read surface. Authenticated by the shared `JWT_SECRET` —\nthe `AuthClient` validates the bearer JWT before executing the\nquery. The SDL is published at\n`sdlHandler_Misc`. Auth: bearer JWT.\n\nWallet-required deal-flow and deal-room mutations can return\n`CHAIN_ACCOUNT_REQUIRED` inside `errors[].extensions` before their first\ndurable side effect. GraphQL extension names are camelCase:\n`code`, `httpStatus`, `entityKind`, `entityId`, `chainId`, and `operation`.\nThis differs intentionally from the snake_case flat body used by the\naccount-gated REST workflow routes.\n", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string" }, "variables": { "description": "Arbitrary JSON value." }, "operationName": { "type": [ "string", "null" ] } } }, "examples": { "deal-list": { "summary": "Simple deal-list query", "value": { "query": "query { deals { items { id status } } }" } } } } } }, "responses": { "200": { "description": "GraphQL response. `errors` array reports per-field failures.", "content": { "application/json": { "schema": { "type": "object", "description": "Standard GraphQL response envelope.", "properties": { "data": { "description": "Arbitrary JSON value." }, "errors": { "type": "array", "items": { "description": "Arbitrary JSON value." } }, "extensions": { "description": "Arbitrary JSON value." } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_graphqlHandler_Misc", "resource_uri": "yf://agents/misc", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"query\":\"query { __schema { types { name } } }\"}' \\\n https://api.yieldfabric.com/graphql\n" } ], "x-related": [ { "operationId": "sdlHandler_Misc", "relation": "sibling" } ] } }, "/graphql/sdl": { "get": { "operationId": "sdlHandler_Misc", "x-method": "GET", "x-path": "/graphql/sdl", "x-handler": "graphql::sdl_handler", "tags": [ "GraphQL" ], "summary": "Download the GraphQL SDL", "description": "Returns the SDL string for the agents-service GraphQL schema. Useful\nfor codegen and for the GraphQL gateway when stitching the agents\nschema in. No auth required.\n", "parameters": [], "responses": { "200": { "description": "SDL text.", "content": { "text/plain": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "string", "description": "GraphQL SDL (`Content-Type: text/plain`)." } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_sdlHandler_Misc", "resource_uri": "yf://agents/misc", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl https://api.yieldfabric.com/graphql/sdl" } ], "x-related": [ { "operationId": "graphqlHandler_Misc", "relation": "sibling" } ] } }, "/health": { "get": { "operationId": "healthCheck_Misc", "x-method": "GET", "x-path": "/health", "x-handler": "handlers::health_check", "tags": [ "Health" ], "summary": "Liveness probe", "description": "Returns `{\"message\":\"Agents service is healthy\"}` whenever the\nprocess is running. No DB roundtrip — pair with\n`databaseHealthCheck_Misc` for a full readiness probe. No auth\nrequired.\n", "parameters": [], "responses": { "200": { "description": "Service alive.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "version": { "type": [ "string", "null" ] } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_healthCheck_Misc", "resource_uri": "yf://agents/misc", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl https://agents.yieldfabric.com/health" } ], "x-related": [ { "operationId": "databaseHealthCheck_Misc", "relation": "sibling" } ] } }, "/health/db": { "get": { "operationId": "databaseHealthCheck_Misc", "x-method": "GET", "x-path": "/health/db", "x-handler": "handlers::database_health_check", "tags": [ "Health" ], "summary": "Database and retrieval readiness probe", "description": "Acquires a connection from the shared pool and validates the storage\nprerequisites required to serve traffic: source-encryption configuration,\nvalid room upload/storage quota and upload-concurrency configuration,\npgvector 0.8.0 or newer, pg_trgm, the 1536-wide embedding column, HNSW frame\nand document indexes, generation/materialization/source tables, durable\nroom-file admission/cursor/idempotency-batch tables, the deferred batch/file\nforeign key, the composite file/room/signed-hash signature foreign key, the\nroom usage counter plus its enabled accounting/immutability triggers, the\ninline-source owner counter plus its enabled owner-assignment/accounting\ntriggers, `STORAGE EXTERNAL` on both encrypted BYTEA columns, the\ntenant-fenced room-file source-reference index and foreign keys, separate\nqueued, expired-lease and failed-admission indexes, a valid and ready active\nroom-file pagination index, text/dedup/retention/lease indexes, and pipeline\nlease columns. Returns the established\n`{\"message\":\"Database connection is healthy\"}` body only when every check\npasses; otherwise returns bare `503 Service Unavailable`. After the schema\nchecks pass, the handler emits structured `queued`, `expired`, `failed`, and\n`oldest_seconds` admission-queue fields to service logs. It logs a warning\nwhen any lease is expired, any row is failed, or the oldest queued-or-expired\nrow age reaches 300 seconds; queue pressure does not change readiness. These\nsignals are not\nadded to the JSON response, preserving existing health consumers. No auth\nrequired.\n", "parameters": [], "responses": { "200": { "description": "Database reachable and all required storage/search prerequisites present.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "ok", "error" ] }, "db": { "type": [ "string", "null" ] }, "latency_ms": { "type": [ "integer", "null" ] } } } } } }, "503": { "description": "Database/configuration unavailable or a required schema, extension,\npgvector version, HNSW index, vector width, room-file page/admission queue\nor upload-limit/concurrency configuration, upload-idempotency/signature\nintegrity, room/inline-source quota accounting, EXTERNAL storage,\nsource-reference ownership, or lease invariant is absent. The handler\nreturns no response body.\n" } }, "x-mcp": { "tool_name": "yieldfabric_agents_databaseHealthCheck_Misc", "resource_uri": "yf://agents/misc", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl https://agents.yieldfabric.com/health/db" } ], "x-related": [ { "operationId": "healthCheck_Misc", "relation": "sibling" } ] } }, "/kgs": { "get": { "operationId": "listKgs_Kgs", "x-method": "GET", "x-path": "/kgs", "x-handler": "handlers::pipelines::list_kgs", "tags": [ "Knowledge Graphs" ], "summary": "List knowledge graphs the caller can see.", "description": "Returns the most-recent 50 knowledge graphs owned by working groups the\nauthenticated entity is an active member of. Each entry carries the KG's\nid, display name, LIVE `node_count`/`edge_count` (counted directly from\n`kgf.kg_frames` per request, NOT the denormalised columns — so a\nstill-running or never-refreshed ingest reports its true frame count\nrather than `0`), owning `working_group_id`, and creation timestamp —\nenough to render the KG picker in the studio without a follow-up call.\nOrdered by `created_at` descending so the freshest KGs surface first.\nKGs in working groups the caller has no membership in are filtered out\nat query time; there is no cross-group leak. Read-only and side-effect\nfree. Auth: bearer JWT.\n", "responses": { "200": { "description": "List of KG summaries, newest first.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "One knowledge graph (listing form).", "required": [ "id", "name", "node_count", "edge_count", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "node_count": { "type": "integer", "minimum": 0, "description": "Live node count from kgf.kg_frames (not the denormalised column), accurate mid-ingest." }, "edge_count": { "type": "integer", "minimum": 0, "description": "Live edge count from kgf.kg_frames (not the denormalised column), accurate mid-ingest." }, "working_group_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listKgs_Kgs", "resource_uri": "yf://agents/kgs", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/kgs" } ], "x-related": [ { "operationId": "getKg_Kgs", "relation": "sibling" }, { "operationId": "getSummary_Kgs", "relation": "sibling" }, { "guide": "pipelines-and-kgs", "relation": "concept" } ] } }, "/kgs/{id}": { "get": { "operationId": "getKg_Kgs", "x-method": "GET", "x-path": "/kgs/{id}", "x-handler": "handlers::pipelines::get_kg", "tags": [ "Knowledge Graphs" ], "summary": "Load a knowledge graph snapshot for rendering.", "description": "Returns a `KGSnapshot` for the requested KG, shaped for the React Flow\nchart. Two projections are available via `?view=`: `ontology` (default)\ntrims the instance-level graph to the most connected nodes (one node\nper real-world entity); `vocabulary` rolls up to the type schema — one\nnode per `concept_type`, with edges aggregated by\n`(from_type, verb, to_type)`. Optional `layers=` restricts to one or\nmore graph layers (e.g. `document,agentic`). `min_instances` filters\nsingletons (default 2) and `max_nodes` caps total nodes (default 100);\nexcess collapse into a synthetic \"Other\" bucket. Read-only; 404 when\nthe KG id does not exist. Auth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Knowledge-graph id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "layers", "in": "query", "required": false, "description": "Comma-separated list of graph layers to include (e.g. `document,agentic`). Omit for all layers.", "schema": { "type": "string" } }, { "name": "view", "in": "query", "required": false, "description": "Projection — `ontology` (default, canonical entities) or `vocabulary` (concept_type rollup).", "schema": { "type": "string", "enum": [ "ontology", "vocabulary" ], "default": "ontology" } }, { "name": "min_instances", "in": "query", "required": false, "description": "Minimum instance count (vocabulary view) or minimum node degree (ontology view). Default 2.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "max_nodes", "in": "query", "required": false, "description": "Maximum nodes to return. Excess collapse into an \"Other\" bucket. Default 100.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "KG snapshot in the requested projection.", "content": { "application/json": { "schema": { "type": "object", "description": "Full graph snapshot. The shape varies between the entity view (one\nnode per real-world thing) and the vocabulary view (one node per\nconcept_type). Both share top-level nodes/edges arrays plus the\nrunning counts and a per-layer breakdown.\n", "required": [ "name", "iteration", "nodes", "edges", "node_count", "edge_count", "layer_counts" ], "properties": { "kg_id": { "type": [ "string", "null" ], "format": "uuid", "description": "KG id. `null` while the snapshot is in-process and hasn't been persisted yet." }, "name": { "type": "string" }, "iteration": { "type": "integer", "minimum": 0, "description": "Monotonically increasing iteration counter for this snapshot lineage." }, "nodes": { "type": "array", "items": { "type": "object", "description": "Loose envelope for a graph node — extra fields vary by view\n(entity vs vocabulary). Keep `additionalProperties` open because\n`KGSnapshot` projects view-specific keys (`stance`, `tally`,\n`verb_pattern`, etc.) at render time.\n", "additionalProperties": true, "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "concept_type": { "type": [ "string", "null" ] }, "properties": { "description": "Arbitrary JSON value." } } } }, "edges": { "type": "array", "items": { "type": "object", "description": "Loose envelope for a graph edge — extra fields vary by view. Keep\n`additionalProperties` open because `KGSnapshot` projects\nview-specific keys (`slot_kind`, `weight`, etc.) at render time.\n", "additionalProperties": true, "properties": { "id": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "verb": { "type": "string" }, "properties": { "description": "Arbitrary JSON value." } } } }, "node_count": { "type": "integer", "minimum": 0 }, "edge_count": { "type": "integer", "minimum": 0 }, "layer_counts": { "type": "object", "description": "Per-layer node/edge counts. `document` = extracted from source documents,\n`inferred` = LLM-inferred during reasoning, `vocabulary` = vocabulary\ndiscovery, `semantic` = post-reconciliation semantic layer.\n", "required": [ "document", "inferred" ], "properties": { "document": { "type": "integer", "minimum": 0 }, "inferred": { "type": "integer", "minimum": 0 }, "vocabulary": { "type": "integer", "minimum": 0 }, "semantic": { "type": "integer", "minimum": 0 } }, "additionalProperties": { "type": "integer", "minimum": 0 } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getKg_Kgs", "resource_uri": "yf://agents/kgs/{id}", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/kgs/$KG_ID?view=ontology&max_nodes=200\"" } ], "x-related": [ { "operationId": "getKgComposed_Kgs", "relation": "sibling" }, { "operationId": "getSummary_Kgs", "relation": "sibling" }, { "operationId": "listKgs_Kgs", "relation": "sibling" }, { "guide": "pipelines-and-kgs", "relation": "concept" } ] } }, "/kgs/{id}/access-rate": { "get": { "operationId": "getAccessRate_Kgs", "x-method": "GET", "x-path": "/kgs/{id}/access-rate", "x-handler": "handlers::kg_access_rate::get_access_rate", "tags": [ "Knowledge Graphs" ], "summary": "Read a knowledge graph's access price", "description": "Returns the prospective price for grounding an answer in this KG before a\nquery is submitted. One page is the platform's configured KG character\nunit. Own-group use is always free; the rate applies only when another\ngroup consumes this KG's content.\n\nPersonal-notebook, platform-owned (group-less), and orphaned-owner KGs are\nstructurally free: they return `priceable: false`, a null rate, and\n`can_edit: false`.\nFor a priceable group KG, `can_edit` is true only for the group creator or\nan active owner/admin. Authentication is required, but group membership is\nnot: prospective payers must be able to inspect the rate before querying.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Knowledge-graph id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current display-clamped access price and edit capability.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "kg_id", "name", "priceable", "access_usd_per_page", "owner_working_group_id", "can_edit" ], "properties": { "kg_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "priceable": { "type": "boolean", "description": "False for personal-notebook, platform-owned, and orphaned-owner KGs." }, "access_usd_per_page": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1, "description": "USD per page of KG context consumed. `null` makes access free." }, "owner_working_group_id": { "type": [ "string", "null" ], "format": "uuid" }, "can_edit": { "type": "boolean" } } } } } }, "400": { "description": "The path id is not a UUID.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing or invalid bearer credential.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Knowledge graph not found.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Knowledge-graph or owner lookup failed.", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getAccessRate_Kgs", "resource_uri": "yf://agents/kgs/{id}/access-rate", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/kgs/$KG_ID/access-rate" } ], "x-related": [ { "operationId": "setAccessRate_Kgs", "relation": "update" }, { "operationId": "getAiRate_WorkingGroups", "relation": "group-pricing" } ] }, "put": { "operationId": "setAccessRate_Kgs", "x-method": "PUT", "x-path": "/kgs/{id}/access-rate", "x-handler": "handlers::kg_access_rate::set_access_rate", "tags": [ "Knowledge Graphs" ], "summary": "Set or clear a knowledge graph's access price", "description": "Sets the price, in USD per consumed KG page, for future cross-group use.\nA null or omitted value clears the rate. The allowed band is 0 through 1\nUSD per page, inclusive.\n\nFor a working-group-owned KG, the caller must be the group creator or an\nactive owner/admin. Personal-notebook and platform-owned (group-less) KGs\ncannot carry a non-null price and reject such writes with 422. Clearing a\nstale value remains permitted to the corresponding management authority.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Knowledge-graph id.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "access_usd_per_page": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1, "description": "USD per page of KG context consumed. `null` makes access free." } }, "description": "Omitting `access_usd_per_page` has the same clearing effect as `null`." }, "examples": { "set": { "value": { "access_usd_per_page": 0.05 } }, "clear": { "value": { "access_usd_per_page": null } } } } } }, "responses": { "200": { "description": "Persisted rate, or null after clearing.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "kg_id", "access_usd_per_page" ], "properties": { "kg_id": { "type": "string", "format": "uuid" }, "access_usd_per_page": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1, "description": "USD per page of KG context consumed. `null` makes access free." } } } } } }, "400": { "description": "Malformed path id or JSON body.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing or invalid bearer credential.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } }, "403": { "description": "Caller lacks active owner/admin authority for the owning group (or staff authority for a group-less cleanup).", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Knowledge graph not found.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "422": { "description": "Rate is non-finite/outside 0..1, or a non-null rate was supplied for an unpriceable KG.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Authorization lookup or database write failed.", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_setAccessRate_Kgs", "resource_uri": "yf://agents/kgs/{id}/access-rate", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PUT -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"access_usd_per_page\":0.05}' \\\n https://agents.yieldfabric.com/kgs/$KG_ID/access-rate\n" } ], "x-related": [ { "operationId": "getAccessRate_Kgs", "relation": "read-after-write" }, { "operationId": "setAiRate_WorkingGroups", "relation": "group-pricing" } ] } }, "/kgs/{id}/bootstrap": { "post": { "operationId": "bootstrap_Kgs", "x-method": "POST", "x-path": "/kgs/{id}/bootstrap", "x-handler": "handlers::bootstrap::bootstrap", "tags": [ "Knowledge Graphs" ], "summary": "Seed a zero-seed KG's lexicon from raw sample text.", "description": "Runs lexicon emergence (Phase A induction) on the KG against a caller-\nsupplied sample. Used to seed file-extraction flows or ad-hoc KGs\nwithout going through the conversation interpreter. Idempotent: if the\nKG is already bootstrapped, returns the existing\n`LexiconMetrics` unchanged; if the KG has a lexicon that came from a\nparent (inherited via lineage), the handler refuses to overwrite and\nreturns `outcome: has_existing_lexicon`. Burns up to 6 LLM calls when\nit does fire — keep `sample_text` modestly sized. Errors map upstream\nLLM failures to 502, retry-rejected output to 422, and missing KG to\n404. Auth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Knowledge-graph id.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Bootstrap a KG's lexicon from a sample text —\n`service::handlers::bootstrap::BootstrapRequest`.\n", "required": [ "sample_text" ], "properties": { "sample_text": { "type": "string", "description": "Raw text the inductor builds the lexicon from. Long sources\nshould be sampled (first N paragraphs) — 6 LLM calls per\nbootstrap is the plan's hard cap.\n" }, "kg_context": { "type": [ "string", "null" ], "description": "Free-form scope hint — e.g. \"legal contracts for a\nstructured-finance group\". Steers the bootstrap prompt.\n" }, "is_conversation": { "type": "boolean", "default": false, "description": "When true, use the conversation-aware bootstrap variant\n(prioritises turn-taking verbs + stance-coverage validator).\n" } } }, "examples": { "document_sample": { "summary": "Seed a legal-contracts KG from a document excerpt", "value": { "sample_text": "This Loan Agreement (the \"Agreement\") is entered into between\nACME Capital LLC (the \"Lender\") and Beta Industries Inc. (the\n\"Borrower\"). The Borrower agrees to repay the principal of\nUSD 5,000,000 at an interest rate of 7.25% per annum.\n", "kg_context": "legal contracts for a structured-finance working group", "is_conversation": false } }, "conversation_seed": { "summary": "Seed from a meeting transcript", "value": { "sample_text": "Alice: I propose we extend the loan by six months. Bob: I'd want a fee bump if we do.", "is_conversation": true } } } } } }, "responses": { "200": { "description": "Bootstrap outcome — applied, already-bootstrapped, or refused due to existing lexicon.", "content": { "application/json": { "schema": { "type": "object", "description": "Bootstrap outcome — `service::handlers::bootstrap::BootstrapResponse`,\na tagged union on `outcome`.\n", "required": [ "outcome" ], "properties": { "outcome": { "type": "string", "enum": [ "applied", "already_bootstrapped", "has_existing_lexicon" ] }, "metrics": { "oneOf": [ { "type": "null" }, { "description": "Arbitrary JSON value." } ], "description": "`LexiconMetrics` — present for `applied` and\n`already_bootstrapped`; absent for `has_existing_lexicon`.\nOpaque because the metrics struct is defined in the\neconomy-schema crate.\n" } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "422": { "description": "LLM output rejected after retry (insufficient concepts, malformed schema, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "502": { "description": "Upstream LLM error.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_bootstrap_Kgs", "resource_uri": "yf://agents/kgs/{id}/bootstrap", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" \\\n \"https://agents.yieldfabric.com/kgs/$KG_ID/bootstrap\" \\\n -d '{\"sample_text\": \"...\", \"kg_context\": \"legal contracts\"}'\n" } ], "x-related": [ { "operationId": "consolidate_Kgs", "relation": "sibling" }, { "operationId": "getLexicon_Kgs", "relation": "sibling" }, { "operationId": "extract_Kgs", "relation": "sibling" }, { "guide": "pipelines-and-kgs", "relation": "concept" } ] } }, "/kgs/{id}/composed": { "get": { "operationId": "getKgComposed_Kgs", "x-method": "GET", "x-path": "/kgs/{id}/composed", "x-handler": "handlers::pipelines::get_kg_composed", "tags": [ "Knowledge Graphs" ], "summary": "Load the composed KG over its lineage parent chain.", "description": "Returns a `KGSnapshot` aggregating the requested KG with every ancestor\nin its `parent_kg_id` chain. Composition is how reasoning flows access\nthe union of a file-extracted parent KG plus the reasoning child's\nemitted frames — without composition the child would only render its\nown frames in isolation. Supports the same `layers`, `view`,\n`min_instances`, and `max_nodes` query params as `GET /kgs/{id}`. The\nvocabulary view re-aggregates over the composed graph in memory because\nthe SQL fast-path targets a single kg_id. Read-only; 404 when the KG id\ndoes not exist. Auth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Knowledge-graph id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "layers", "in": "query", "required": false, "description": "Comma-separated list of graph layers to include.", "schema": { "type": "string" } }, { "name": "view", "in": "query", "required": false, "description": "Projection — `ontology` (default) or `vocabulary`.", "schema": { "type": "string", "enum": [ "ontology", "vocabulary" ], "default": "ontology" } }, { "name": "min_instances", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "max_nodes", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Composed KG snapshot.", "content": { "application/json": { "schema": { "type": "object", "description": "Full graph snapshot. The shape varies between the entity view (one\nnode per real-world thing) and the vocabulary view (one node per\nconcept_type). Both share top-level nodes/edges arrays plus the\nrunning counts and a per-layer breakdown.\n", "required": [ "name", "iteration", "nodes", "edges", "node_count", "edge_count", "layer_counts" ], "properties": { "kg_id": { "type": [ "string", "null" ], "format": "uuid", "description": "KG id. `null` while the snapshot is in-process and hasn't been persisted yet." }, "name": { "type": "string" }, "iteration": { "type": "integer", "minimum": 0, "description": "Monotonically increasing iteration counter for this snapshot lineage." }, "nodes": { "type": "array", "items": { "type": "object", "description": "Loose envelope for a graph node — extra fields vary by view\n(entity vs vocabulary). Keep `additionalProperties` open because\n`KGSnapshot` projects view-specific keys (`stance`, `tally`,\n`verb_pattern`, etc.) at render time.\n", "additionalProperties": true, "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "concept_type": { "type": [ "string", "null" ] }, "properties": { "description": "Arbitrary JSON value." } } } }, "edges": { "type": "array", "items": { "type": "object", "description": "Loose envelope for a graph edge — extra fields vary by view. Keep\n`additionalProperties` open because `KGSnapshot` projects\nview-specific keys (`slot_kind`, `weight`, etc.) at render time.\n", "additionalProperties": true, "properties": { "id": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "verb": { "type": "string" }, "properties": { "description": "Arbitrary JSON value." } } } }, "node_count": { "type": "integer", "minimum": 0 }, "edge_count": { "type": "integer", "minimum": 0 }, "layer_counts": { "type": "object", "description": "Per-layer node/edge counts. `document` = extracted from source documents,\n`inferred` = LLM-inferred during reasoning, `vocabulary` = vocabulary\ndiscovery, `semantic` = post-reconciliation semantic layer.\n", "required": [ "document", "inferred" ], "properties": { "document": { "type": "integer", "minimum": 0 }, "inferred": { "type": "integer", "minimum": 0 }, "vocabulary": { "type": "integer", "minimum": 0 }, "semantic": { "type": "integer", "minimum": 0 } }, "additionalProperties": { "type": "integer", "minimum": 0 } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getKgComposed_Kgs", "resource_uri": "yf://agents/kgs/{id}/composed", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/kgs/$KG_ID/composed\"" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx, os\nkg_id = os.environ[\"KG_ID\"]\nr = httpx.get(\n f\"https://agents.yieldfabric.com/kgs/{kg_id}/composed\",\n params={\"view\": \"ontology\", \"max_nodes\": 300},\n headers={\"Authorization\": f\"Bearer {os.environ['JWT']}\"},\n)\nr.raise_for_status()\nsnapshot = r.json()\n" } ], "x-related": [ { "operationId": "getKg_Kgs", "relation": "sibling" }, { "operationId": "getKgLineage_Kgs", "relation": "sibling" }, { "guide": "pipelines-and-kgs", "relation": "concept" } ] } }, "/kgs/{id}/consolidate": { "post": { "operationId": "consolidate_Kgs", "x-method": "POST", "x-path": "/kgs/{id}/consolidate", "x-handler": "handlers::consolidate::consolidate", "tags": [ "Knowledge Graphs" ], "summary": "Run Phase-B consolidation over the KG's untyped frame residue.", "description": "Companion to bootstrap. Walks the KG's current untyped frames, clusters\nthem, and asks the LLM to translate each cluster to an existing\nlexicon verb or extend the lexicon with a new provisional verb. Frames\nwhose cluster lands a translation are upgraded in place; new\nprovisional verbs are promoted to typed only if the consolidation's\nround-trip gate passes (coverage >= 0.70, verb_utilisation >= 0.50).\nUse when an interrupted reasoning run left untyped residue, when\nlegacy tools emitted untyped frames, or as a dry-run inspection\nbefore automation. No request body; the handler reads the KG's\ncurrent state and emits a structured summary. Requires a bootstrapped\nlexicon — returns 409 if the KG has none. LLM error mapping matches\nthe bootstrap endpoint. Auth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Knowledge-graph id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Consolidation summary — counts, gate outcome, persisted lexicon hash.", "content": { "application/json": { "schema": { "type": "object", "required": [ "consolidated" ], "properties": { "consolidated": { "type": "integer", "minimum": 0 }, "skipped": { "type": [ "integer", "null" ] }, "notes": { "type": "array", "items": { "type": "string" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "409": { "description": "KG has no lexicon to extend — bootstrap first.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "422": { "description": "LLM output rejected after retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "502": { "description": "Upstream LLM error.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_consolidate_Kgs", "resource_uri": "yf://agents/kgs/{id}/consolidate", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/kgs/$KG_ID/consolidate\"" } ], "x-related": [ { "operationId": "bootstrap_Kgs", "relation": "sibling" }, { "operationId": "getLexicon_Kgs", "relation": "sibling" }, { "operationId": "getSummary_Kgs", "relation": "sibling" }, { "guide": "pipelines-and-kgs", "relation": "concept" } ] } }, "/kgs/{id}/conversation/interpret": { "post": { "operationId": "interpret_Kgs", "x-method": "POST", "x-path": "/kgs/{id}/conversation/interpret", "x-handler": "handlers::conversation::interpret", "tags": [ "Knowledge Graphs" ], "summary": "Interpret a transcript into speech-act + mental frames on the KG.", "description": "Pipes a chronological transcript through the conversation pipeline\n(interpret + misunderstanding + intent), persists the resulting\nSpeechAct + Mental frames, and returns the persisted frame ids plus\nmisunderstanding candidates. On zero-seed KGs the handler runs LLM\nbootstrap emergence against a transcript sample first (disable via\n`?bootstrap=false`), and after persistence runs Phase-B\nconsolidation (disable via `?consolidate=false`). Idempotent at the\nframe level: re-submitting the same `turn_index` upserts rather than\nduplicates, thanks to `save_frame`'s ON CONFLICT semantics.\nMisunderstanding candidates are returned as metadata only — not\npersisted as frames in v1. Auth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Knowledge-graph id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "bootstrap", "in": "query", "required": false, "description": "Auto-bootstrap zero-seed KGs from a transcript sample. Default true.", "schema": { "type": "boolean", "default": true } }, { "name": "consolidate", "in": "query", "required": false, "description": "Run Phase-B consolidation after persistence. Default true.", "schema": { "type": "boolean", "default": true } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "utterance" ], "properties": { "utterance": { "type": "string" }, "options": { "description": "Arbitrary JSON value." } } }, "examples": { "two_turn": { "summary": "Two-turn negotiation snippet", "value": { "turns": [ { "turn_index": 0, "speaker": "alice", "text": "I propose we extend the loan by six months." }, { "turn_index": 1, "speaker": "bob", "text": "Happy to if the fee bumps by 25 bps." } ] } } } } } }, "responses": { "200": { "description": "Persisted frame ids + misunderstandings.", "content": { "application/json": { "schema": { "type": "object", "description": "Conversation interpreter output — wire shape of\n`service::handlers::conversation::InterpretResponse`.\n", "required": [ "kg_id", "speech_act_ids", "intent_ids", "misunderstandings", "frames_failed", "bootstrap_ran" ], "properties": { "kg_id": { "type": "string", "format": "uuid" }, "speech_act_ids": { "type": "array", "items": { "type": "string" } }, "intent_ids": { "type": "array", "items": { "type": "string" } }, "misunderstandings": { "type": "array", "items": { "description": "Arbitrary JSON value." } }, "frames_failed": { "type": "integer", "minimum": 0 }, "bootstrap_ran": { "type": "boolean", "description": "True when the handler ran LLM-driven bootstrap during this request." }, "consolidation": { "oneOf": [ { "type": "null" }, { "type": "object", "description": "Phase-B consolidation summary — wire shape of\n`service::handlers::conversation::ConsolidationSummary`.\n", "required": [ "clusters_seen", "translations", "extensions", "failed_clusters", "frames_upgraded", "frames_marked_failed", "promoted_patterns", "lexicon_persisted", "quality_warning" ], "properties": { "clusters_seen": { "type": "integer", "minimum": 0 }, "translations": { "type": "integer", "minimum": 0 }, "extensions": { "type": "integer", "minimum": 0 }, "failed_clusters": { "type": "integer", "minimum": 0 }, "frames_upgraded": { "type": "integer", "minimum": 0 }, "frames_marked_failed": { "type": "integer", "minimum": 0 }, "lexicon_gate_passed": { "type": [ "boolean", "null" ] }, "promoted_patterns": { "type": "array", "items": { "type": "string" } }, "lexicon_persisted": { "type": "boolean" }, "quality_warning": { "type": "boolean" } } } ] } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_interpret_Kgs", "resource_uri": "yf://agents/kgs/{id}/conversation/interpret", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" \\\n \"https://agents.yieldfabric.com/kgs/$KG_ID/conversation/interpret\" \\\n -d '{\"turns\":[{\"turn_index\":0,\"speaker\":\"alice\",\"text\":\"Hello\"}]}'\n" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx, os\nr = httpx.post(\n f\"https://agents.yieldfabric.com/kgs/{os.environ['KG_ID']}/conversation/interpret\",\n json={\"turns\": [\n {\"turn_index\": 0, \"speaker\": \"alice\", \"text\": \"I propose we extend the loan.\"},\n {\"turn_index\": 1, \"speaker\": \"bob\", \"text\": \"Happy to if the fee bumps.\"},\n ]},\n params={\"bootstrap\": \"true\", \"consolidate\": \"true\"},\n headers={\"Authorization\": f\"Bearer {os.environ['JWT']}\"},\n timeout=120.0,\n)\nr.raise_for_status()\noutcome = r.json()\n" } ], "x-related": [ { "operationId": "bootstrap_Kgs", "relation": "sibling" }, { "operationId": "extract_Kgs", "relation": "sibling" }, { "operationId": "listFrames_Kgs", "relation": "sibling" }, { "guide": "pipelines-and-kgs", "relation": "concept" } ] } }, "/kgs/{id}/extract": { "post": { "operationId": "extract_Kgs", "x-method": "POST", "x-path": "/kgs/{id}/extract", "x-handler": "handlers::extract::extract", "tags": [ "Knowledge Graphs" ], "summary": "Run end-to-end document extraction into the KG.", "description": "Synchronous extraction over a document and its ordered chunks.\nAuto-bootstraps the lexicon on zero-seed KGs (unless\n`options.bootstrap_on_zero_seed = false`), runs frame extraction\nchunk-by-chunk, and finishes with Phase-B consolidation (unless\n`options.run_consolidation = false`). Strict validation up front:\nchunk frame_ids must be unique, in strictly increasing `index`\norder, and free of `{shorter}_…` prefix collisions (which would\nbreak the orphan-cleanup LIKE pattern). Returns a structured\noutcome with per-chunk frame counts plus consolidation +\nlexicon-flush summaries. Status codes: 400 (validation), 404 (no\nsuch KG), 422 (LLM output rejected after retry), 502 (upstream LLM\nerror), 500 (persistence). Auth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Target knowledge-graph id.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "document" ], "properties": { "document": { "type": "object", "required": [ "id", "title", "text" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "text": { "type": "string" }, "metadata": { "description": "Arbitrary JSON value." } } }, "chunks": { "type": "array", "items": { "type": "object", "required": [ "id", "content", "index" ], "properties": { "id": { "type": "string" }, "content": { "type": "string" }, "index": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 }, "doc_title": { "type": [ "string", "null" ] }, "doc_id": { "type": [ "string", "null" ] } } } }, "options": { "type": "object", "description": "Extraction options — mirrors\n`service::handlers::extract::ExtractOptionsDto`. All fields default\nto the safe behaviour when absent.\n", "properties": { "graph_layer": { "type": [ "string", "null" ], "description": "`document` / `inferred` / `vocabulary` / `semantic`. Defaults to `document`." }, "run_consolidation": { "type": [ "boolean", "null" ], "description": "Defaults to true. Set false to inspect untyped residue." }, "bootstrap_on_zero_seed": { "type": [ "boolean", "null" ], "description": "Defaults to true. Set false to forbid LLM bootstrap on seeded KGs." } } } } }, "examples": { "two_chunks": { "summary": "Extract a two-chunk document", "value": { "document": { "frame_id": "doc_loan_agreement_v1", "title": "Loan Agreement — Q4 2025", "document_id": "9c1a4b2d-1f5a-4f6c-8c8b-1a2b3c4d5e6f" }, "chunks": [ { "frame_id": "chunk_loan_agreement_v1_001", "text": "ACME Capital LLC (the Lender) agrees to lend Beta Industries Inc. the principal of USD 5,000,000.", "index": 0, "total": 2 }, { "frame_id": "chunk_loan_agreement_v1_002", "text": "Interest accrues at 7.25% per annum, payable quarterly.", "index": 1, "total": 2 } ], "options": { "graph_layer": "document", "run_consolidation": true, "bootstrap_on_zero_seed": true } } } } } } }, "responses": { "200": { "description": "Extraction completed; per-chunk + consolidation summary.", "content": { "application/json": { "schema": { "type": "object", "description": "Extraction summary — wire shape of\n`service::handlers::extract::ExtractResponse`.\n", "required": [ "chunks" ], "properties": { "bootstrap": { "type": [ "string", "null" ], "enum": [ "applied", "already_bootstrapped", "has_existing_lexicon", null ] }, "chunks": { "type": "array", "items": { "type": "object", "required": [ "chunk_frame_id", "chunk_index", "frames_emitted", "wrappers_emitted", "frames_persisted" ], "properties": { "chunk_frame_id": { "type": "string" }, "chunk_index": { "type": "integer", "minimum": 0 }, "frames_emitted": { "type": "integer", "minimum": 0 }, "wrappers_emitted": { "type": "integer", "minimum": 0 }, "frames_persisted": { "type": "integer", "minimum": 0 }, "failure": { "type": [ "string", "null" ] } } } }, "consolidation": { "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "clusters_seen", "translations", "extensions", "failed_clusters", "frames_upgraded", "frames_marked_failed", "promoted_patterns", "quality_warning" ], "properties": { "clusters_seen": { "type": "integer", "minimum": 0 }, "translations": { "type": "integer", "minimum": 0 }, "extensions": { "type": "integer", "minimum": 0 }, "failed_clusters": { "type": "integer", "minimum": 0 }, "frames_upgraded": { "type": "integer", "minimum": 0 }, "frames_marked_failed": { "type": "integer", "minimum": 0 }, "lexicon_gate_passed": { "type": [ "boolean", "null" ] }, "promoted_patterns": { "type": "array", "items": { "type": "string" } }, "quality_warning": { "type": "boolean" } } } ] }, "lexicon_flush": { "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "lexicon_written", "lexicon_hash", "quality_warning", "consolidation_failed_count", "below_threshold" ], "properties": { "lexicon_written": { "type": "boolean" }, "lexicon_hash": { "type": "string" }, "quality_warning": { "type": "boolean" }, "consolidation_failed_count": { "type": "integer", "minimum": 0 }, "below_threshold": { "type": "boolean" } } } ] } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "422": { "description": "LLM output rejected after retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "502": { "description": "Upstream LLM error.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_extract_Kgs", "resource_uri": "yf://agents/kgs/{id}/extract", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" \\\n \"https://agents.yieldfabric.com/kgs/$KG_ID/extract\" \\\n -d @extract_request.json\n" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx, os\npayload = {\n \"document\": {\n \"frame_id\": \"doc_loan_agreement_v1\",\n \"title\": \"Loan Agreement — Q4 2025\",\n },\n \"chunks\": [\n {\"frame_id\": \"chunk_001\", \"text\": \"...\", \"index\": 0, \"total\": 2},\n {\"frame_id\": \"chunk_002\", \"text\": \"...\", \"index\": 1, \"total\": 2},\n ],\n \"options\": {\"run_consolidation\": True},\n}\nr = httpx.post(\n f\"https://agents.yieldfabric.com/kgs/{os.environ['KG_ID']}/extract\",\n json=payload,\n headers={\"Authorization\": f\"Bearer {os.environ['JWT']}\"},\n timeout=120.0,\n)\nr.raise_for_status()\noutcome = r.json()\n" } ], "x-related": [ { "operationId": "bootstrap_Kgs", "relation": "sibling" }, { "operationId": "consolidate_Kgs", "relation": "sibling" }, { "operationId": "getSummary_Kgs", "relation": "sibling" }, { "guide": "pipelines-and-kgs", "relation": "concept" } ] } }, "/kgs/{id}/frames": { "get": { "operationId": "listFrames_Kgs", "x-method": "GET", "x-path": "/kgs/{id}/frames", "x-handler": "handlers::frames::list_frames", "tags": [ "Knowledge Graphs" ], "summary": "List frames in a KG with optional kind/lifecycle filters.", "description": "Operator-facing inspection endpoint. Returns up to `limit`\n`FrameView` projections (default 100, cap 1000) for the given KG.\nAll filters AND-compose: `kind` constrains to a `FrameKind`\n(`event`, `state`, `relation`, `speech_act`, `mental`, `action`);\n`lifecycle` constrains to `untyped`, `provisional`, or `typed`;\n`consolidation_failed=true` surfaces frames Phase-B explicitly gave\nup on for operator review. Unknown enum strings return 400. Slot\nedges are omitted from list rows — use `getFrame_Kgs` for the\ndrill-down detail with rehydrated slot values. Auth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Knowledge-graph id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "query", "required": false, "description": "Restrict to one frame kind.", "schema": { "type": "string", "enum": [ "event", "state", "relation", "speech_act", "mental", "action" ] } }, { "name": "lifecycle", "in": "query", "required": false, "description": "Restrict to one lifecycle stage.", "schema": { "type": "string", "enum": [ "untyped", "provisional", "typed" ] } }, { "name": "consolidation_failed", "in": "query", "required": false, "description": "Return only frames the consolidator marked as failed.", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum rows to return. Capped at 1000, defaults to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } } ], "responses": { "200": { "description": "Filtered list of frame projections.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "One frame in a KG — may be an entity, relation, speech act, etc.,\ndistinguished by `concept_type`.\n", "required": [ "id", "kg_id", "frame_id", "concept_type" ], "properties": { "id": { "type": "string", "format": "uuid" }, "kg_id": { "type": "string", "format": "uuid" }, "frame_id": { "type": "string" }, "concept_type": { "type": "string" }, "verb": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] }, "raw_text": { "type": [ "string", "null" ] }, "properties": { "description": "Arbitrary JSON value." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listFrames_Kgs", "resource_uri": "yf://agents/kgs/{id}/frames", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/kgs/$KG_ID/frames?kind=speech_act&lifecycle=typed&limit=200\"" } ], "x-related": [ { "operationId": "getFrame_Kgs", "relation": "sibling" }, { "operationId": "getSummary_Kgs", "relation": "sibling" }, { "operationId": "getConsensus_Kgs", "relation": "sibling" }, { "guide": "pipelines-and-kgs", "relation": "concept" } ] } }, "/kgs/{id}/frames/merge-entity": { "post": { "operationId": "mergeEntity_Kgs", "x-method": "POST", "x-path": "/kgs/{id}/frames/merge-entity", "x-handler": "handlers::frames::merge_entity", "tags": [ "Knowledge Graphs" ], "summary": "Confirm a dedup near-match — fold one entity into another.", "description": "The write half of the adjudication queue that\n`GET /kgs/{id}/frames?suggested_matches=true` reads. `keep_frame_id`\nsurvives and gains the other's edges and aliases; `merge_frame_id` is\n**archived, not deleted**, which is what makes\n`unmerge-entity` possible.\n\nMerging is the direction that re-running extraction cannot undo, so it\nis only ever reached through an explicit call — never automatically.\nThe absorbed entity's own label becomes an alias on the keeper: after\nfolding \"AMAL Trustees Ltd\" into \"AMAL Trustees\", the keeper must still\nbe findable by the name that disappeared.\n\n**Access.** Bearer JWT, gated by `authorize_kg_write` — which resolves\nthe KG's OWNING group and checks `UploadDocuments` there. Deliberately\nnot `ensure_kg_access`: that is a membership/visibility predicate, so on\nits own it let anyone who could READ a corpus mutate it.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge graph id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "keep_frame_id", "merge_frame_id" ], "properties": { "keep_frame_id": { "type": "string", "description": "The entity that survives", "gaining the other's edges and aliases.": null }, "merge_frame_id": { "type": "string", "description": "The entity absorbed. Archived", "not deleted — which is what makes the merge reversible.": null } } } } } }, "responses": { "200": { "description": "What the merge moved.", "content": { "application/json": { "schema": { "type": "object", "required": [ "kept_frame_id", "merged_frame_id", "edges_remapped", "duplicate_edges_removed", "aliases" ], "properties": { "kept_frame_id": { "type": "string" }, "merged_frame_id": { "type": "string" }, "edges_remapped": { "type": "integer", "minimum": 0 }, "duplicate_edges_removed": { "type": "integer", "minimum": 0 }, "aliases": { "type": "array", "items": { "type": "string" }, "description": "The keeper's surface forms after the union. The absorbed entity's own label becomes one of these — that is the point of the merge: the keeper must still be findable by the name that was folded in." } } } } } }, "400": { "description": "Either frame is missing, or the two cannot be merged." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_mergeEntity_Kgs", "resource_uri": "yf://agents/kgs/frames", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \"https://agents.yieldfabric.com/kgs/$KG/frames/merge-entity\" \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"keep_frame_id\":\"entity:amal-trustees\",\"merge_frame_id\":\"entity:amal-trustees-ltd\"}'\n" } ], "x-related": [ { "operationId": "unmergeEntity_Kgs", "relation": "alternative" }, { "operationId": "dismissMatch_Kgs", "relation": "alternative" }, { "guide": "pipelines-and-kgs", "relation": "concept" } ] } }, "/kgs/{id}/frames/{frame_id}": { "get": { "operationId": "getFrame_Kgs", "x-method": "GET", "x-path": "/kgs/{id}/frames/{frame_id}", "x-handler": "handlers::frames::get_frame", "tags": [ "Knowledge Graphs" ], "summary": "Drill-down view of a single frame and its slot edges.", "description": "Returns one `FrameView` (kind, lifecycle, verb, stance, concept_type,\ndescription, confidence, raw_text, layer, consolidation-failure flag,\ntimestamps) augmented with the frame's slot edges rehydrated into\nJSON. Slot values are flattened with a `kind` discriminator: `frame`\nslots carry `ref_kind` (`entity`|`frame`) and a `target_frame_id`,\nwhile `literal` slots carry their JSON value. Used as the drill-down\ncompanion to `listFrames_Kgs` — operators click a frame in the\nlist view to see its anatomy. Read-only; 404 when the frame is not\nin this KG. Auth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Knowledge-graph id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "frame_id", "in": "path", "required": true, "description": "Frame id (string from `kg_frames.frame_id`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Frame view + slot edges.", "content": { "application/json": { "schema": { "type": "object", "description": "One frame in a KG — may be an entity, relation, speech act, etc.,\ndistinguished by `concept_type`.\n", "required": [ "id", "kg_id", "frame_id", "concept_type" ], "properties": { "id": { "type": "string", "format": "uuid" }, "kg_id": { "type": "string", "format": "uuid" }, "frame_id": { "type": "string" }, "concept_type": { "type": "string" }, "verb": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] }, "raw_text": { "type": [ "string", "null" ] }, "properties": { "description": "Arbitrary JSON value." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getFrame_Kgs", "resource_uri": "yf://agents/kgs/{id}/frames/{frame_id}", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/kgs/$KG_ID/frames/$FRAME_ID\"" } ], "x-related": [ { "operationId": "listFrames_Kgs", "relation": "sibling" }, { "operationId": "getConsensus_Kgs", "relation": "sibling" }, { "guide": "pipelines-and-kgs", "relation": "concept" } ] } }, "/kgs/{id}/frames/{frame_id}/archive-observation": { "post": { "operationId": "archiveObservation_Kgs", "x-method": "POST", "x-path": "/kgs/{id}/frames/{frame_id}/archive-observation", "x-handler": "handlers::frames::archive_observation", "tags": [ "Knowledge Graphs" ], "summary": "Retract a SpeechAct in a shared knowledge graph.", "description": "Retracts a review endorsement, correction, or note written against a\nframe in a working-group KG.\n\nThe pre-existing delete routes resolve through a `target` edge to a\ncontact in the caller's PERSONAL notebook, so a claim endorsement\nwritten against a chunk frame in a shared KG had no retraction path at\nall — approving and then rejecting a document left its support frames\nalive, still reading `Accepted`.\n\nGated by `authorize_kg_write`, the **identical** gate the observation\nWRITER uses: retracting an assertion is the same authority as making\none, and a mere reader must not be able to silence another party's.\n\n**Access.** Bearer JWT, gated by `authorize_kg_write` — which resolves\nthe KG's OWNING group and checks `UploadDocuments` there. Deliberately\nnot `ensure_kg_access`: that is a membership/visibility predicate, so on\nits own it let anyone who could READ a corpus mutate it.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge graph id." }, { "name": "frame_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Optional note recorded with the retraction." } } } } } }, "responses": { "200": { "description": "How many speech acts were archived.", "content": { "application/json": { "schema": { "type": "object", "properties": { "archived": { "type": "integer", "minimum": 0 } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_archiveObservation_Kgs", "resource_uri": "yf://agents/kgs/frames", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \"https://agents.yieldfabric.com/kgs/$KG/frames/speechact:abc/archive-observation\" \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"reason\":\"document rejected on review\"}'\n" } ], "x-related": [ { "guide": "pipelines-and-kgs", "relation": "concept" } ] } }, "/kgs/{id}/frames/{frame_id}/consensus": { "get": { "operationId": "getConsensus_Kgs", "x-method": "GET", "x-path": "/kgs/{id}/frames/{frame_id}/consensus", "x-handler": "handlers::consensus::get_consensus", "tags": [ "Knowledge Graphs" ], "summary": "Compute consensus state over SpeechAct frames targeting a frame.", "description": "Aggregates the SpeechAct frames (support / challenge / question /\nneutral / uncertain) that target the given frame and derives a\n`ConsensusState`. Three cooperation modes are selectable via\n`?mode=`: `collaborative` (default) accepts after\n`auto_accept_after_stable_turns` consecutive stable turns;\n`adversarial` requires at least `min_supports` confirming SpeechActs\nwith no unresolved challenge; `degenerate` reports raw counts only.\nReturns the derived `ConsensusState` plus the underlying SpeechAct\ntally. Read-only; 404 when the target frame is not present in the\nKG; 400 for unknown mode values. Auth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Knowledge-graph id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "frame_id", "in": "path", "required": true, "description": "Target frame id whose consensus is being queried.", "schema": { "type": "string" } }, { "name": "mode", "in": "query", "required": false, "description": "Cooperation mode.", "schema": { "type": "string", "enum": [ "collaborative", "adversarial", "degenerate" ], "default": "collaborative" } }, { "name": "min_supports", "in": "query", "required": false, "description": "Required confirming SpeechActs (adversarial mode only). Default 2.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "auto_accept_after_stable_turns", "in": "query", "required": false, "description": "Consecutive stable turns before auto-acceptance (collaborative mode only). Default 3.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Consensus state + SpeechAct tally.", "content": { "application/json": { "schema": { "type": "object", "description": "Per-frame consensus snapshot — wire shape of\n`service::handlers::consensus::ConsensusResponse`.\n", "required": [ "kg_id", "target_frame_id", "state", "mode", "supports", "challenges", "unresolved_challenges", "questions", "neutral", "uncertain", "total_claims", "stable_turns" ], "properties": { "kg_id": { "type": "string", "format": "uuid" }, "target_frame_id": { "type": "string" }, "state": { "type": "string", "description": "Consensus state — values from\n`yieldfabric_economy_schema::cooperation::ConsensusState`.\n" }, "mode": { "type": "string", "enum": [ "collaborative", "adversarial", "degenerate" ] }, "supports": { "type": "integer", "minimum": 0 }, "challenges": { "type": "integer", "minimum": 0 }, "unresolved_challenges": { "type": "integer", "minimum": 0 }, "questions": { "type": "integer", "minimum": 0 }, "neutral": { "type": "integer", "minimum": 0 }, "uncertain": { "type": "integer", "minimum": 0 }, "total_claims": { "type": "integer", "minimum": 0 }, "stable_turns": { "type": "integer", "minimum": 0 } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getConsensus_Kgs", "resource_uri": "yf://agents/kgs/{id}/frames/{frame_id}/consensus", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/kgs/$KG_ID/frames/$FRAME_ID/consensus?mode=adversarial&min_supports=3\"" } ], "x-related": [ { "operationId": "getFrame_Kgs", "relation": "sibling" }, { "operationId": "listFrames_Kgs", "relation": "sibling" }, { "guide": "pipelines-and-kgs", "relation": "concept" } ] } }, "/kgs/{id}/frames/{frame_id}/dismiss-match": { "post": { "operationId": "dismissMatch_Kgs", "x-method": "POST", "x-path": "/kgs/{id}/frames/{frame_id}/dismiss-match", "x-handler": "handlers::frames::dismiss_match", "tags": [ "Knowledge Graphs" ], "summary": "Judge a near-match to be two genuinely different entities.", "description": "Clears the suggested-match marker so the pair leaves the adjudication\nqueue. **The entities themselves are untouched** — this is the \"no,\nthese really are different\" answer, the counterpart to\n`merge-entity`'s \"yes, same thing\".\n\n**Access.** Bearer JWT, gated by `authorize_kg_write` — which resolves\nthe KG's OWNING group and checks `UploadDocuments` there. Deliberately\nnot `ensure_kg_access`: that is a membership/visibility predicate, so on\nits own it let anyone who could READ a corpus mutate it.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge graph id." }, { "name": "frame_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "How many markers were cleared.", "content": { "application/json": { "schema": { "type": "object", "required": [ "frame_id", "cleared" ], "properties": { "frame_id": { "type": "string" }, "cleared": { "type": "integer", "minimum": 0, "description": "How many suggested-match markers were removed." } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_dismissMatch_Kgs", "resource_uri": "yf://agents/kgs/frames", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \"https://agents.yieldfabric.com/kgs/$KG/frames/entity:acme/dismiss-match\" \\\n -H \"Authorization: Bearer $JWT\"\n" } ], "x-related": [ { "operationId": "mergeEntity_Kgs", "relation": "alternative" }, { "guide": "pipelines-and-kgs", "relation": "concept" } ] } }, "/kgs/{id}/frames/{frame_id}/unmerge-entity": { "post": { "operationId": "unmergeEntity_Kgs", "x-method": "POST", "x-path": "/kgs/{id}/frames/{frame_id}/unmerge-entity", "x-handler": "handlers::frames::unmerge_entity", "tags": [ "Knowledge Graphs" ], "summary": "Reverse an entity merge.", "description": "`frame_id` is the **absorbed** entity — the archived one — not the\nkeeper. Restores it and moves its edges back.\n\nWithout this, the human gate in front of merging would only move who\nmakes the permanent mistake. Wrong merges surface late, and the only\nother remedy would be re-ingesting the corpus.\n\n**Access.** Bearer JWT, gated by `authorize_kg_write` — which resolves\nthe KG's OWNING group and checks `UploadDocuments` there. Deliberately\nnot `ensure_kg_access`: that is a membership/visibility predicate, so on\nits own it let anyone who could READ a corpus mutate it.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge graph id." }, { "name": "frame_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "What the reversal restored.", "content": { "application/json": { "schema": { "type": "object", "required": [ "kept_frame_id", "merged_frame_id", "edges_remapped", "duplicate_edges_removed", "aliases" ], "properties": { "kept_frame_id": { "type": "string" }, "merged_frame_id": { "type": "string" }, "edges_remapped": { "type": "integer", "minimum": 0 }, "duplicate_edges_removed": { "type": "integer", "minimum": 0 }, "aliases": { "type": "array", "items": { "type": "string" }, "description": "The keeper's surface forms after the union. The absorbed entity's own label becomes one of these — that is the point of the merge: the keeper must still be findable by the name that was folded in." } } } } } }, "400": { "description": "The frame is not an absorbed entity, or was never merged." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_unmergeEntity_Kgs", "resource_uri": "yf://agents/kgs/frames", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \"https://agents.yieldfabric.com/kgs/$KG/frames/entity:amal-trustees-ltd/unmerge-entity\" \\\n -H \"Authorization: Bearer $JWT\"\n" } ], "x-related": [ { "operationId": "mergeEntity_Kgs", "relation": "alternative" }, { "guide": "pipelines-and-kgs", "relation": "concept" } ] } }, "/kgs/{id}/lexicon": { "get": { "operationId": "getLexicon_Kgs", "x-method": "GET", "x-path": "/kgs/{id}/lexicon", "x-handler": "handlers::kg_lexicon::get_lexicon", "tags": [ "Knowledge Graphs" ], "summary": "Read the KG's persisted lexicon and metrics.", "description": "Returns the KG's current `ExtractionLexicon` (concepts, terms, verb\npatterns, derived rules) plus `LexiconMetrics` (version, content\nhash, counts, round-trip outcome, quality warning, threshold flag,\nbootstrap timestamp). The response always carries a `present` flag\nso callers can distinguish \"no lexicon yet\" (e.g. fresh\nreasoning-only KG before its first bootstrap) from \"lexicon present\nbut empty\". Read-only and side-effect free. Auth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Knowledge-graph id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Lexicon + metrics (or `present: false`).", "content": { "application/json": { "schema": { "type": "object", "description": "Vocabulary surface for a KG — wire shape of\n`service::handlers::kg_lexicon::LexiconView`.\n", "required": [ "kg_id", "present" ], "properties": { "kg_id": { "type": "string", "format": "uuid" }, "present": { "type": "boolean", "description": "True when the KG has a persisted lexicon row." }, "lexicon": { "oneOf": [ { "type": "null" }, { "description": "Arbitrary JSON value." } ], "description": "`ExtractionLexicon` (concept_types, verb_patterns, metrics) —\nshape defined by the `yieldfabric-economy-schema` crate.\nOpaque here because the lexicon spec lives outside this service.\n" }, "metrics": { "oneOf": [ { "type": "null" }, { "description": "Arbitrary JSON value." } ], "description": "`LexiconMetrics` — coverage / utilisation / quality counters.\nOpaque for the same reason as `lexicon`.\n" } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getLexicon_Kgs", "resource_uri": "yf://agents/kgs/{id}/lexicon", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/kgs/$KG_ID/lexicon\"" } ], "x-related": [ { "operationId": "bootstrap_Kgs", "relation": "sibling" }, { "operationId": "consolidate_Kgs", "relation": "sibling" }, { "operationId": "mergeInto_Kgs", "relation": "sibling" }, { "guide": "pipelines-and-kgs", "relation": "concept" } ] } }, "/kgs/{id}/lexicon/verbs/promote": { "post": { "operationId": "promoteVerb_Kgs", "x-method": "POST", "x-path": "/kgs/{id}/lexicon/verbs/promote", "x-handler": "handlers::kg_lexicon::promote_verb", "tags": [ "Knowledge Graphs" ], "summary": "Promote a provisional verb into the typed set.", "description": "Consolidation grows the lexicon monotonically and auto-promotes verbs\nthat pass its round-trip gate. That gate is a **corpus statistic, not a\njudgement**: a verb can be correct and important while appearing too\nrarely to promote itself. This is the manual override.\n\n`metrics` in the response are the LAST consolidation's measurement,\nwritten back unchanged — a manual promotion does not re-measure the\ncorpus. The next consolidation recomputes them.\n\nThe pattern travels in the body rather than the path because patterns\ncontain slashes and angle brackets.\n\n**Access.** Bearer JWT, gated by `authorize_kg_write` — which resolves\nthe KG's OWNING group and checks `UploadDocuments` there. Deliberately\nnot `ensure_kg_access`: that is a membership/visibility predicate, so on\nits own it let anyone who could READ a corpus mutate it.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge graph id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pattern" ], "properties": { "pattern": { "type": "string", "description": "The verb pattern to adjudicate. Travels in the body rather than the path because patterns contain slashes and angle brackets." } } } } } }, "responses": { "200": { "description": "The lexicon after promotion.", "content": { "application/json": { "schema": { "type": "object", "required": [ "kg_id", "present" ], "properties": { "kg_id": { "type": "string", "format": "uuid" }, "present": { "type": "boolean" }, "lexicon": { "type": "object", "description": "The extraction lexicon — typed and provisional verbs." }, "metrics": { "type": "object", "description": "The LAST consolidation's round-trip measurement, written back unchanged. A manual adjudication does not re-measure the corpus; the next consolidation recomputes these." } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "No provisional verb matches that pattern." }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_promoteVerb_Kgs", "resource_uri": "yf://agents/kgs/lexicon", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \"https://agents.yieldfabric.com/kgs/$KG/lexicon/verbs/promote\" \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"pattern\":\"guarantees\"}'\n" } ], "x-related": [ { "operationId": "rejectVerb_Kgs", "relation": "alternative" }, { "guide": "pipelines-and-kgs", "relation": "concept" } ] } }, "/kgs/{id}/lexicon/verbs/reject": { "post": { "operationId": "rejectVerb_Kgs", "x-method": "POST", "x-path": "/kgs/{id}/lexicon/verbs/reject", "x-handler": "handlers::kg_lexicon::reject_verb", "tags": [ "Knowledge Graphs" ], "summary": "Drop a provisional verb from the lexicon.", "description": "**Only provisional verbs can be rejected.** A typed verb may already\nhave frames assigned to it, so removing it would strand them —\nre-typing existing frames is consolidation's job, not this endpoint's.\n\nSame body shape and same `metrics` semantics as `promote`.\n\n**Access.** Bearer JWT, gated by `authorize_kg_write` — which resolves\nthe KG's OWNING group and checks `UploadDocuments` there. Deliberately\nnot `ensure_kg_access`: that is a membership/visibility predicate, so on\nits own it let anyone who could READ a corpus mutate it.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge graph id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pattern" ], "properties": { "pattern": { "type": "string", "description": "The verb pattern to adjudicate. Travels in the body rather than the path because patterns contain slashes and angle brackets." } } } } } }, "responses": { "200": { "description": "The lexicon after rejection.", "content": { "application/json": { "schema": { "type": "object", "required": [ "kg_id", "present" ], "properties": { "kg_id": { "type": "string", "format": "uuid" }, "present": { "type": "boolean" }, "lexicon": { "type": "object", "description": "The extraction lexicon — typed and provisional verbs." }, "metrics": { "type": "object", "description": "The LAST consolidation's round-trip measurement, written back unchanged. A manual adjudication does not re-measure the corpus; the next consolidation recomputes these." } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "No provisional verb matches that pattern." }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_rejectVerb_Kgs", "resource_uri": "yf://agents/kgs/lexicon", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \"https://agents.yieldfabric.com/kgs/$KG/lexicon/verbs/reject\" \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"pattern\":\"is-a-kind-of\"}'\n" } ], "x-related": [ { "operationId": "promoteVerb_Kgs", "relation": "alternative" }, { "guide": "pipelines-and-kgs", "relation": "concept" } ] } }, "/kgs/{id}/lineage": { "get": { "operationId": "getKgLineage_Kgs", "x-method": "GET", "x-path": "/kgs/{id}/lineage", "x-handler": "handlers::pipelines::get_kg_lineage", "tags": [ "Knowledge Graphs" ], "summary": "Return the parent chain metadata for a KG.", "description": "Walks `parent_kg_id` from the requested KG up to its lineage root and\nreturns one `LineageEntry` per ancestor (including the requested KG\nitself). Each entry carries id, name, working_group_id, parent\npointer, and cached node/edge counts. Used to render lineage\nbreadcrumbs and to validate that a `getKgComposed_Kgs` call covers\nthe expected ancestors. Read-only; 404 when the requested KG does\nnot exist. Auth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Knowledge-graph id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Ordered chain from leaf to root.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "node_count", "edge_count" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "working_group_id": { "type": [ "string", "null" ], "format": "uuid" }, "parent_kg_id": { "type": [ "string", "null" ], "format": "uuid" }, "node_count": { "type": "integer", "minimum": 0 }, "edge_count": { "type": "integer", "minimum": 0 } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getKgLineage_Kgs", "resource_uri": "yf://agents/kgs/{id}/lineage", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/kgs/$KG_ID/lineage\"" } ], "x-related": [ { "operationId": "getKgComposed_Kgs", "relation": "sibling" }, { "operationId": "getKg_Kgs", "relation": "sibling" }, { "guide": "pipelines-and-kgs", "relation": "concept" } ] } }, "/kgs/{id}/merge_into/{target_id}": { "post": { "operationId": "mergeInto_Kgs", "x-method": "POST", "x-path": "/kgs/{id}/merge_into/{target_id}", "x-handler": "handlers::kg_lexicon::merge_into", "tags": [ "Knowledge Graphs" ], "summary": "Merge a source KG's lexicon into a target KG and report conflicts.", "description": "Deterministic, target-wins merge of the source KG's lexicon into the\ntarget's: same-key verb patterns merge, near-duplicate verbs surface\nfor operator review, conflicted concept/term/derived definitions are\nrecorded in the response. The target's `lexicon_version` bumps by\none and `content_hash` reflects the post-merge state; the target's\n`bootstrap_completed_at` is preserved so merging never un-bootstraps\na KG. Identity merges (source == target) return 400. Either KG\nmissing returns 404. No request body — the operation is fully\ndetermined by the path. Auth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Source knowledge-graph id (lexicon being merged in).", "schema": { "type": "string", "format": "uuid" } }, { "name": "target_id", "in": "path", "required": true, "description": "Target knowledge-graph id (lexicon being mutated).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Merge applied; conflict report attached.", "content": { "application/json": { "schema": { "type": "object", "description": "Lexicon merge outcome — wire shape of\n`service::handlers::kg_lexicon::MergeResponse`.\n", "required": [ "source_kg_id", "target_kg_id" ], "properties": { "source_kg_id": { "type": "string", "format": "uuid" }, "target_kg_id": { "type": "string", "format": "uuid" }, "target_metrics": { "description": "Arbitrary JSON value." }, "report": { "description": "Arbitrary JSON value." } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_mergeInto_Kgs", "resource_uri": "yf://agents/kgs/{id}/merge_into/{target_id}", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/kgs/$SOURCE_KG_ID/merge_into/$TARGET_KG_ID\"" } ], "x-related": [ { "operationId": "getLexicon_Kgs", "relation": "sibling" }, { "operationId": "bootstrap_Kgs", "relation": "sibling" }, { "operationId": "consolidate_Kgs", "relation": "sibling" }, { "guide": "pipelines-and-kgs", "relation": "concept" } ] } }, "/kgs/{id}/reason-over": { "post": { "operationId": "reasonOverKg_Kgs", "x-method": "POST", "x-path": "/kgs/{id}/reason-over", "x-handler": "handlers::pipelines::reason_over_kg", "tags": [ "Knowledge Graphs" ], "summary": "Start a reasoning pipeline whose lineage parent is the given KG.", "description": "Convenience operation for the canonical composition flow\n`file → KG → reason → KG`. Verifies the parent KG exists, creates a\nfresh child KG with `parent_kg_id = {id}`, builds a reasoning\npipeline (optionally with team-formation and vocab-review\ncheckpoints), and spawns it asynchronously. Returns `200 OK` with\nthe new `run_id`, the child `kg_id`, and a `thread_id` (when\ncreated). Inherits `working_group_id` from the parent unless\noverridden. Vocab discovery is skipped since the parent KG already\ncarries a vocabulary. 404 when the parent KG does not exist. Auth:\nbearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Parent knowledge-graph id (reasoning lineage root).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "problem" ], "properties": { "problem": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "working_group_id": { "type": [ "string", "null" ], "format": "uuid" }, "max_turns": { "type": [ "integer", "null" ], "minimum": 1 }, "require_team_formation": { "type": "boolean", "default": false }, "require_vocab_review": { "type": "boolean", "default": false } } }, "examples": { "minimal": { "summary": "Ask a question over the KG", "value": { "problem": "Is the proposed loan extension covenant-compliant?" } }, "with_team_formation": { "summary": "Reason with team construction + vocab review checkpoints", "value": { "problem": "Synthesise the structuring options on the table.", "name": "Q4 structuring review", "max_turns": 20, "require_team_formation": true, "require_vocab_review": true } } } } } }, "responses": { "200": { "description": "Reasoning pipeline started.", "content": { "application/json": { "schema": { "type": "object", "required": [ "run_id", "kg_id" ], "properties": { "run_id": { "type": "string", "format": "uuid" }, "kg_id": { "type": "string", "format": "uuid" }, "thread_id": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_reasonOverKg_Kgs", "resource_uri": "yf://agents/kgs/{id}/reason-over", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" \\\n \"https://agents.yieldfabric.com/kgs/$PARENT_KG_ID/reason-over\" \\\n -d '{\"problem\": \"Is the loan extension covenant-compliant?\"}'\n" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx, os\nr = httpx.post(\n f\"https://agents.yieldfabric.com/kgs/{os.environ['PARENT_KG_ID']}/reason-over\",\n json={\"problem\": \"Synthesise structuring options.\", \"max_turns\": 20},\n headers={\"Authorization\": f\"Bearer {os.environ['JWT']}\"},\n)\nr.raise_for_status()\nrun = r.json()\n" } ], "x-related": [ { "operationId": "getKg_Kgs", "relation": "sibling" }, { "operationId": "getKgComposed_Kgs", "relation": "sibling" }, { "operationId": "getKgLatestRun_Kgs", "relation": "sibling" }, { "guide": "pipelines-and-kgs", "relation": "concept" } ] } }, "/kgs/{id}/run": { "get": { "operationId": "getKgLatestRun_Kgs", "x-method": "GET", "x-path": "/kgs/{id}/run", "x-handler": "handlers::pipelines::get_kg_latest_run", "tags": [ "Knowledge Graphs" ], "summary": "Latest pipeline run for a KG, with thread linkage.", "description": "Returns the most recent `pipeline_runs` row whose `target_kg_id`\nmatches the requested KG. Carries `run_id`, `status`, `kind`,\n`working_group_id`, `thread_id`, and the run's `problem` description.\nOn legacy runs created before the thread-per-pipeline backfill\nlanded, the handler lazily creates a new chat thread, links it back\nto `pipeline_runs.thread_id`, and returns the new id — guaranteeing\nthe KG chat panel always has a target for new messages. Read-only\nfrom the caller's perspective (the backfill is incidental). 404 when\nno run targets this KG. Auth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Knowledge-graph id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Latest run + thread linkage.", "content": { "application/json": { "schema": { "type": "object", "required": [ "run_id", "status", "kind" ], "properties": { "run_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "kind": { "type": "string" }, "working_group_id": { "type": [ "string", "null" ], "format": "uuid" }, "thread_id": { "type": [ "string", "null" ] }, "problem": { "type": [ "string", "null" ] } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getKgLatestRun_Kgs", "resource_uri": "yf://agents/kgs/{id}/run", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/kgs/$KG_ID/run\"" } ], "x-related": [ { "operationId": "getKg_Kgs", "relation": "sibling" }, { "operationId": "reasonOverKg_Kgs", "relation": "sibling" }, { "guide": "pipelines-and-kgs", "relation": "concept" } ] } }, "/kgs/{id}/summary": { "get": { "operationId": "getSummary_Kgs", "x-method": "GET", "x-path": "/kgs/{id}/summary", "x-handler": "handlers::kg_summary::get_summary", "tags": [ "Knowledge Graphs" ], "summary": "Aggregate frame counts plus lexicon health for the KG.", "description": "Returns a `KgSummary` aggregating frame counts (by kind, by\nlifecycle, and the cumulative `consolidation_failed` total) plus\nlexicon health metadata (version, bootstrap stamp, quality warning,\nthreshold flag). One round-trip alternative to issuing parallel\n`listFrames_Kgs` + `getLexicon_Kgs` calls for dashboards / health\nchecks / post-pipeline validation / operator triage. Read-only and\nside-effect free. 404 when the KG id is unknown. Auth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Knowledge-graph id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "KG summary.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Markdown-rendered summary plus structured metadata. Shape is composed\nat handler render time from frame counts, lexicon hash, and per-view\nrollups — kept open because new rollup keys land here without an API\nbump.\n" } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getSummary_Kgs", "resource_uri": "yf://agents/kgs/{id}/summary", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/kgs/$KG_ID/summary\"" } ], "x-related": [ { "operationId": "getKg_Kgs", "relation": "sibling" }, { "operationId": "getLexicon_Kgs", "relation": "sibling" }, { "operationId": "listFrames_Kgs", "relation": "sibling" }, { "guide": "pipelines-and-kgs", "relation": "concept" } ] } }, "/kgs/{kg_id}/agent_memory/{agent_id}": { "get": { "operationId": "listKgAgentMemory_Kgs", "x-method": "GET", "x-path": "/kgs/{kg_id}/agent_memory/{agent_id}", "x-handler": "handlers::agent_registry::list_kg_agent_memory", "tags": [ "Knowledge Graphs" ], "summary": "List KG-scoped memory entries for an agent.", "description": "Requires a caller-visible agent. Reads and writes address only the verified\ncaller's private memory partition, including when the agent spec is shared.\nThe caller must also be authorized for this KG or working group.\nReturns every shared-agent memory entry stored under the\n`(kg_id, agent_id)` scope. KG-scoped memory is isolated from the\nagent's working-group memory and global memory, letting the same\nagent definition carry different notes per KG. Read-only;\n500 on persistence errors. Operates on shared-agent memory only —\npersonal-agent memory is accessed through the owning user's flows.\nAuth: bearer JWT.\n", "parameters": [ { "name": "kg_id", "in": "path", "required": true, "description": "Knowledge-graph id.", "schema": { "type": "string" } }, { "name": "agent_id", "in": "path", "required": true, "description": "Agent id (slug or uuid).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Memory entries for this agent in this KG scope.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "agent_id", "key", "value", "created_at", "updated_at" ], "properties": { "agent_id": { "type": "string" }, "user_id": { "type": [ "string", "null" ] }, "kg_id": { "type": [ "string", "null" ], "format": "uuid" }, "working_group_id": { "type": [ "string", "null" ], "format": "uuid" }, "key": { "type": "string" }, "value": { "description": "Arbitrary JSON value." }, "description": { "type": [ "string", "null" ] }, "confidence": { "type": [ "number", "null" ] }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listKgAgentMemory_Kgs", "resource_uri": "yf://agents/kgs/{kg_id}/agent_memory/{agent_id}", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/kgs/$KG_ID/agent_memory/$AGENT_ID\"" } ], "x-related": [ { "operationId": "putKgAgentMemory_Kgs", "relation": "sibling" }, { "operationId": "deleteKgAgentMemory_Kgs", "relation": "sibling" }, { "operationId": "listAgentsOnKg_Kgs", "relation": "sibling" }, { "guide": "pipelines-and-kgs", "relation": "concept" } ] }, "post": { "operationId": "putKgAgentMemory_Kgs", "x-method": "POST", "x-path": "/kgs/{kg_id}/agent_memory/{agent_id}", "x-handler": "handlers::agent_registry::put_kg_agent_memory", "tags": [ "Knowledge Graphs" ], "summary": "Upsert a KG-scoped memory entry for an agent.", "description": "Requires a caller-visible agent. Reads and writes address only the verified\ncaller's private memory partition, including when the agent spec is shared.\nThe caller must also be authorized for this KG or working group.\nWrites (insert-or-update) a single memory entry under the\n`(kg_id, agent_id)` scope. The entry's `key` is the dedup field;\nre-posting the same key replaces the previous value. KG-scoped\nmemory is isolated from working-group and global memory namespaces,\nso the same key may hold different values across scopes. Returns\n`204 No Content` on success. Operates on shared-agent memory only —\npersonal-agent memory is accessed through the owning user's flows.\nAuth: bearer JWT.\n", "parameters": [ { "name": "kg_id", "in": "path", "required": true, "description": "Knowledge-graph id.", "schema": { "type": "string" } }, { "name": "agent_id", "in": "path", "required": true, "description": "Agent id (slug or uuid).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "One memory entry for an agent at a given scope (KG / WG / global).", "required": [ "key", "value" ], "properties": { "key": { "type": "string" }, "value": { "description": "Arbitrary JSON value." }, "description": { "type": [ "string", "null" ] }, "confidence": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 } } }, "examples": { "scalar_value": { "summary": "Stash a per-KG preference", "value": { "key": "preferred_unit", "value": "USD" } }, "json_blob": { "summary": "Stash structured working notes", "value": { "key": "counterparty_risk_notes", "value": { "party": "Beta Industries", "flags": [ "recent downgrade", "covenant breach" ] } } } } } } }, "responses": { "204": { "description": "Entry upserted." }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_putKgAgentMemory_Kgs", "resource_uri": "yf://agents/kgs/{kg_id}/agent_memory/{agent_id}", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" \\\n \"https://agents.yieldfabric.com/kgs/$KG_ID/agent_memory/$AGENT_ID\" \\\n -d '{\"key\": \"preferred_unit\", \"value\": \"USD\"}'\n" } ], "x-related": [ { "operationId": "listKgAgentMemory_Kgs", "relation": "sibling" }, { "operationId": "deleteKgAgentMemory_Kgs", "relation": "sibling" }, { "guide": "pipelines-and-kgs", "relation": "concept" } ] } }, "/kgs/{kg_id}/agent_memory/{agent_id}/{key}": { "delete": { "operationId": "deleteKgAgentMemory_Kgs", "x-method": "DELETE", "x-path": "/kgs/{kg_id}/agent_memory/{agent_id}/{key}", "x-handler": "handlers::agent_registry::delete_kg_agent_memory", "tags": [ "Knowledge Graphs" ], "summary": "Delete a single KG-scoped memory entry for an agent.", "description": "Requires a caller-visible agent. Reads and writes address only the verified\ncaller's private memory partition, including when the agent spec is shared.\nThe caller must also be authorized for this KG or working group.\nRemoves one entry from an agent's KG-scoped memory namespace. The\nscope is bounded by both the KG id and the agent id, so deleting\n`(kg, agent, key)` here has no effect on the same agent's\nworking-group or global memory entries with the same key. Returns\n`204 No Content` on success and `404 Not Found` if the key is not\npresent. Operates on shared-agent memory only; personal-agent\nmemory is accessed through the owning user's flows. Auth: bearer JWT.\n", "parameters": [ { "name": "kg_id", "in": "path", "required": true, "description": "Knowledge-graph id.", "schema": { "type": "string" } }, { "name": "agent_id", "in": "path", "required": true, "description": "Agent id (slug or uuid).", "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "description": "Memory entry key.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Entry deleted." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_deleteKgAgentMemory_Kgs", "resource_uri": "yf://agents/kgs/{kg_id}/agent_memory/{agent_id}/{key}", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X DELETE -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/kgs/$KG_ID/agent_memory/$AGENT_ID/$KEY\"" } ], "x-related": [ { "operationId": "listKgAgentMemory_Kgs", "relation": "sibling" }, { "operationId": "putKgAgentMemory_Kgs", "relation": "sibling" }, { "guide": "pipelines-and-kgs", "relation": "concept" } ] } }, "/kgs/{kg_id}/agents": { "get": { "operationId": "listAgentsOnKg_Kgs", "x-method": "GET", "x-path": "/kgs/{kg_id}/agents", "x-handler": "handlers::agent_registry::list_agents_on_kg", "tags": [ "Knowledge Graphs" ], "summary": "List agents that have produced invocations on a KG.", "description": "Requires KG access and returns only caller-visible agents.\nAggregates `agent_invocations` rows for the requested KG and returns\none entry per distinct agent id, with the per-agent invocation count\nand the latest invocation timestamp. Ordered by `last_used`\ndescending so the most-recently active agents surface first. Used by\nthe studio's \"who has touched this KG\" panel. Read-only and side-\neffect free. Auth: bearer JWT.\n", "parameters": [ { "name": "kg_id", "in": "path", "required": true, "description": "Knowledge-graph id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Per-agent invocation summary.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "agent_id", "invocation_count", "last_used" ], "properties": { "agent_id": { "type": "string" }, "invocation_count": { "type": "integer", "minimum": 0 }, "last_used": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listAgentsOnKg_Kgs", "resource_uri": "yf://agents/kgs/{kg_id}/agents", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/kgs/$KG_ID/agents\"" } ], "x-related": [ { "operationId": "listKgAgentMemory_Kgs", "relation": "sibling" }, { "operationId": "getKgLatestRun_Kgs", "relation": "sibling" }, { "guide": "pipelines-and-kgs", "relation": "concept" } ] } }, "/kgs/{kg_id}/chunks": { "get": { "operationId": "getKgChunks_Kgs", "x-method": "GET", "x-path": "/kgs/{kg_id}/chunks", "x-handler": "handlers::chunks::get_kg_chunks", "tags": [ "Knowledge Graphs" ], "summary": "List every chunk linked to a KG, with citations attached.", "description": "Returns one row per `(citation, chunk)` pair for every chunk in the\nKG. Chunks with zero citations still appear (with `node_key=null`)\nso operators can spot a \"66 chunks persisted, 1 cited\" silent\nextraction failure instead of believing the chunker produced only\none chunk. Each row carries the chunk text, position, parent\ndocument, document title, and the source frame id that cited the\nchunk under `source_chunk` provenance. Used by the chunk-graph\nbuilder client-side to compute \"chunks connected through shared\nentities\" edges. Read-only. Auth: bearer JWT.\nThe caller must have read access to the requested KG; platform visibility\ndoes not imply write access on the sibling mutation routes.\n", "parameters": [ { "name": "kg_id", "in": "path", "required": true, "description": "Knowledge-graph id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Flat list of chunk citation rows.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "Row returned by GET /kgs/{kg_id}/chunks — a chunk with one optional\ncitation per row (multiple rows per chunk when there are multiple\ncitations).\n", "required": [ "id", "chunk_id", "link_type", "chunk_text", "chunk_index", "updated_at", "document_id", "doc_title" ], "properties": { "id": { "type": "string", "format": "uuid" }, "node_key": { "type": [ "string", "null" ] }, "edge_key": { "type": [ "string", "null" ] }, "chunk_id": { "type": "string", "format": "uuid" }, "link_type": { "type": "string" }, "excerpt": { "type": "string" }, "chunk_text": { "type": "string" }, "chunk_index": { "type": "integer", "minimum": 0 }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "document_id": { "type": "string", "format": "uuid" }, "doc_title": { "type": "string" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getKgChunks_Kgs", "resource_uri": "yf://agents/kgs/{kg_id}/chunks", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/kgs/$KG_ID/chunks\"" } ], "x-related": [ { "operationId": "createChunk_Kgs", "relation": "sibling" }, { "operationId": "getStitchedDocument_Kgs", "relation": "sibling" }, { "operationId": "pruneOrphans_Kgs", "relation": "sibling" }, { "guide": "knowledge", "relation": "concept" } ] }, "post": { "operationId": "createChunk_Kgs", "x-method": "POST", "x-path": "/kgs/{kg_id}/chunks", "x-handler": "handlers::chunks::create_chunk", "tags": [ "Knowledge Graphs" ], "summary": "Append a manual note as a new chunk on an existing KG.", "description": "Creates a new note chunk on the KG and asynchronously extracts frames\nfrom it. The note is persisted with its embedding and attached to the\nKG's source document (file-extracted KGs) or to a lazy `kg_notes`\ncontainer document (reasoning-only KGs). Returns `202 Accepted`\nimmediately with the new `chunk_id`, `document_id`, and the\nbackground `run_id` for streaming extraction progress via\n`GET /pipelines/{run_id}/events`. Content is validated for non-empty\ntrimmed text and a 32 KiB ceiling. The handler refuses creation\n(409) when an extraction-kind pipeline is already in flight on this\nKG to avoid vocabulary lost-update and duplicate-node races. Auth:\nbearer JWT with the owning group's `UploadDocuments` capability (member\nrole or higher). Group-less platform KGs are staff-only.\n", "parameters": [ { "name": "kg_id", "in": "path", "required": true, "description": "Knowledge-graph id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Create a new note (chunk) on an existing KG — mirrors\n`service::handlers::chunks::CreateChunkRequest`.\n", "required": [ "content" ], "properties": { "content": { "type": "string" } } }, "examples": { "short_note": { "summary": "Add a short note to a reasoning KG", "value": { "content": "Counterparty risk on Beta Industries is elevated due to recent rating downgrade." } } } } } }, "responses": { "202": { "description": "Chunk persisted, extraction pipeline spawned.", "content": { "application/json": { "schema": { "type": "object", "required": [ "chunk_id", "document_id", "run_id" ], "properties": { "chunk_id": { "type": "string", "format": "uuid" }, "document_id": { "type": "string", "format": "uuid" }, "run_id": { "type": "string", "format": "uuid" } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "409": { "description": "Another extraction pipeline is in flight on this KG.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_createChunk_Kgs", "resource_uri": "yf://agents/kgs/{kg_id}/chunks", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" \\\n \"https://agents.yieldfabric.com/kgs/$KG_ID/chunks\" \\\n -d '{\"content\": \"Counterparty risk on Beta Industries is elevated.\"}'\n" } ], "x-related": [ { "operationId": "getKgChunks_Kgs", "relation": "sibling" }, { "operationId": "updateChunk_Kgs", "relation": "sibling" }, { "operationId": "pruneOrphans_Kgs", "relation": "sibling" }, { "guide": "knowledge", "relation": "concept" } ] } }, "/kgs/{kg_id}/chunks/{chunk_id}": { "get": { "operationId": "getScopedChunk_Kgs", "x-method": "GET", "x-path": "/kgs/{kg_id}/chunks/{chunk_id}", "x-handler": "handlers::chunks::get_scoped_chunk", "tags": [ "Knowledge Graphs" ], "summary": "Fetch one chunk in its explicit KG context.", "description": "Canonical chunk-detail route. Returns the chunk text, parent document and\nprevious/next chunk ids using `(kg_id, chunk_id)` as the identity. The caller\nmust have read access to the KG. A matching chunk in another KG is never\nconsidered and cannot affect the response. Auth: bearer JWT.\n", "parameters": [ { "name": "kg_id", "in": "path", "required": true, "description": "Knowledge-graph id.", "schema": { "type": "string" } }, { "name": "chunk_id", "in": "path", "required": true, "description": "Chunk id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Chunk content and neighbours within the requested KG.", "content": { "application/json": { "schema": { "type": "object", "required": [ "chunk_id", "content", "position" ], "properties": { "chunk_id": { "type": "string", "format": "uuid" }, "content": { "type": "string" }, "position": { "type": "integer", "minimum": 0 }, "document_id": { "type": [ "string", "null" ], "format": "uuid" }, "document_label": { "type": [ "string", "null" ] }, "prev_chunk_id": { "type": [ "string", "null" ], "format": "uuid" }, "next_chunk_id": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getScopedChunk_Kgs", "resource_uri": "yf://agents/kgs/{kg_id}/chunks/{chunk_id}", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/kgs/$KG_ID/chunks/$CHUNK_ID\"" } ], "x-related": [ { "operationId": "updateScopedChunk_Kgs", "relation": "sibling" }, { "operationId": "getChunk_Kgs", "relation": "legacy" }, { "operationId": "getStitchedDocument_Kgs", "relation": "sibling" } ] }, "post": { "operationId": "updateScopedChunk_Kgs", "x-method": "POST", "x-path": "/kgs/{kg_id}/chunks/{chunk_id}", "x-handler": "handlers::chunks::update_scoped_chunk", "tags": [ "Knowledge Graphs" ], "summary": "Edit one chunk inside an explicit KG and re-extract it.", "description": "Canonical chunk-edit route. Requires `UploadDocuments` authority on the\nowning group (member role or higher), or staff authority for a group-less\nplatform KG. Content and embedding are updated only for the `(kg_id,\nchunk_id)` row, and extraction is triggered only for that KG. The response\nshape is identical to the legacy edit endpoint. Validation: non-empty\ntrimmed content and a 32 KiB ceiling. Auth: bearer JWT.\n", "parameters": [ { "name": "kg_id", "in": "path", "required": true, "description": "Knowledge-graph id.", "schema": { "type": "string" } }, { "name": "chunk_id", "in": "path", "required": true, "description": "Chunk id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string" } } } } } }, "responses": { "200": { "description": "Chunk updated and re-extraction completed in the selected KG.", "content": { "application/json": { "schema": { "type": "object", "required": [ "chunk_id", "affected_kgs", "pending_run_ids", "orphaned_nodes" ], "properties": { "chunk_id": { "type": "string", "format": "uuid" }, "affected_kgs": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "pending_run_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "orphaned_nodes": { "type": "integer", "minimum": 0 } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "409": { "description": "Conflicting state (e.g. step already completed, intent already cancelled, duplicate idempotency key with different body).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_updateScopedChunk_Kgs", "resource_uri": "yf://agents/kgs/{kg_id}/chunks/{chunk_id}", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" \\\n \"https://agents.yieldfabric.com/kgs/$KG_ID/chunks/$CHUNK_ID\" \\\n -d '{\"content\": \"Updated note text.\"}'\n" } ], "x-related": [ { "operationId": "getScopedChunk_Kgs", "relation": "sibling" }, { "operationId": "updateChunk_Kgs", "relation": "legacy" }, { "operationId": "pruneOrphans_Kgs", "relation": "sibling" } ] } }, "/kgs/{kg_id}/documents/{doc_id}/source": { "get": { "operationId": "getDocumentSource_Kgs", "x-method": "GET", "x-path": "/kgs/{kg_id}/documents/{doc_id}/source", "x-handler": "handlers::chunks::get_document_source", "tags": [ "Knowledge Graphs" ], "summary": "Download the retained original bytes of a document.", "description": "Returns the file as it was uploaded — not extracted text. Served\n`inline` with the uploader's declared `media_type` so a PDF renders in\nplace, and with `X-Content-Type-Options: nosniff` so a mislabelled file\ncannot be coaxed into executing as something else in the browser. The\nmedia type is **echoed, never sniffed**.\n\nA `404` here is about the SOURCE, not the document: retention may have\nexpired, or the document may predate source retention entirely. The\ndocument and its frames can be perfectly present.\n\n**Access.** Bearer JWT, gated by the same chunk-read predicate as the\nrest of this surface — the caller must be able to read the KG.\n", "parameters": [ { "name": "kg_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "doc_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The retained bytes, with the uploader's declared content type.", "headers": { "Content-Disposition": { "schema": { "type": "string" }, "description": "`inline`, with a sanitised filename when one was retained." }, "X-Content-Type-Options": { "schema": { "type": "string", "enum": [ "nosniff" ] } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "No retained source for this document — retention expired, or it predates retention." }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getDocumentSource_Kgs", "resource_uri": "yf://agents/kgs/documents", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET \"https://agents.yieldfabric.com/kgs/$KG/documents/$DOC/source\" \\\n -H \"Authorization: Bearer $JWT\"\n" } ], "x-related": [ { "operationId": "getDocument_Knowledge", "relation": "sibling" }, { "guide": "knowledge", "relation": "concept" } ] } }, "/kgs/{kg_id}/documents/{doc_id}/stitched": { "get": { "operationId": "getStitchedDocument_Kgs", "x-method": "GET", "x-path": "/kgs/{kg_id}/documents/{doc_id}/stitched", "x-handler": "handlers::chunks::get_stitched_document", "tags": [ "Knowledge Graphs" ], "summary": "Stitched document view — title plus chunks in position order.", "description": "Returns one document and every chunk that is ` is part of\n` of it, in `properties.position` order. Powers a \"render\nthe full file, edit a paragraph at a time\" UX: the frontend stitches\nchunks back into one continuous read view, and edits target a single\nchunk by its `chunk_id` via `updateChunk_Kgs`. Returns 404 when the\n`(kg_id, doc_id)` pair does not resolve to a document frame in this\nKG — the handler refuses to surface \"this doc exists but belongs to\nanother KG\" as a distinct error. Read-only. Auth: bearer JWT.\nThe caller must have read access to `kg_id` before any document lookup runs.\n", "parameters": [ { "name": "kg_id", "in": "path", "required": true, "description": "Knowledge-graph id.", "schema": { "type": "string" } }, { "name": "doc_id", "in": "path", "required": true, "description": "Document frame id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Document + ordered chunks.", "content": { "application/json": { "schema": { "type": "object", "required": [ "document_id", "document_frame_id", "doc_title", "chunks" ], "properties": { "document_id": { "type": "string", "format": "uuid" }, "document_frame_id": { "type": "string" }, "doc_title": { "type": "string" }, "chunks": { "type": "array", "items": { "type": "object", "required": [ "chunk_id", "frame_id", "position", "token_count", "content", "updated_at" ], "properties": { "chunk_id": { "type": "string", "format": "uuid" }, "frame_id": { "type": "string" }, "position": { "type": "integer", "minimum": 0 }, "token_count": { "type": "integer", "minimum": 0 }, "content": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getStitchedDocument_Kgs", "resource_uri": "yf://agents/kgs/{kg_id}/documents/{doc_id}/stitched", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/kgs/$KG_ID/documents/$DOC_ID/stitched\"" } ], "x-related": [ { "operationId": "getKgChunks_Kgs", "relation": "sibling" }, { "operationId": "updateChunk_Kgs", "relation": "sibling" }, { "operationId": "getChunk_Kgs", "relation": "sibling" }, { "guide": "knowledge", "relation": "concept" } ] } }, "/kgs/{kg_id}/prune-orphans": { "post": { "operationId": "pruneOrphans_Kgs", "x-method": "POST", "x-path": "/kgs/{kg_id}/prune-orphans", "x-handler": "handlers::chunks::prune_orphans", "tags": [ "Knowledge Graphs" ], "summary": "Delete document-layer frames that no longer have chunk provenance.", "description": "Sweeps every document-layer frame in the KG that (a) isn't itself a\nchunk or document row and (b) has no outbound `source_chunk` slot\nedge, deleting it. Inbound slot edges cascade via the\n`from_frame_id` FK. Opt-in cleanup intended to follow a note edit\nwhose re-extraction failed or narrowed (the edit endpoint surfaces\nthe orphan count but does not auto-delete because the user's edit\nmay be a typo fix and silently losing nodes is a footgun). Returns\nthe deleted `frame_id` list plus a count. No request body. Auth:\nbearer JWT. This destructive operation requires the owning group's\n`DeleteDocuments` capability (admin role or higher); group-less platform\nKGs are staff-only.\n", "parameters": [ { "name": "kg_id", "in": "path", "required": true, "description": "Knowledge-graph id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pruned frame ids + count.", "content": { "application/json": { "schema": { "type": "object", "required": [ "kg_id", "pruned_count", "pruned_node_keys" ], "properties": { "kg_id": { "type": "string", "format": "uuid" }, "pruned_count": { "type": "integer", "minimum": 0 }, "pruned_node_keys": { "type": "array", "items": { "type": "string" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_pruneOrphans_Kgs", "resource_uri": "yf://agents/kgs/{kg_id}/prune-orphans", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/kgs/$KG_ID/prune-orphans\"" } ], "x-related": [ { "operationId": "updateChunk_Kgs", "relation": "sibling" }, { "operationId": "getKgChunks_Kgs", "relation": "sibling" }, { "operationId": "getSummary_Kgs", "relation": "sibling" }, { "guide": "pipelines-and-kgs", "relation": "concept" } ] } }, "/knowledge/claims/enumerate": { "post": { "operationId": "enumerateClaims_Knowledge", "x-method": "POST", "x-path": "/knowledge/claims/enumerate", "x-handler": "handlers::claims_evidence::enumerate_claims", "tags": [ "Knowledge Documents" ], "summary": "Enumerate recorded document-ledger claims with exact scoped totals.", "description": "Read-only scoped retrieval authorization. Summary includes verdict, finding, risk, requirement and question; all also includes facts and unclassified claims. Source verdicts are author assessments, not consensus. Counts describe recorded ledger observations. One page is consistent; pagination is live, not a snapshot. Order: severity, kind, document, section, KG, frame identity. Empty results do not prove no problems exist. Unknown fields, including as_of, are rejected. Frozen sets constrain membership, not historical contents. Set and explicit KG scopes are mutually exclusive. No model or embedding calls.", "responses": { "200": { "description": "Enumerate recorded document-ledger claims with exact scoped totals.", "content": { "application/json": { "schema": { "type": "object", "properties": { "projection": { "type": "string", "const": "document_ledger" }, "scope": { "type": "object", "properties": { "working_group_id": { "type": "string", "format": "uuid" }, "kg_ids": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" }, "maxItems": 1000 }, "set_id": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "working_group_id" ] }, "filters": { "type": "object", "properties": { "view": { "type": "string", "enum": [ "summary", "all" ], "default": "summary" }, "kinds": { "type": [ "array", "null" ], "maxItems": 32, "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "verdicts": { "type": [ "array", "null" ], "maxItems": 32, "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "document_id": { "type": [ "string", "null" ], "format": "uuid" }, "section": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 512, "description": "Case-insensitive literal substring." }, "about": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 512, "description": "Case-insensitive literal substring." } }, "required": [] }, "total": { "type": "integer", "minimum": 0 }, "returned": { "type": "integer", "minimum": 0, "maximum": 200 }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kg_id": { "type": "string", "format": "uuid" }, "frame_id": { "type": "string" }, "document_id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "chunk_id": { "type": [ "string", "null" ] }, "claim": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "statement": { "type": "string" }, "kind": { "type": "string" }, "verdict": { "type": "string" }, "severity": { "type": "string" }, "section": { "type": "string" }, "supports": { "type": "integer", "minimum": 0, "description": "Eligible distinct observation records supporting the claim, counted in the read's transaction. Citations of other claims (evidence kind claim) are dependencies, listed in rests_on, and never counted." }, "challenges": { "type": "integer", "minimum": 0, "description": "Eligible distinct observation records challenging the claim; citations excluded." } }, "required": [ "id", "key", "statement", "supports", "challenges" ] }, "evidence": { "type": "array", "items": { "type": "object", "required": [ "id", "relation", "kind" ], "properties": { "id": { "type": "string", "description": "FRAME::" }, "relation": { "type": "string", "enum": [ "supports", "challenges" ] }, "kind": { "type": "string" }, "artifact": { "type": "string" }, "ref": { "type": "string" }, "path": { "type": "string" }, "line": { "type": "integer" }, "excerpt": { "type": "string" }, "verdict": { "type": "string" }, "verified_at": { "type": "string", "format": "date-time" }, "verifier": { "type": "string" }, "document": { "type": "string", "description": "DOC: holding the artifact's text." }, "note": { "type": "string" }, "claim": { "type": "string", "description": "FRAME:: of the cited claim, for kind claim." } } } }, "rests_on": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "relation": { "type": "string", "enum": [ "supports", "challenges" ] }, "evidence_id": { "type": "string" } }, "required": [ "id", "relation", "evidence_id" ] } }, "cited_by": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "relation": { "type": "string", "enum": [ "supports", "challenges" ] }, "evidence_id": { "type": "string" } }, "required": [ "id", "relation", "evidence_id" ] } }, "content": { "type": "string" }, "content_revision": { "type": "string", "description": "SHA-256 of returned claim, evidence, dependencies and content." }, "evidence_scope": { "type": "string", "const": "recorded_ledger_observations" } }, "required": [ "id", "kg_id", "frame_id", "document_id", "title", "chunk_id", "claim", "evidence", "rests_on", "cited_by", "content", "content_revision", "evidence_scope" ] } }, "next_cursor": { "type": [ "string", "null" ] }, "exhausted": { "type": "boolean" }, "consistency": { "type": "string", "const": "live" }, "read_at": { "type": "string", "format": "date-time" } }, "required": [ "projection", "scope", "filters", "total", "returned", "results", "next_cursor", "exhausted", "consistency", "read_at" ] } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "working_group_id": { "type": "string", "format": "uuid" }, "kg_ids": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" }, "maxItems": 1000 }, "set_id": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "working_group_id" ] }, { "type": "object", "properties": { "view": { "type": "string", "enum": [ "summary", "all" ], "default": "summary" }, "kinds": { "type": [ "array", "null" ], "maxItems": 32, "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "verdicts": { "type": [ "array", "null" ], "maxItems": 32, "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "document_id": { "type": [ "string", "null" ], "format": "uuid" }, "section": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 512, "description": "Case-insensitive literal substring." }, "about": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 512, "description": "Case-insensitive literal substring." } }, "required": [] }, { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "cursor": { "type": [ "string", "null" ], "maxLength": 16384, "description": "Opaque cursor bound to normalized scope and filters." } }, "required": [] } ], "unevaluatedProperties": false } } } }, "x-mcp": { "tool_name": "findings", "idempotent": true } } }, "/knowledge/claims/{kg_id}/{frame_id}": { "get": { "operationId": "readClaim_Knowledge", "x-method": "GET", "x-path": "/knowledge/claims/{kg_id}/{frame_id}", "x-handler": "handlers::claims_evidence::read_claim", "tags": [ "Knowledge Documents" ], "summary": "Expand a recorded claim and its live evidence.", "description": "Native bearer JWT reader over the same domain projection as MCP fetch. Without a group, requires exact KG access. An optional group preserves corpus membership, including shared KGs. Optional set requires group and owner/grantee entitlement; the claim must belong to that set. Each read reauthorizes. Compare content_revision with the earlier read. Archived, unpublished, removed, protected or inaccessible claims are absent.", "responses": { "200": { "description": "Expand a recorded claim and its live evidence.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kg_id": { "type": "string", "format": "uuid" }, "frame_id": { "type": "string" }, "document_id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "chunk_id": { "type": [ "string", "null" ] }, "claim": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "statement": { "type": "string" }, "kind": { "type": "string" }, "verdict": { "type": "string" }, "severity": { "type": "string" }, "section": { "type": "string" }, "supports": { "type": "integer", "minimum": 0, "description": "Eligible distinct observation records supporting the claim, counted in the read's transaction. Citations of other claims (evidence kind claim) are dependencies, listed in rests_on, and never counted." }, "challenges": { "type": "integer", "minimum": 0, "description": "Eligible distinct observation records challenging the claim; citations excluded." } }, "required": [ "id", "key", "statement", "supports", "challenges" ] }, "evidence": { "type": "array", "items": { "type": "object", "required": [ "id", "relation", "kind" ], "properties": { "id": { "type": "string", "description": "FRAME::" }, "relation": { "type": "string", "enum": [ "supports", "challenges" ] }, "kind": { "type": "string" }, "artifact": { "type": "string" }, "ref": { "type": "string" }, "path": { "type": "string" }, "line": { "type": "integer" }, "excerpt": { "type": "string" }, "verdict": { "type": "string" }, "verified_at": { "type": "string", "format": "date-time" }, "verifier": { "type": "string" }, "document": { "type": "string", "description": "DOC: holding the artifact's text." }, "note": { "type": "string" }, "claim": { "type": "string", "description": "FRAME:: of the cited claim, for kind claim." } } } }, "rests_on": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "relation": { "type": "string", "enum": [ "supports", "challenges" ] }, "evidence_id": { "type": "string" } }, "required": [ "id", "relation", "evidence_id" ] } }, "cited_by": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "relation": { "type": "string", "enum": [ "supports", "challenges" ] }, "evidence_id": { "type": "string" } }, "required": [ "id", "relation", "evidence_id" ] } }, "content": { "type": "string" }, "content_revision": { "type": "string", "description": "SHA-256 of returned claim, evidence, dependencies and content." }, "evidence_scope": { "type": "string", "const": "recorded_ledger_observations" } }, "required": [ "id", "kg_id", "frame_id", "document_id", "title", "chunk_id", "claim", "evidence", "rests_on", "cited_by", "content", "content_revision", "evidence_scope" ] } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "parameters": [ { "name": "kg_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "frame_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "working_group_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "set_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ] } }, "/knowledge/documents": { "get": { "operationId": "listDocuments_Knowledge", "x-method": "GET", "x-path": "/knowledge/documents", "x-handler": "handlers::knowledge_documents::list_documents", "tags": [ "Knowledge Documents" ], "summary": "Paginated list of knowledge documents with optional filters.", "description": "Returns up to `limit` knowledge documents (default 20) with the\nmatching pagination metadata (`total`, `limit`, `offset`). All\nfilters AND-compose. `kg_id` scopes the listing to a single KG;\nomit it to span every KG the caller can read. `document_type` and\n`source_type` filter by metadata classifiers (e.g. `news`, `rss`).\n`status` defaults to `active`; pass `archived` (or another status\nmarker) to see retired rows. Read-only. Auth: bearer JWT.\n", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum rows to return. Default 20.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 20 } }, { "name": "offset", "in": "query", "required": false, "description": "Offset for pagination.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "document_type", "in": "query", "required": false, "description": "Filter by document classifier (e.g. `news`, `report`).", "schema": { "type": "string" } }, { "name": "source_type", "in": "query", "required": false, "description": "Filter by source classifier (e.g. `rss`, `upload`).", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by document status. Defaults to `active`.", "schema": { "type": "string", "default": "active" } }, { "name": "kg_id", "in": "query", "required": false, "description": "Restrict to a single KG. Omit to span every KG the caller can read.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Document page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "documents", "total", "limit", "offset" ], "properties": { "documents": { "type": "array", "items": { "type": "object", "description": "A document — the wire-form projection of a `concept_type='document'` frame.", "required": [ "id", "document_type", "source_type", "title", "content", "fetched_at", "tags", "extracted_concepts", "metadata" ], "properties": { "id": { "type": "string", "format": "uuid" }, "document_type": { "type": "string" }, "source_type": { "type": "string" }, "source_id": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "summary": { "type": [ "string", "null" ] }, "content": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "author": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "fetched_at": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "type": "string" } }, "extracted_concepts": { "type": "array", "items": { "type": "string" } }, "metadata": { "description": "Arbitrary JSON value." } } } }, "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1 }, "offset": { "type": "integer", "minimum": 0 } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listDocuments_Knowledge", "resource_uri": "yf://agents/knowledge/documents", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/knowledge/documents?kg_id=$KG_ID&document_type=news&limit=50\"" } ], "x-related": [ { "operationId": "getDocument_Knowledge", "relation": "sibling" }, { "operationId": "searchDocuments_Knowledge", "relation": "sibling" }, { "operationId": "fetchNews_Knowledge", "relation": "sibling" }, { "guide": "knowledge", "relation": "concept" } ] } }, "/knowledge/documents/count": { "post": { "operationId": "countDocumentsLexical_Knowledge", "x-method": "POST", "x-path": "/knowledge/documents/count", "x-handler": "handlers::knowledge_documents::count_documents_lexical", "tags": [ "Knowledge Documents" ], "summary": "Exhaustive lexical tallies — counted, never ranked.", "description": "The counted half of the two-guarantee rule: a ranked result never\nreports a total, a counted result never reports a rank. For up to 16\nterms, returns how many frames match and how many distinct published\ndocuments those frames resolve to — through the same provenance join\nand KG scoping `retrieve` uses, so a count can never disagree with\nwhat a search then shows.\n\nCounts are lexical only and explicitly capped: `frames_capped` /\n`documents_capped` say when a tally is a floor rather than an exact\nnumber. When no term is capped the response also carries the union\ncount and each term's unique contribution (documents matched by that\nterm alone) — the numbers a term list is negotiated over.\n\nModes: `exact` (default) is `simple`-config full text with no\nstemming, so identifiers match only themselves; `phrase` is\n`english`-config websearch syntax; `fuzzy` is a trigram substring\nscan that matches inside words and must never be presented as a\nreportable bound.\n\nAccess control is identical to `retrieve`: document-view access to\n`working_group_id`, requested `kg_ids` must belong to it, and an\nexplicit empty scope returns zero counts rather than falling through\nto an unscoped query.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "working_group_id", "terms" ], "properties": { "working_group_id": { "type": "string", "format": "uuid", "description": "Private corpus boundary. The caller must have document-view access." }, "kg_ids": { "type": [ "array", "null" ], "maxItems": 1000, "uniqueItems": true, "items": { "type": "string", "format": "uuid" }, "description": "Optional KG allow-list. Omitted counts over every KG owned by `working_group_id`; an explicit empty array counts nothing." }, "terms": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "type": "object", "required": [ "term" ], "properties": { "term": { "type": "string", "minLength": 1, "maxLength": 512 }, "mode": { "type": "string", "enum": [ "exact", "phrase", "fuzzy" ], "default": "exact", "description": "`exact` — `simple`-config full text, no stemming: an ACN or clause number matches only itself. `phrase` — `english`-config websearch syntax (stemming, quoted phrases, OR, -negation). `fuzzy` — trigram substring scan; for short terms it matches inside words (`%ATO%` counts \"regulatory\"), so fuzzy counts are exploratory and must not be reported as bounds." } } } }, "as_of": { "type": [ "string", "null" ], "format": "date-time", "description": "Pin the count to a corpus state so the same request regenerates the same number. Same shape as retrieval's `as_of`." } } }, "examples": { "term_panel": { "summary": "A term panel refreshing its true counts", "value": { "working_group_id": "11111111-1111-4111-8111-111111111111", "terms": [ { "term": "ATO", "mode": "exact" }, { "term": "Australian Taxation Office", "mode": "phrase" } ], "as_of": "2026-07-29T00:00:00Z" } } } } } }, "responses": { "200": { "description": "Per-term tallies plus union/unique arithmetic when uncapped.", "content": { "application/json": { "schema": { "type": "object", "required": [ "terms", "union_capped", "frame_cap", "document_cap" ], "properties": { "as_of": { "type": [ "string", "null" ], "format": "date-time" }, "terms": { "type": "array", "items": { "type": "object", "required": [ "term", "mode", "frames", "frames_capped", "documents", "documents_capped" ], "properties": { "term": { "type": "string" }, "mode": { "type": "string", "enum": [ "exact", "phrase", "fuzzy" ] }, "frames": { "type": "integer", "minimum": 0 }, "frames_capped": { "type": "boolean" }, "documents": { "type": "integer", "minimum": 0 }, "documents_capped": { "type": "boolean" }, "unique_documents": { "type": [ "integer", "null" ], "minimum": 0, "description": "Documents matched by this term and no other requested term. Null when any requested term was capped — set arithmetic over a truncated set would be silently wrong." } } } }, "union_documents": { "type": [ "integer", "null" ], "minimum": 0, "description": "Distinct documents matched by at least one term; null when capped." }, "union_capped": { "type": "boolean" }, "frame_cap": { "type": "integer" }, "document_cap": { "type": "integer" } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "422": { "description": "Malformed JSON, UUID, or RFC3339 timestamp." }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_countDocumentsLexical_Knowledge", "resource_uri": "yf://agents/knowledge/documents/count", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST https://agents.yieldfabric.com/knowledge/documents/count \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"working_group_id\":\"'$WG'\",\"terms\":[{\"term\":\"ATO\"}]}'\n" } ], "x-related": [ { "operationId": "matchDocumentsLexical_Knowledge", "relation": "sibling" }, { "operationId": "retrieveDocuments_Knowledge", "relation": "sibling" }, { "guide": "knowledge", "relation": "concept" } ] } }, "/knowledge/documents/count-in-set": { "post": { "operationId": "countDocumentsInSet_Knowledge", "x-method": "POST", "x-path": "/knowledge/documents/count-in-set", "x-handler": "handlers::knowledge_documents::count_documents_in_set", "tags": [ "Knowledge Documents" ], "summary": "Exhaustive tallies inside a frozen set — a total over a known denominator.", "description": "The strongest absence statement this API makes: \"of the 412 documents\nin this frozen set, ZERO contain X\" is a claim about a known\ndenominator, not about what a ranking happened to surface. `/count`\nanswers over a corpus that can change under you; this answers over\nmembership that cannot.\n\nThe response echoes `set_document_count` so a caller can state the\ndenominator without a second round trip — the claim is \"0 of 2,405\",\nnot \"0\". A `capped: true` term hit the scan bound and its figure is a\nfloor; never build an absence finding on one.\n\nSeparate from `/knowledge/documents/count` because it returns no frame\nnumber — inside a fixed membership the document tally is the whole\nanswer.\n\nAuthorized against the SET's own group, through the same predicate that\ndecides a single set: a set id names no tenant by itself, and the\ncaller never supplies a group id here. Readable by the owner **or** a\nlive grantee.\n\n1–16 terms, each at most 512 characters.\n\n**Access.** Bearer JWT. Authorization is `authorize_retrieval_group` —\nthe same `ViewDocuments` capability check (plus the group-creator\nfallback) every knowledge-documents endpoint runs. Deliberately NOT the\ngroup ids on the token: those are a different set, the more permissive\nof the two, and two opinions about who is in a group is how they drift\ninto a leak.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "set_id", "terms" ], "properties": { "set_id": { "type": "string", "format": "uuid", "description": "The set carries its own tenant — the group gate runs against the set ROW, never against a group id the caller supplies." }, "terms": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "type": "object", "required": [ "term" ], "properties": { "term": { "type": "string", "minLength": 1, "maxLength": 512 }, "mode": { "type": "string", "enum": [ "exact", "phrase", "fuzzy" ], "default": "exact" } } } }, "as_of": { "type": "string", "format": "date-time", "description": "Bounds which frames of those documents are visible. Independent of the set's own `as_of` — membership is already frozen." } } }, "examples": { "absence_finding": { "summary": "Establish that a term appears nowhere in a disclosed set", "value": { "set_id": "22222222-2222-4222-8222-222222222222", "terms": [ { "term": "indemnity", "mode": "exact" } ] } } } } } }, "responses": { "200": { "description": "Per-term totals over the frozen membership.", "content": { "application/json": { "schema": { "type": "object", "required": [ "set_id", "set_document_count", "terms" ], "properties": { "set_id": { "type": "string", "format": "uuid" }, "set_document_count": { "type": "integer", "minimum": 0, "description": "Echoed so a caller can state the denominator without a second round trip: the claim is \"0 of 2,405\", not \"0\"." }, "terms": { "type": "array", "items": { "type": "object", "required": [ "term", "mode", "documents", "capped" ], "properties": { "term": { "type": "string" }, "mode": { "type": "string", "enum": [ "exact", "phrase", "fuzzy" ] }, "documents": { "type": "integer", "minimum": 0, "description": "Exhaustive within the frozen membership — a total", "not a sample.": null }, "capped": { "type": "boolean", "description": "True means the scan hit its bound and the figure is a floor. Never build an absence finding on a capped count." }, "document_ids": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "400": { "description": "Empty term list, more than 16 terms, or a term over 512 characters." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_countDocumentsInSet_Knowledge", "resource_uri": "yf://agents/knowledge/documents/count-in-set", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \"https://agents.yieldfabric.com/knowledge/documents/count-in-set\" \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"set_id\":\"'$SET_ID'\",\"terms\":[{\"term\":\"indemnity\"}]}'\n" } ], "x-related": [ { "operationId": "countDocumentsLexical_Knowledge", "relation": "sibling" }, { "operationId": "getSet_Knowledge", "relation": "parent" }, { "operationId": "setMembers_Knowledge", "relation": "sibling" }, { "guide": "knowledge", "relation": "concept" } ] } }, "/knowledge/documents/fetch-news": { "post": { "operationId": "fetchNews_Knowledge", "x-method": "POST", "x-path": "/knowledge/documents/fetch-news", "x-handler": "handlers::knowledge_documents::fetch_news", "tags": [ "Knowledge Documents" ], "summary": "Fetch an RSS feed and chunk articles into the KG's RAG index.", "description": "Pulls articles from the supplied RSS feed URL, stores each as a\nknowledge document scoped to the named KG, then chunks the freshly\nstored documents through the RAG pipeline (embedding + position\nindex). Defaults `document_type` to `news` and `source_type` to\n`rss` when omitted. The response carries the count of articles\nstored and chunks created. Documents are persisted as per-KG\nframes (`concept_type='document'`), so the caller must name a\ntarget `kg_id`. The feed must be a public HTTP(S) URL. DNS results\nand every redirect hop are checked against private/reserved address\nranges and pinned for the connection; response streaming is capped\nat 10 MiB. Auth: bearer JWT.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "kg_id", "url", "source_id" ], "properties": { "kg_id": { "type": "string", "format": "uuid", "description": "KG that ingested articles land in (documents are per-KG frames)." }, "url": { "type": "string", "format": "uri", "description": "Public HTTP(S) RSS URL. Private/reserved DNS results and redirect\ndestinations are rejected; response body cap is 10 MiB.\n" }, "source_id": { "type": "string" }, "document_type": { "type": "string", "default": "news" }, "source_type": { "type": "string", "default": "rss" } } }, "examples": { "rss_feed": { "summary": "Ingest an RSS news feed", "value": { "kg_id": "9c1a4b2d-1f5a-4f6c-8c8b-1a2b3c4d5e6f", "url": "https://example.com/feed.xml", "source_id": "example_news", "document_type": "news", "source_type": "rss" } } } } } }, "responses": { "200": { "description": "Articles stored and chunked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "fetched" ], "properties": { "fetched": { "type": "integer", "minimum": 0 }, "documents": { "type": "array", "items": { "type": "object", "description": "A document — the wire-form projection of a `concept_type='document'` frame.", "required": [ "id", "document_type", "source_type", "title", "content", "fetched_at", "tags", "extracted_concepts", "metadata" ], "properties": { "id": { "type": "string", "format": "uuid" }, "document_type": { "type": "string" }, "source_type": { "type": "string" }, "source_id": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "summary": { "type": [ "string", "null" ] }, "content": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "author": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "fetched_at": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "type": "string" } }, "extracted_concepts": { "type": "array", "items": { "type": "string" } }, "metadata": { "description": "Arbitrary JSON value." } } } } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_fetchNews_Knowledge", "resource_uri": "yf://agents/knowledge/documents/fetch-news", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" \\\n \"https://agents.yieldfabric.com/knowledge/documents/fetch-news\" \\\n -d '{\"kg_id\": \"'\"$KG_ID\"'\", \"url\": \"https://example.com/feed.xml\", \"source_id\": \"example_news\"}'\n" } ], "x-related": [ { "operationId": "listDocuments_Knowledge", "relation": "sibling" }, { "operationId": "ragQuery_Knowledge", "relation": "sibling" }, { "guide": "knowledge", "relation": "concept" } ] } }, "/knowledge/documents/for-node/{node_id}": { "get": { "operationId": "getDocumentsForNode_Knowledge", "x-method": "GET", "x-path": "/knowledge/documents/for-node/{node_id}", "x-handler": "handlers::knowledge_documents::get_documents_for_node", "tags": [ "Knowledge Documents" ], "summary": "List documents linked to a specific KG node.", "description": "Returns every knowledge document explicitly linked to the given KG\nnode id via `linkDocumentToNode_Knowledge`. Used to populate the\n\"supporting evidence\" panel on a node-detail view — distinct from\nthe implicit RAG citations that surface in `getKgChunks_Kgs`. The\nlink payload (link type, evidence node, strength) is reflected in\nthe returned rows. Read-only and side-effect free. Auth: bearer JWT.\n", "parameters": [ { "name": "node_id", "in": "path", "required": true, "description": "KG node id (frame id string).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Documents linked to this node.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "A document — the wire-form projection of a `concept_type='document'` frame.", "required": [ "id", "document_type", "source_type", "title", "content", "fetched_at", "tags", "extracted_concepts", "metadata" ], "properties": { "id": { "type": "string", "format": "uuid" }, "document_type": { "type": "string" }, "source_type": { "type": "string" }, "source_id": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "summary": { "type": [ "string", "null" ] }, "content": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "author": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "fetched_at": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "type": "string" } }, "extracted_concepts": { "type": "array", "items": { "type": "string" } }, "metadata": { "description": "Arbitrary JSON value." } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getDocumentsForNode_Knowledge", "resource_uri": "yf://agents/knowledge/documents/for-node/{node_id}", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/knowledge/documents/for-node/$NODE_ID\"" } ], "x-related": [ { "operationId": "linkDocumentToNode_Knowledge", "relation": "sibling" }, { "operationId": "getDocument_Knowledge", "relation": "sibling" }, { "guide": "knowledge", "relation": "concept" } ] } }, "/knowledge/documents/match": { "post": { "operationId": "matchDocumentsLexical_Knowledge", "x-method": "POST", "x-path": "/knowledge/documents/match", "x-handler": "handlers::knowledge_documents::match_documents_lexical", "tags": [ "Knowledge Documents" ], "summary": "The set behind the count — exhaustive, unranked, keyset-paged.", "description": "Enumerates every published document matching one lexical term, in\nascending document-id order with keyset paging. No scoring, no top-K,\nno rerank: this is what a frozen review set or an enumerate-mode run\nconsumes. Same predicate, provenance join, and KG scoping as `count`,\nso the enumeration is exactly the set the count described.\n\nA term matching more than the frame-scan cap is refused with `422`\nrather than silently truncated — a partial enumeration presented as\nexhaustive is precisely the defect the counted surface exists to\nkill. Narrow the predicate (or use `count` first: an uncapped count\nimplies an enumerable term).\n\nPass a pinned `as_of` when paging: it keeps every page reading the\nsame corpus state, and `next_after` cursors stay stable.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "working_group_id", "term" ], "properties": { "working_group_id": { "type": "string", "format": "uuid" }, "kg_ids": { "type": [ "array", "null" ], "maxItems": 1000, "uniqueItems": true, "items": { "type": "string", "format": "uuid" } }, "term": { "type": "string", "minLength": 1, "maxLength": 512 }, "mode": { "type": "string", "enum": [ "exact", "phrase", "fuzzy" ], "default": "exact" }, "as_of": { "type": [ "string", "null" ], "format": "date-time" }, "after_document_id": { "type": [ "string", "null" ], "description": "Keyset cursor — the last document id of the previous page." }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 500 } } }, "examples": { "first_page": { "summary": "First page of an enumeration", "value": { "working_group_id": "11111111-1111-4111-8111-111111111111", "term": "ATO", "mode": "exact", "as_of": "2026-07-29T00:00:00Z", "limit": 500 } }, "next_page": { "summary": "Continue from a cursor", "value": { "working_group_id": "11111111-1111-4111-8111-111111111111", "term": "ATO", "mode": "exact", "as_of": "2026-07-29T00:00:00Z", "after_document_id": "44b322e9-aee2-4b80-b716-68d0444d9e15", "limit": 500 } } } } } }, "responses": { "200": { "description": "One page; `exhausted: true` on the last.", "content": { "application/json": { "schema": { "type": "object", "required": [ "document_ids", "exhausted" ], "properties": { "document_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Ascending document ids; stable across pages for a pinned `as_of`." }, "next_after": { "type": [ "string", "null" ], "description": "Pass back as `after_document_id`; null when exhausted." }, "exhausted": { "type": "boolean" } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "422": { "description": "Malformed input, or the term is broader than the frame-scan cap and cannot be exhaustively enumerated." }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_matchDocumentsLexical_Knowledge", "resource_uri": "yf://agents/knowledge/documents/match", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST https://agents.yieldfabric.com/knowledge/documents/match \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"working_group_id\":\"'$WG'\",\"term\":\"ATO\",\"limit\":500}'\n" } ], "x-related": [ { "operationId": "countDocumentsLexical_Knowledge", "relation": "sibling" }, { "operationId": "retrieveDocuments_Knowledge", "relation": "sibling" }, { "guide": "knowledge", "relation": "concept" } ] } }, "/knowledge/documents/query": { "post": { "operationId": "ragQuery_Knowledge", "x-method": "POST", "x-path": "/knowledge/documents/query", "x-handler": "handlers::knowledge_documents::rag_query", "tags": [ "Knowledge Documents" ], "summary": "End-to-end RAG query — retrieve, rerank, generate.", "description": "Runs the full RAG pipeline on a natural-language query: HyDE-augmented\nretrieval (toggle with `use_hyde`), optional GraphRAG node traversal\n(toggle with `use_graph_rag`), rerank to the top `top_n`, and final\nLLM generation. Returns the generated `answer` plus citations\n(document title, URL, excerpt, publication date), a confidence\nscore, chunks-retrieved count, graph-nodes-traversed count, and the\nretrieval strategy that fired. Defaults: `top_k=20`, `top_n=6`,\n`use_hyde=true`, `use_graph_rag=true`. Burns LLM and embedding\nbudget proportional to the chunk count. Auth: bearer JWT.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string" }, "top_k": { "type": "integer", "default": 20, "minimum": 1 }, "top_n": { "type": "integer", "default": 6, "minimum": 1 }, "use_hyde": { "type": "boolean", "default": true }, "use_graph_rag": { "type": "boolean", "default": true } } }, "examples": { "question": { "summary": "Ask a question over the knowledge index", "value": { "query": "What's the principal of the loan to Beta Industries?", "top_k": 20, "top_n": 6, "use_hyde": true, "use_graph_rag": true } } } } } }, "responses": { "200": { "description": "Generated answer + citations.", "content": { "application/json": { "schema": { "type": "object", "required": [ "answer", "citations", "chunks_retrieved" ], "properties": { "answer": { "type": "string" }, "citations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "excerpt": { "type": [ "string", "null" ] } } } }, "confidence": { "type": [ "number", "null" ] }, "chunks_retrieved": { "type": "integer", "minimum": 0 }, "graph_nodes_traversed": { "type": [ "integer", "null" ], "minimum": 0 }, "strategy_used": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_ragQuery_Knowledge", "resource_uri": "yf://agents/knowledge/documents/query", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" \\\n \"https://agents.yieldfabric.com/knowledge/documents/query\" \\\n -d '{\"query\": \"What is the loan principal?\", \"top_k\": 20, \"top_n\": 6}'\n" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx, os\nr = httpx.post(\n \"https://agents.yieldfabric.com/knowledge/documents/query\",\n json={\"query\": \"What is the loan principal?\", \"top_k\": 20, \"top_n\": 6, \"use_hyde\": True, \"use_graph_rag\": True},\n headers={\"Authorization\": f\"Bearer {os.environ['JWT']}\"},\n timeout=60.0,\n)\nr.raise_for_status()\nout = r.json()\nprint(out[\"answer\"])\nfor c in out[\"citations\"]:\n print(\"-\", c[\"title\"], c.get(\"url\"))\n" } ], "x-related": [ { "operationId": "searchDocuments_Knowledge", "relation": "sibling" }, { "operationId": "listDocuments_Knowledge", "relation": "sibling" }, { "guide": "knowledge", "relation": "concept" } ] } }, "/knowledge/documents/retrieve": { "post": { "operationId": "retrieveDocuments_Knowledge", "x-method": "POST", "x-path": "/knowledge/documents/retrieve", "x-handler": "handlers::knowledge_documents::retrieve_documents", "tags": [ "Knowledge Documents" ], "summary": "Scoped hybrid retrieval without answer generation.", "description": "Embeds `query`, runs the canonical vector + keyword/BM25 + graph retrieval\npaths, fuses and reranks eligible evidence, and returns ranked chunks without\ngenerating an answer.\n\nThe caller must have document-view access to `working_group_id`. Every\nrequested `kg_id` must belong to that working group; an inaccessible,\nunknown, or cross-group KG fails with `403`. Omitted `kg_ids` resolves to\nevery KG owned by the working group. An explicit empty `kg_ids` or\n`include_document_ids` array returns an empty result set.\n\nSource-document include/exclude, document-type, tag, KG, and `as_of`\npredicates are applied inside the canonical provenance projection before\neach retrieval path's candidate limit. Exclusion wins over inclusion.\nMulti-source frames keep only eligible provenance and are discarded when no\neligible source remains, so an excluded source cannot reappear through a\nmerged KG. Each UUID list accepts at most 1,000 values.\n\nEach retrieval path nominates three candidates per requested result\n(capped at 24, never fewer than `top_k`), and the reranker chooses\n`top_k` of the fused pool. The pool used to equal `top_k`, which left\nthe reranker nothing to choose from: for a general question the nearest\nneighbours by embedding are the blended heads of long pages, and a short\npassage that answers outright never reached the one stage that can tell\nthe two apart. The reranker scores the pool in one call, so a wider pool\ncosts a proportionally larger rerank prompt.\n\nEmbedding and reranking usage is attributed through the normal metering path\nto the authenticated entity and working group. Sponsored JWTs retain their\nrequest-scoped sponsor attribution.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "working_group_id", "query" ], "properties": { "working_group_id": { "type": "string", "format": "uuid", "description": "Private corpus boundary. The caller must have document-view access." }, "query": { "type": "string", "minLength": 1, "maxLength": 10000 }, "kg_ids": { "type": [ "array", "null" ], "maxItems": 1000, "uniqueItems": true, "items": { "type": "string", "format": "uuid" }, "description": "Optional KG allow-list. Omitted searches every KG owned by `working_group_id`; an explicit empty array matches nothing." }, "include_document_ids": { "type": [ "array", "null" ], "maxItems": 1000, "uniqueItems": true, "items": { "type": "string", "format": "uuid" }, "description": "Optional immutable source-document allow-list. Omitted means no document allow-list; an explicit empty array matches nothing." }, "exclude_document_ids": { "type": "array", "maxItems": 1000, "uniqueItems": true, "default": [], "items": { "type": "string", "format": "uuid" }, "description": "Source-document deny-list. Exclusion wins over an overlapping include." }, "top_k": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 }, "min_score": { "type": "number", "minimum": 0, "maximum": 1, "default": 0 }, "document_types": { "type": [ "array", "null" ], "maxItems": 64, "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "tags": { "type": [ "array", "null" ], "maxItems": 64, "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "as_of": { "type": [ "string", "null" ], "format": "date-time" } } }, "examples": { "single_kg": { "summary": "Search one KG", "value": { "working_group_id": "11111111-1111-4111-8111-111111111111", "query": "PwC advice concerning R&D eligibility", "kg_ids": [ "22222222-2222-4222-8222-222222222222" ], "top_k": 30, "min_score": 0.25 } }, "multi_kg": { "summary": "Search the union of selected KGs", "value": { "working_group_id": "11111111-1111-4111-8111-111111111111", "query": "PwC advice concerning R&D eligibility", "kg_ids": [ "22222222-2222-4222-8222-222222222222", "33333333-3333-4333-8333-333333333333" ], "top_k": 30 } }, "document_scope": { "summary": "Search an eligible document shard and exclude visited files", "value": { "working_group_id": "11111111-1111-4111-8111-111111111111", "query": "PwC advice concerning R&D eligibility", "kg_ids": [ "22222222-2222-4222-8222-222222222222" ], "include_document_ids": [ "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaa1", "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaa2" ], "exclude_document_ids": [ "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaa1" ], "top_k": 30, "min_score": 0.25 } } } } } }, "responses": { "200": { "description": "Ranked eligible evidence; `results` may be empty.", "content": { "application/json": { "schema": { "type": "object", "required": [ "query", "results" ], "properties": { "query": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "required": [ "rank", "score", "content", "title", "document_id", "source_document_ids", "kg_id", "chunk_id", "metadata" ], "properties": { "rank": { "type": "integer", "minimum": 1 }, "score": { "type": "number" }, "content": { "type": "string" }, "title": { "type": "string" }, "document_id": { "type": "string", "format": "uuid" }, "source_document_ids": { "type": "array", "uniqueItems": true, "items": { "type": "string", "format": "uuid" }, "description": "Eligible provenance only; excluded source UUIDs are never returned." }, "kg_id": { "type": "string", "format": "uuid" }, "chunk_id": { "type": "string", "description": "Stable frame/chunk identifier inside `kg_id`." }, "metadata": { "description": "Arbitrary JSON value." } } } } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "422": { "description": "Malformed JSON, UUID, or RFC3339 timestamp." }, "429": { "description": "Too much AI in flight for this person (`inference_limit`), with\n`Retry-After` — the same refusal the request gate sends, raised here\nbecause retrieval's own model calls (HyDE, the reranker) run past the\ngate. Not an error: retry after the interval. A client fanning out\nacross campaigns should bound its concurrency to the per-person\nceiling rather than race to be refused.\n" }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_retrieveDocuments_Knowledge", "resource_uri": "yf://agents/knowledge/documents/retrieve", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST https://agents.yieldfabric.com/knowledge/documents/retrieve \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d @retrieval-shard.json\n" }, { "lang": "python", "label": "Python (256-document shard)", "source": "import os\nimport httpx\n\neligible_document_ids = load_next_256_document_ids()\nresponse = httpx.post(\n \"https://agents.yieldfabric.com/knowledge/documents/retrieve\",\n headers={\"Authorization\": f\"Bearer {os.environ['JWT']}\"},\n json={\n \"working_group_id\": os.environ[\"WORKING_GROUP_ID\"],\n \"query\": \"PwC advice concerning R&D eligibility\",\n \"kg_ids\": [os.environ[\"INTAKE_KG_ID\"]],\n \"include_document_ids\": eligible_document_ids,\n \"exclude_document_ids\": visited_document_ids,\n \"top_k\": 30,\n \"min_score\": 0.25,\n },\n timeout=60,\n)\nresponse.raise_for_status()\nprint(response.json()[\"results\"])\n" } ], "x-related": [ { "operationId": "searchDocuments_Knowledge", "relation": "sibling" }, { "operationId": "ragQuery_Knowledge", "relation": "sibling" }, { "operationId": "chatCompletions_Openai", "relation": "alternative" }, { "guide": "knowledge", "relation": "concept" } ] } }, "/knowledge/documents/search": { "get": { "operationId": "searchDocuments_Knowledge", "x-method": "GET", "x-path": "/knowledge/documents/search", "x-handler": "handlers::knowledge_documents::search_documents", "tags": [ "Knowledge Documents" ], "summary": "Embedding-based document similarity search.", "description": "Embeds the supplied `query` and returns the top `limit` similar\ndocuments (default 20) with their cosine similarity scores. Unlike\n`ragQuery_Knowledge` this is retrieval-only — no rerank, no\ngeneration, no graph traversal. Filters: `document_type` restricts\nby classifier; `min_score` drops results below the threshold (range\n0.0 to 1.0); `kg_id` scopes to a single KG. Useful for source-\ncuration flows and for fast \"is there already a doc on this?\"\nduplicate checks. Burns one embedding call per request. Auth: bearer\nJWT.\n", "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Natural-language search query.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum rows to return. Default 20.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 20 } }, { "name": "document_type", "in": "query", "required": false, "description": "Filter by document classifier.", "schema": { "type": "string" } }, { "name": "min_score", "in": "query", "required": false, "description": "Drop results with similarity below this threshold.", "schema": { "type": "number", "minimum": 0, "maximum": 1 } }, { "name": "kg_id", "in": "query", "required": false, "description": "Restrict to a single KG.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Ranked document hits with similarity scores.", "content": { "application/json": { "schema": { "type": "object", "required": [ "documents", "query" ], "properties": { "documents": { "type": "array", "items": { "type": "object", "required": [ "document", "similarity_score" ], "properties": { "document": { "type": "object", "description": "A document — the wire-form projection of a `concept_type='document'` frame.", "required": [ "id", "document_type", "source_type", "title", "content", "fetched_at", "tags", "extracted_concepts", "metadata" ], "properties": { "id": { "type": "string", "format": "uuid" }, "document_type": { "type": "string" }, "source_type": { "type": "string" }, "source_id": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "summary": { "type": [ "string", "null" ] }, "content": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "author": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "fetched_at": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "type": "string" } }, "extracted_concepts": { "type": "array", "items": { "type": "string" } }, "metadata": { "description": "Arbitrary JSON value." } } }, "similarity_score": { "type": "number" } } } }, "query": { "type": "string" } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_searchDocuments_Knowledge", "resource_uri": "yf://agents/knowledge/documents/search", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/knowledge/documents/search?query=loan%20principal&limit=20&min_score=0.6\"" } ], "x-related": [ { "operationId": "ragQuery_Knowledge", "relation": "sibling" }, { "operationId": "listDocuments_Knowledge", "relation": "sibling" }, { "operationId": "getDocument_Knowledge", "relation": "sibling" }, { "guide": "knowledge", "relation": "concept" } ] } }, "/knowledge/documents/{id}": { "get": { "operationId": "getDocument_Knowledge", "x-method": "GET", "x-path": "/knowledge/documents/{id}", "x-handler": "handlers::knowledge_documents::get_document", "tags": [ "Knowledge Documents" ], "summary": "Fetch a single knowledge document by id.", "description": "Returns one knowledge document row by id, with all fields the listing\nendpoint surfaces plus the full `content` body. Used for document\ndetail panes and for re-hydration when a caller already has the\ndocument id (e.g. from a RAG citation). Returns 400 when `id` is\nnot a valid UUID and 404 when the document is not present. Read-only.\nAuth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Knowledge document id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Document row.", "content": { "application/json": { "schema": { "type": "object", "description": "A document — the wire-form projection of a `concept_type='document'` frame.", "required": [ "id", "document_type", "source_type", "title", "content", "fetched_at", "tags", "extracted_concepts", "metadata" ], "properties": { "id": { "type": "string", "format": "uuid" }, "document_type": { "type": "string" }, "source_type": { "type": "string" }, "source_id": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "summary": { "type": [ "string", "null" ] }, "content": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "author": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "fetched_at": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "type": "string" } }, "extracted_concepts": { "type": "array", "items": { "type": "string" } }, "metadata": { "description": "Arbitrary JSON value." } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getDocument_Knowledge", "resource_uri": "yf://agents/knowledge/documents/{id}", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/knowledge/documents/$DOC_ID\"" } ], "x-related": [ { "operationId": "listDocuments_Knowledge", "relation": "sibling" }, { "operationId": "searchDocuments_Knowledge", "relation": "sibling" }, { "operationId": "linkDocumentToNode_Knowledge", "relation": "sibling" }, { "guide": "knowledge", "relation": "concept" } ] } }, "/knowledge/documents/{id}/link": { "post": { "operationId": "linkDocumentToNode_Knowledge", "x-method": "POST", "x-path": "/knowledge/documents/{id}/link", "x-handler": "handlers::knowledge_documents::link_document_to_node", "tags": [ "Knowledge Documents" ], "summary": "Attach a knowledge document to a KG node as supporting evidence.", "description": "Creates a `(document, node, link_type)` association in the document\nlink table. The link carries an optional `evidence_node_id` (to point\nat the specific frame within the document that supports the target)\nand an optional `strength` score. Used to record manual or\nsemi-automatic curation of which documents back which KG nodes —\ncomplementing the implicit RAG-citation links surfaced via\n`getKgChunks_Kgs`. Returns the new `link_id` plus the\n`evidence_node_id` echo. Validates that `id` is a valid UUID. Auth:\nbearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Knowledge document id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "node_id", "link_type" ], "properties": { "node_id": { "type": "string" }, "link_type": { "type": "string", "description": "e.g. `mention`, `evidence`, `definition`, `implication`." }, "evidence_node_id": { "type": [ "string", "null" ] }, "strength": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 } } }, "examples": { "evidence_link": { "summary": "Link a document to a node as evidence", "value": { "node_id": "party_acme_capital", "link_type": "evidence", "evidence_node_id": "claim_loan_principal", "strength": 0.92 } } } } } }, "responses": { "201": { "description": "Link created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "linked" ], "properties": { "linked": { "type": "boolean" }, "link_id": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "409": { "description": "The document UUID is present in more than one knowledge graph the caller may modify; use a KG-scoped identity.", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_linkDocumentToNode_Knowledge", "resource_uri": "yf://agents/knowledge/documents/{id}/link", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" \\\n \"https://agents.yieldfabric.com/knowledge/documents/$DOC_ID/link\" \\\n -d '{\"node_id\": \"party_acme_capital\", \"link_type\": \"evidence\", \"strength\": 0.9}'\n" } ], "x-related": [ { "operationId": "getDocumentsForNode_Knowledge", "relation": "sibling" }, { "operationId": "getDocument_Knowledge", "relation": "sibling" }, { "guide": "knowledge", "relation": "concept" } ] } }, "/knowledge/documents/{id}/claims": { "get": { "operationId": "getDocumentClaims_Knowledge", "x-method": "GET", "x-path": "/knowledge/documents/{id}/claims", "x-handler": "handlers::claims_evidence::get_document_claims", "tags": [ "Knowledge Documents" ], "summary": "Read a document's ledger of claims and evidence as stored.", "description": "Every claim written for the document by `PUT …/claims`, each with the\nentities it is `about`, the chunk it was located to (`located: false`\nwhen the quote was not found and the claim cites the document itself), and its\nobservations with their locators, verdicts and `verified_at`. Ids are\n`FRAME::` throughout, so each is fetchable and\nexplorable through MCP. Read-only; gated on an accessible KG (404\notherwise); `kg_id` disambiguates a document id present in several\naccessible KGs (409 otherwise). Auth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Knowledge document id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "kg_id", "in": "query", "required": false, "description": "The KG holding the document, when the id occurs in more than one.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The ledger.", "content": { "application/json": { "schema": { "type": "object", "required": [ "document_id", "kg_id", "claims" ], "properties": { "document_id": { "type": "string", "format": "uuid" }, "kg_id": { "type": "string", "format": "uuid" }, "claims": { "type": "array", "items": { "type": "object", "required": [ "id", "key", "statement", "supports", "challenges", "located", "about", "evidence" ], "properties": { "id": { "type": "string", "description": "FRAME::" }, "key": { "type": "string" }, "statement": { "type": "string" }, "kind": { "type": "string" }, "verdict": { "type": "string" }, "severity": { "type": "string" }, "section": { "type": "string" }, "supports": { "type": "integer", "description": "Eligible distinct observation records supporting the claim. Citations of other claims (evidence kind claim) are dependencies and never counted." }, "challenges": { "type": "integer", "description": "Eligible distinct observation records challenging the claim; citations excluded." }, "located": { "type": "boolean" }, "chunk_id": { "type": "string", "description": "Frame id of the chunk the claim was located to; absent when located is false (the claim cites the document itself)." }, "about": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" } } } }, "evidence": { "type": "array", "items": { "type": "object", "required": [ "id", "relation", "kind" ], "properties": { "id": { "type": "string", "description": "FRAME::" }, "relation": { "type": "string", "enum": [ "supports", "challenges" ] }, "kind": { "type": "string" }, "artifact": { "type": "string" }, "ref": { "type": "string" }, "path": { "type": "string" }, "line": { "type": "integer" }, "excerpt": { "type": "string" }, "verdict": { "type": "string" }, "verified_at": { "type": "string", "format": "date-time" }, "verifier": { "type": "string" }, "document": { "type": "string", "description": "DOC: holding the artifact's text." }, "note": { "type": "string" }, "claim": { "type": "string", "description": "FRAME:: of the cited claim, for kind claim." } } } } } } } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "409": { "description": "Conflicting state (e.g. step already completed, intent already cancelled, duplicate idempotency key with different body).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getDocumentClaims_Knowledge", "resource_uri": "yf://agents/knowledge/documents/{id}/claims", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/knowledge/documents/$DOC_ID/claims\"" } ], "x-related": [ { "operationId": "putDocumentClaims_Knowledge", "relation": "sibling" }, { "operationId": "getDocument_Knowledge", "relation": "sibling" }, { "guide": "knowledge", "relation": "concept" } ] }, "put": { "operationId": "putDocumentClaims_Knowledge", "x-method": "PUT", "x-path": "/knowledge/documents/{id}/claims", "x-handler": "handlers::claims_evidence::put_document_claims", "tags": [ "Knowledge Documents" ], "summary": "Replace a document's ledger of claims and the evidence behind each.", "description": "Writes what a document asserts — claims — and the observations that\nsupport or challenge each one, as frames in the document's knowledge\ngraph: a claim is a `state` frame linked by `source_chunk` to the chunk\nthat states it and by `about` to the entities it concerns; an\nobservation is a `speech_act` (stance `support` / `challenge`) that\n`target`s the claim and carries its locator (`artifact`, `ref`, `path`,\n`line`, `excerpt`), the verifier's `verdict` and `verified_at`. Model\nand rationale: `docs/architecture/claims-and-evidence.md`.\n\nThe request is the document's whole ledger. Frame ids are deterministic\nper `(document, key[, locator])`, so re-sending upserts; claims and\nobservations of this document that are not in the request are deleted.\nEntity frames are resolved by label (and type) and created when\nmissing, never deleted. Each claim is located in the document by its\n`quote` (default: the statement); one that is not found cites the\ndocument itself (`source_document`) with `located: false`.\n\nNo model runs. The KG's embedding backfill is drained before the\nresponse so the claims are searchable when it arrives. Once stored, a\nretrieval hit on a claim carries its evidence rendered into `content`\nand structured in `metadata.evidence`; a hit on an observation carries\nits claim. MCP `fetch` and `explore` expose the same.\n\nA write to the document's KG: gated like an upload to the owning group\n(`UploadDocuments`). `kg_id` is required when the document id occurs\nin more than one accessible KG (409 otherwise). Limits: 2,000 claims\nper request, 50 observations and 12 `about` entries per claim.\nAuth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Knowledge document id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "claims" ], "properties": { "kg_id": { "type": "string", "format": "uuid", "description": "Required when the document id occurs in several accessible KGs." }, "compiler": { "type": "string", "description": "Recorded as created_by on every frame." }, "asserted_at": { "type": "string", "format": "date-time", "description": "Default verified_at for observations without one." }, "claims": { "type": "array", "maxItems": 2000, "items": { "type": "object", "required": [ "key", "statement" ], "properties": { "key": { "type": "string", "maxLength": 200, "description": "Stable within the document; no ':'." }, "statement": { "type": "string", "maxLength": 4000 }, "kind": { "type": "string", "description": "finding | fact | verdict | risk | requirement | question." }, "verdict": { "type": "string" }, "severity": { "type": "string" }, "section": { "type": "string" }, "quote": { "type": "string", "description": "Text to locate in the document's chunks; defaults to the statement." }, "about": { "type": "array", "maxItems": 12, "items": { "type": "object", "required": [ "label" ], "properties": { "type": { "type": "string" }, "label": { "type": "string" } } } }, "evidence": { "type": "array", "maxItems": 50, "items": { "type": "object", "required": [ "relation", "kind" ], "properties": { "relation": { "type": "string", "enum": [ "supports", "challenges" ] }, "kind": { "type": "string", "description": "code_line | code_path | absence | document_span | register_row | command_output | inspection | claim (another claim of this ledger, named by claim_key)." }, "artifact": { "type": "string", "description": "Repository", "document or dataset the observation is in.": null }, "ref": { "type": "string", "description": "The version read (branch", "tag": null, "commit).": null }, "path": { "type": "string" }, "line": { "type": "integer" }, "excerpt": { "type": "string", "maxLength": 2000 }, "verdict": { "type": "string", "description": "The verifier's verdict on the observation (ok | stale | missing)." }, "verified_at": { "type": "string", "format": "date-time" }, "verifier": { "type": "string" }, "document_id": { "type": "string", "format": "uuid", "description": "A corpus document holding the artifact's text." }, "note": { "type": "string" }, "claim_key": { "type": "string", "description": "For kind claim", "the key of the cited claim in the same ledger; must not be the citing claim.": null } } } } } } } } } } } }, "responses": { "200": { "description": "What the replace did.", "content": { "application/json": { "schema": { "type": "object", "required": [ "document_id", "kg_id", "claims", "evidence", "entities_created", "removed", "located", "unlocated" ], "properties": { "document_id": { "type": "string", "format": "uuid" }, "kg_id": { "type": "string", "format": "uuid" }, "claims": { "type": "integer" }, "evidence": { "type": "integer" }, "entities_created": { "type": "integer" }, "removed": { "type": "integer", "description": "Claims and observations of this document deleted because the request no longer carried them." }, "located": { "type": "integer", "description": "Claims whose quote was found in a chunk." }, "unlocated": { "type": "integer" } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "409": { "description": "Conflicting state (e.g. step already completed, intent already cancelled, duplicate idempotency key with different body).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_putDocumentClaims_Knowledge", "resource_uri": "yf://agents/knowledge/documents/{id}/claims", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PUT -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" -d @ledger.json \"https://agents.yieldfabric.com/knowledge/documents/$DOC_ID/claims\"" } ], "x-related": [ { "operationId": "getDocumentClaims_Knowledge", "relation": "sibling" }, { "operationId": "getDocument_Knowledge", "relation": "sibling" }, { "operationId": "retrieveDocuments_Knowledge", "relation": "consumer" }, { "guide": "knowledge", "relation": "concept" } ] } }, "/knowledge/graphs/{kg_id}/groups": { "post": { "operationId": "attributeKgToGroup_Knowledge", "x-method": "POST", "x-path": "/knowledge/graphs/{kg_id}/groups", "x-handler": "handlers::knowledge_documents::attribute_kg_to_group", "tags": [ "Knowledge Documents" ], "summary": "Record that another room also holds this graph.", "description": "The case this exists for: two people independently upload the same file\nto two unrelated rooms. Content dedup is a SYSTEM optimisation —\nextract once, embed once, store once — and the frames land in whichever\nroom arrived first. That must not make the second room a guest. Without\nthis it sees the file in its ledger and its assistant cannot retrieve\nit.\n\n**Two gates, and neither is sufficient alone:**\n\n1. **Membership of the target room** — you may only add a document to a\n room you belong to (`ViewDocuments`).\n2. **Proof of possession** — the caller presents the document's\n `sha256`, verified against the graph.\n\nMembership alone would be a corpus-wide read primitive: a member of\ntheir own room could attach ANY graph id to it and read the contents.\nThe hash is what makes the claim real — a 64-hex digest is not\nguessable or enumerable, so knowing it means having had the bytes,\nwhich is exactly the claim being asserted.\n\n\"No such graph\" and \"wrong hash\" both answer `403`, deliberately:\ndistinguishing them would turn this into an oracle for which graphs\nhold which content.\n\n**Idempotent** — the same room re-uploading the same file is a no-op,\nand so is a retried delivery.\n", "parameters": [ { "name": "kg_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "working_group_id", "sha256" ], "properties": { "working_group_id": { "type": "string", "format": "uuid", "description": "The room claiming the graph. The caller must belong to it." }, "sha256": { "type": "string", "pattern": "^[0-9a-fA-F]{64}$", "description": "The document's content hash — proof of possession, not a lookup key. A 64-hex digest is not guessable or enumerable, so knowing it means having had the bytes." } } } } } }, "responses": { "200": { "description": "The room now holds this graph.", "content": { "application/json": { "schema": { "type": "object", "required": [ "attributed" ], "properties": { "attributed": { "type": "boolean" } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Not a member of the target room, or the sha256 does not match a document in this graph." }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_attributeKgToGroup_Knowledge", "resource_uri": "yf://agents/knowledge/graphs", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \"https://agents.yieldfabric.com/knowledge/graphs/$KG/groups\" \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"working_group_id\":\"'$WG'\",\"sha256\":\"e3b0c44298fc1c149afbf4c8996fb924...\"}'\n" } ], "x-related": [ { "operationId": "listDocuments_Knowledge", "relation": "sibling" }, { "guide": "knowledge", "relation": "concept" } ] } }, "/knowledge/sets": { "post": { "operationId": "createSet_Knowledge", "x-method": "POST", "x-path": "/knowledge/sets", "x-handler": "handlers::knowledge_sets::create_set", "tags": [ "Knowledge Documents" ], "summary": "Freeze a membership snapshot from a term predicate (async).", "description": "Starts a freeze: the exact set of documents matching these terms at\nthis moment, hash-pinned and immutable. This is what turns \"a search I\nran once\" into a claim someone can check later — \"these 412 documents,\nfrozen on this date, under this predicate\".\nAn omitted `as_of` uses the database clock shared by frame timestamps,\nso clock skew on an application host cannot omit just-committed documents.\n\n**Asynchronous.** Returns `202` with a `job_id` and parks the work; the\njob row is the receipt, so nothing is lost if the replica handling this\nrequest goes away. Poll `GET /knowledge/sets/jobs/{job_id}` until the\nstatus is terminal (`done` or `failed`). Freezing is one\n`INSERT..SELECT` — seconds, not minutes. Do not re-submit while\nwaiting: creation is **not** idempotent and a second call mints a\nsecond snapshot. That is wasteful rather than wrong (two freezes of the\nsame predicate at the same `as_of` produce equal membership, and equal\nhashes), but it leaves a set nobody asked for.\n\n1–16 terms, each at most 512 characters. All three lexical modes are\nfreezable. `created_by` is the authenticated entity and is never taken\nfrom the request.\n\n**Access.** Bearer JWT. Authorization is `authorize_retrieval_group` —\nthe same `ViewDocuments` capability check (plus the group-creator\nfallback) every knowledge-documents endpoint runs. Deliberately NOT the\ngroup ids on the token: those are a different set, the more permissive\nof the two, and two opinions about who is in a group is how they drift\ninto a leak.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "working_group_id", "terms" ], "properties": { "working_group_id": { "type": "string", "format": "uuid" }, "terms": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "type": "object", "required": [ "term" ], "properties": { "term": { "type": "string", "minLength": 1, "maxLength": 512 }, "mode": { "type": "string", "enum": [ "exact", "phrase", "fuzzy" ], "default": "exact", "description": "`exact` is `simple`-config full text with no stemming, so an identifier matches only itself. `phrase` is `english`-config websearch syntax. `fuzzy` is a deterministic trigram substring predicate — despite the name it is exact enough to freeze, and is the only honest way to pin a needle that lives inside a lexeme no tsquery can see into (a domain in an email address, say)." } } } }, "as_of": { "type": "string", "format": "date-time", "description": "The snapshot time, recorded when the job is inserted (default: now). The freeze executes against it regardless of when the worker actually runs, so a queued job cannot drift." } } }, "examples": { "disclosure_predicate": { "summary": "Freeze everything mentioning either party", "value": { "working_group_id": "11111111-1111-4111-8111-111111111111", "terms": [ { "term": "Silberstein", "mode": "exact" }, { "term": "costs estimate", "mode": "phrase" } ] } } } } } }, "responses": { "202": { "description": "Freeze accepted. Poll the job.", "content": { "application/json": { "schema": { "type": "object", "required": [ "job_id" ], "properties": { "job_id": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "422": { "description": "Empty term list, more than 16 terms, or a term over 512 characters." }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_createSet_Knowledge", "resource_uri": "yf://agents/knowledge/sets", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \"https://agents.yieldfabric.com/knowledge/sets\" \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"working_group_id\":\"'$WG'\",\"terms\":[{\"term\":\"Silberstein\"}]}'\n" } ], "x-related": [ { "operationId": "getFreezeJob_Knowledge", "relation": "next" }, { "operationId": "createSetFromDocuments_Knowledge", "relation": "alternative" }, { "operationId": "countDocumentsInSet_Knowledge", "relation": "next" }, { "guide": "knowledge", "relation": "concept" } ] }, "get": { "operationId": "listSets_Knowledge", "x-method": "GET", "x-path": "/knowledge/sets", "x-handler": "handlers::knowledge_sets::list_sets", "tags": [ "Knowledge Documents" ], "summary": "List the frozen sets one workspace can read.", "description": "Every set the named working group can read: the ones it owns, plus the\nones another workspace has granted to it (`granted: true`).\n\nThe REST twin of the `sets` MCP tool, over ONE named group rather than\nevery group the caller belongs to — which is the question a consumer\napp asks, because it renders one workspace at a time. Both go through\nthe same query, so the two surfaces cannot come to different answers.\n\nUnlike the MCP tool this DOES return the owning `working_group_id` on\ngranted rows. The caller has already proved membership of the grantee\ngroup, and a consumer app needs the owner to say \"shared from\n‹workspace›\" — the set's name lives in that app's own tables, not\nhere, so without the owner id a received set has nothing to render but\na hash.\n\n**Access.** Bearer JWT. Authorization is `authorize_retrieval_group` —\nthe same `ViewDocuments` capability check (plus the group-creator\nfallback) every knowledge-documents endpoint runs. Deliberately NOT the\ngroup ids on the token: those are a different set, the more permissive\nof the two, and two opinions about who is in a group is how they drift\ninto a leak.\n", "parameters": [ { "name": "working_group_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sets readable by this workspace, owned and granted.", "content": { "application/json": { "schema": { "type": "array", "items": { "allOf": [ { "type": "object", "required": [ "id", "working_group_id", "terms", "as_of", "document_count", "content_sha256", "created_by", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "working_group_id": { "type": "string", "format": "uuid", "description": "The owning workspace. A set belongs to exactly one." }, "terms": { "type": "array", "items": { "type": "object", "required": [ "term" ], "properties": { "term": { "type": "string", "minLength": 1, "maxLength": 512 }, "mode": { "type": "string", "enum": [ "exact", "phrase", "fuzzy" ], "default": "exact", "description": "`exact` is `simple`-config full text with no stemming, so an identifier matches only itself. `phrase` is `english`-config websearch syntax. `fuzzy` is a deterministic trigram substring predicate — despite the name it is exact enough to freeze, and is the only honest way to pin a needle that lives inside a lexeme no tsquery can see into (a domain in an email address, say)." } } }, "description": "The predicate", "as submitted.": null }, "as_of": { "type": "string", "format": "date-time", "description": "The moment membership was fixed." }, "document_count": { "type": "integer", "minimum": 0, "description": "The denominator every in-set figure is out of." }, "content_sha256": { "type": "string", "description": "SHA-256 over the terms AS SUBMITTED (order and modes), the snapshot time, and the sorted membership — deliberately not over server-normalized terms, so the hash carries no dependency on the normalization echo. Two sets with the same hash hold the same documents, which is what lets a counterparty verify you searched what you said you searched." }, "created_by": { "type": "string", "description": "The authenticated entity. Never client-supplied." }, "created_at": { "type": "string", "format": "date-time" } } }, { "type": "object", "required": [ "granted" ], "properties": { "granted": { "type": "boolean", "description": "True when this set is reachable through a grant rather than ownership. A set owned by one of the caller's groups AND granted to another appears once, reported as owned." } } } ] } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listSets_Knowledge", "resource_uri": "yf://agents/knowledge/sets", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET \"https://agents.yieldfabric.com/knowledge/sets?working_group_id=$WG\" \\\n -H \"Authorization: Bearer $JWT\"\n" } ], "x-related": [ { "operationId": "getSet_Knowledge", "relation": "detail" }, { "operationId": "listGrants_Knowledge", "relation": "sibling" }, { "guide": "knowledge", "relation": "concept" } ] } }, "/knowledge/sets/from-documents": { "post": { "operationId": "createSetFromDocuments_Knowledge", "x-method": "POST", "x-path": "/knowledge/sets/from-documents", "x-handler": "handlers::knowledge_sets::create_set_from_documents", "tags": [ "Knowledge Documents" ], "summary": "Freeze an explicit list of document ids (synchronous).", "description": "Freezes membership you already hold, rather than membership a\npredicate finds. Returns the set itself.\n\n**Synchronous**, because there is nothing to wait for: no search, one\ntransaction. Index warming is spawned rather than awaited — the set is\ncomplete and correct at commit, and priming the planner for its first\nread is an optimisation nobody should be held on.\n\nA separate route from `POST /knowledge/sets` rather than another shape\non it: the two share nothing at the edges — one runs a search and\nreturns a job to poll, the other has its membership already and answers\nwith the set. Folding them together would produce a request where half\nthe fields are meaningless depending on the other half. They share what\nactually matters, so a set is still born in exactly one place.\n\n**Access.** Bearer JWT. Authorization is `authorize_retrieval_group` —\nthe same `ViewDocuments` capability check (plus the group-creator\nfallback) every knowledge-documents endpoint runs. Deliberately NOT the\ngroup ids on the token: those are a different set, the more permissive\nof the two, and two opinions about who is in a group is how they drift\ninto a leak.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "working_group_id", "document_ids" ], "properties": { "working_group_id": { "type": "string", "format": "uuid" }, "document_ids": { "type": "array", "items": { "type": "string" } }, "as_of": { "type": "string", "format": "date-time", "description": "When this list was fixed. Defaults to now." } } } } } }, "responses": { "200": { "description": "The frozen set.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "working_group_id", "terms", "as_of", "document_count", "content_sha256", "created_by", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "working_group_id": { "type": "string", "format": "uuid", "description": "The owning workspace. A set belongs to exactly one." }, "terms": { "type": "array", "items": { "type": "object", "required": [ "term" ], "properties": { "term": { "type": "string", "minLength": 1, "maxLength": 512 }, "mode": { "type": "string", "enum": [ "exact", "phrase", "fuzzy" ], "default": "exact", "description": "`exact` is `simple`-config full text with no stemming, so an identifier matches only itself. `phrase` is `english`-config websearch syntax. `fuzzy` is a deterministic trigram substring predicate — despite the name it is exact enough to freeze, and is the only honest way to pin a needle that lives inside a lexeme no tsquery can see into (a domain in an email address, say)." } } }, "description": "The predicate", "as submitted.": null }, "as_of": { "type": "string", "format": "date-time", "description": "The moment membership was fixed." }, "document_count": { "type": "integer", "minimum": 0, "description": "The denominator every in-set figure is out of." }, "content_sha256": { "type": "string", "description": "SHA-256 over the terms AS SUBMITTED (order and modes), the snapshot time, and the sorted membership — deliberately not over server-normalized terms, so the hash carries no dependency on the normalization echo. Two sets with the same hash hold the same documents, which is what lets a counterparty verify you searched what you said you searched." }, "created_by": { "type": "string", "description": "The authenticated entity. Never client-supplied." }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "422": { "description": "The document list was rejected (empty, or ids outside the workspace)." }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_createSetFromDocuments_Knowledge", "resource_uri": "yf://agents/knowledge/sets", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \"https://agents.yieldfabric.com/knowledge/sets/from-documents\" \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"working_group_id\":\"'$WG'\",\"document_ids\":[\"doc-a\",\"doc-b\"]}'\n" } ], "x-related": [ { "operationId": "createSet_Knowledge", "relation": "alternative" }, { "operationId": "getSet_Knowledge", "relation": "detail" }, { "guide": "knowledge", "relation": "concept" } ] } }, "/knowledge/sets/jobs/{job_id}": { "get": { "operationId": "getFreezeJob_Knowledge", "x-method": "GET", "x-path": "/knowledge/sets/jobs/{job_id}", "x-handler": "handlers::knowledge_sets::get_freeze_job", "tags": [ "Knowledge Documents" ], "summary": "Poll a freeze job.", "description": "Returns the job's `status` and, once `done`, the `set_id` to use with\nthe in-set count and the member listing.\n\n**Terminal statuses are `done` and `failed`** — there is no\n`completed`. A poller testing for the wrong string never stops. A job\nleft `running` by a service restart is failed lazily after 15 minutes,\non the next read or create, so a poll always converges.\n\nThe job is stateless to poll: state lives in Postgres, so any replica\nanswers, and a dropped connection loses nothing.\n\nAuthorized against the JOB's own working group — a job id names no\ntenant by itself.\n\n**Access.** Bearer JWT. Authorization is `authorize_retrieval_group` —\nthe same `ViewDocuments` capability check (plus the group-creator\nfallback) every knowledge-documents endpoint runs. Deliberately NOT the\ngroup ids on the token: those are a different set, the more permissive\nof the two, and two opinions about who is in a group is how they drift\ninto a leak.\n", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The freeze job.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "working_group_id", "terms", "as_of", "status", "progress", "created_by", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "working_group_id": { "type": "string", "format": "uuid" }, "terms": { "type": "array", "items": { "type": "object", "required": [ "term" ], "properties": { "term": { "type": "string", "minLength": 1, "maxLength": 512 }, "mode": { "type": "string", "enum": [ "exact", "phrase", "fuzzy" ], "default": "exact", "description": "`exact` is `simple`-config full text with no stemming, so an identifier matches only itself. `phrase` is `english`-config websearch syntax. `fuzzy` is a deterministic trigram substring predicate — despite the name it is exact enough to freeze, and is the only honest way to pin a needle that lives inside a lexeme no tsquery can see into (a domain in an email address, say)." } } } }, "as_of": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "running", "done", "failed" ], "description": "`done` and `failed` are the terminal states — poll until one of them. A job left `running` by a service restart is failed lazily after 15 minutes on the next read or create." }, "progress": { "type": "array", "items": { "type": "object" }, "description": "One entry per term plus bookends; capped at 64." }, "set_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Present once status is `done`." }, "error": { "type": [ "string", "null" ] }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getFreezeJob_Knowledge", "resource_uri": "yf://agents/knowledge/sets/jobs", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET \"https://agents.yieldfabric.com/knowledge/sets/jobs/$JOB_ID\" \\\n -H \"Authorization: Bearer $JWT\"\n" } ], "x-related": [ { "operationId": "createSet_Knowledge", "relation": "parent" }, { "operationId": "getSet_Knowledge", "relation": "next" }, { "guide": "knowledge", "relation": "concept" } ] } }, "/knowledge/sets/{set_id}": { "get": { "operationId": "getSet_Knowledge", "x-method": "GET", "x-path": "/knowledge/sets/{set_id}", "x-handler": "handlers::knowledge_sets::get_set", "tags": [ "Knowledge Documents" ], "summary": "Read one frozen set.", "description": "Its terms, the moment it was frozen, how many documents it holds, and\nits content hash. Confirm what a set actually covers before relying on\na count taken against it — `document_count` is the denominator every\nin-set figure is out of.\n\nReadable by the owning workspace **or** by any workspace holding a live\ngrant. A set id names no tenant by itself, so authorization comes from\nthe row, not from a group the caller names.\n\n**Access.** Bearer JWT. Authorization is `authorize_retrieval_group` —\nthe same `ViewDocuments` capability check (plus the group-creator\nfallback) every knowledge-documents endpoint runs. Deliberately NOT the\ngroup ids on the token: those are a different set, the more permissive\nof the two, and two opinions about who is in a group is how they drift\ninto a leak.\n", "parameters": [ { "name": "set_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The frozen set.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "working_group_id", "terms", "as_of", "document_count", "content_sha256", "created_by", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "working_group_id": { "type": "string", "format": "uuid", "description": "The owning workspace. A set belongs to exactly one." }, "terms": { "type": "array", "items": { "type": "object", "required": [ "term" ], "properties": { "term": { "type": "string", "minLength": 1, "maxLength": 512 }, "mode": { "type": "string", "enum": [ "exact", "phrase", "fuzzy" ], "default": "exact", "description": "`exact` is `simple`-config full text with no stemming, so an identifier matches only itself. `phrase` is `english`-config websearch syntax. `fuzzy` is a deterministic trigram substring predicate — despite the name it is exact enough to freeze, and is the only honest way to pin a needle that lives inside a lexeme no tsquery can see into (a domain in an email address, say)." } } }, "description": "The predicate", "as submitted.": null }, "as_of": { "type": "string", "format": "date-time", "description": "The moment membership was fixed." }, "document_count": { "type": "integer", "minimum": 0, "description": "The denominator every in-set figure is out of." }, "content_sha256": { "type": "string", "description": "SHA-256 over the terms AS SUBMITTED (order and modes), the snapshot time, and the sorted membership — deliberately not over server-normalized terms, so the hash carries no dependency on the normalization echo. Two sets with the same hash hold the same documents, which is what lets a counterparty verify you searched what you said you searched." }, "created_by": { "type": "string", "description": "The authenticated entity. Never client-supplied." }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getSet_Knowledge", "resource_uri": "yf://agents/knowledge/sets", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET \"https://agents.yieldfabric.com/knowledge/sets/$SET_ID\" \\\n -H \"Authorization: Bearer $JWT\"\n" } ], "x-related": [ { "operationId": "setMembers_Knowledge", "relation": "detail" }, { "operationId": "countDocumentsInSet_Knowledge", "relation": "next" }, { "operationId": "listSets_Knowledge", "relation": "list" }, { "guide": "knowledge", "relation": "concept" } ] }, "delete": { "operationId": "deleteSet_Knowledge", "x-method": "DELETE", "x-path": "/knowledge/sets/{set_id}", "x-handler": "handlers::knowledge_sets::delete_set", "tags": [ "Knowledge Documents" ], "summary": "Delete a frozen set, cascading its members and samples.", "description": "Removes the set, its membership, and every sample drawn from it.\n\n**Owner only.** A grantee may read a set's frozen membership and\nnothing else. A grantee reads a set, never destroys one — and deletion\ncascades the membership every grantee is reading.\n\n**Referential guards are the consumer's to enforce before calling.**\nNothing here checks whether a citing run, a scoped conversation, or a\npublished finding still depends on this set; `deleted: false` simply\nmeans there was no such set.\n\n**Access.** Bearer JWT. Authorization is `authorize_retrieval_group` —\nthe same `ViewDocuments` capability check (plus the group-creator\nfallback) every knowledge-documents endpoint runs. Deliberately NOT the\ngroup ids on the token: those are a different set, the more permissive\nof the two, and two opinions about who is in a group is how they drift\ninto a leak.\n", "parameters": [ { "name": "set_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Whether a set was removed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_deleteSet_Knowledge", "resource_uri": "yf://agents/knowledge/sets", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X DELETE \"https://agents.yieldfabric.com/knowledge/sets/$SET_ID\" \\\n -H \"Authorization: Bearer $JWT\"\n" } ], "x-related": [ { "operationId": "getSet_Knowledge", "relation": "detail" }, { "operationId": "revokeGrant_Knowledge", "relation": "alternative" }, { "guide": "knowledge", "relation": "concept" } ] } }, "/knowledge/sets/{set_id}/grants": { "get": { "operationId": "listGrants_Knowledge", "x-method": "GET", "x-path": "/knowledge/sets/{set_id}/grants", "x-handler": "handlers::knowledge_sets::list_grants", "tags": [ "Knowledge Documents" ], "summary": "List the workspaces currently holding this set.", "description": "The live grants on a set — revoked ones are excluded.\n\n**Owner only:** the list of parties a set was disclosed to is itself\ndisclosure, and a grantee has no business reading who else holds it.\n\n**Access.** Bearer JWT. Authorization is `authorize_retrieval_group` —\nthe same `ViewDocuments` capability check (plus the group-creator\nfallback) every knowledge-documents endpoint runs. Deliberately NOT the\ngroup ids on the token: those are a different set, the more permissive\nof the two, and two opinions about who is in a group is how they drift\ninto a leak.\n", "parameters": [ { "name": "set_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Workspaces holding a live grant.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "to_working_group_id" ], "properties": { "to_working_group_id": { "type": "string", "format": "uuid" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listGrants_Knowledge", "resource_uri": "yf://agents/knowledge/sets", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET \"https://agents.yieldfabric.com/knowledge/sets/$SET_ID/grants\" \\\n -H \"Authorization: Bearer $JWT\"\n" } ], "x-related": [ { "operationId": "createGrant_Knowledge", "relation": "parent" }, { "operationId": "revokeGrant_Knowledge", "relation": "alternative" }, { "guide": "knowledge", "relation": "concept" } ] }, "post": { "operationId": "createGrant_Knowledge", "x-method": "POST", "x-path": "/knowledge/sets/{set_id}/grants", "x-handler": "handlers::knowledge_sets::create_grant", "tags": [ "Knowledge Documents" ], "summary": "Let another workspace read this set.", "description": "A grant is the ONLY way a caller reads documents belonging to a\nworkspace they are not in. What makes that safe is that membership is\nFROZEN — an explicit, immutable list fixed at freeze time — so a grant\ndiscloses exactly what the owner enumerated and can never grow into\nmore. *If sets ever become mutable, this reasoning fails and the grant\nmodel needs rethinking, not patching.*\n\nA grantee may read the set, its members, and run in-set counts and\nset-scoped retrieval. They may not sample it, delete it, list its other\ngrantees, or pass it on: grants are **not transitive**, so every grant\non a set comes from one party, which is what makes \"who can see this\"\nanswerable from a single table.\n\n**Idempotent.** Re-granting to the same workspace refreshes the row,\nand reinstates a grant that had been revoked. Granting to the owning\nworkspace is a `400` — it would leave a row implying a cross-tenant\nshare that never happened.\n\n**Owner only.**\n\n**Access.** Bearer JWT. Authorization is `authorize_retrieval_group` —\nthe same `ViewDocuments` capability check (plus the group-creator\nfallback) every knowledge-documents endpoint runs. Deliberately NOT the\ngroup ids on the token: those are a different set, the more permissive\nof the two, and two opinions about who is in a group is how they drift\ninto a leak.\n", "parameters": [ { "name": "set_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "to_working_group_id" ], "properties": { "to_working_group_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "The grant is live.", "content": { "application/json": { "schema": { "type": "object", "required": [ "granted" ], "properties": { "granted": { "type": "boolean" } } } } } }, "400": { "description": "The set already belongs to that working group." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_createGrant_Knowledge", "resource_uri": "yf://agents/knowledge/sets", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \"https://agents.yieldfabric.com/knowledge/sets/$SET_ID/grants\" \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"to_working_group_id\":\"'$OTHER_WG'\"}'\n" } ], "x-related": [ { "operationId": "revokeGrant_Knowledge", "relation": "alternative" }, { "operationId": "listGrants_Knowledge", "relation": "list" }, { "guide": "knowledge", "relation": "concept" } ] } }, "/knowledge/sets/{set_id}/grants/{group_id}": { "delete": { "operationId": "revokeGrant_Knowledge", "x-method": "DELETE", "x-path": "/knowledge/sets/{set_id}/grants/{group_id}", "x-handler": "handlers::knowledge_sets::revoke_grant", "tags": [ "Knowledge Documents" ], "summary": "Withdraw a workspace's access to this set.", "description": "Stamps the grant revoked. The row is KEPT rather than deleted, because\n\"who held this, and until when\" is the question this corpus gets asked\nafterwards.\n\n**`revoked: false` means there was no live grant to withdraw.** That is\nreported rather than smoothed into success, because \"I stopped it\" and\n\"it was already stopped\" are different answers to give someone asking\nwhether a party still has access.\n\nWithdrawal stops FUTURE reads. It cannot un-read what was already read,\nand no caller should be told otherwise.\n\n**Owner only.**\n\n**Access.** Bearer JWT. Authorization is `authorize_retrieval_group` —\nthe same `ViewDocuments` capability check (plus the group-creator\nfallback) every knowledge-documents endpoint runs. Deliberately NOT the\ngroup ids on the token: those are a different set, the more permissive\nof the two, and two opinions about who is in a group is how they drift\ninto a leak.\n", "parameters": [ { "name": "set_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The grantee workspace." } ], "responses": { "200": { "description": "Whether a live grant was withdrawn.", "content": { "application/json": { "schema": { "type": "object", "required": [ "revoked" ], "properties": { "revoked": { "type": "boolean" } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_revokeGrant_Knowledge", "resource_uri": "yf://agents/knowledge/sets", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X DELETE \"https://agents.yieldfabric.com/knowledge/sets/$SET_ID/grants/$OTHER_WG\" \\\n -H \"Authorization: Bearer $JWT\"\n" } ], "x-related": [ { "operationId": "createGrant_Knowledge", "relation": "alternative" }, { "operationId": "listGrants_Knowledge", "relation": "list" }, { "guide": "knowledge", "relation": "concept" } ] } }, "/knowledge/sets/{set_id}/members": { "get": { "operationId": "setMembers_Knowledge", "x-method": "GET", "x-path": "/knowledge/sets/{set_id}/members", "x-handler": "handlers::knowledge_sets::set_members", "tags": [ "Knowledge Documents" ], "summary": "Page through a set's frozen membership.", "description": "Keyset-paginated document ids, in stable order. Page until `next_after`\nis null; that is what makes a review list auditable rather than merely\nlong.\n\nIds only by default — display names are the consumer's to resolve, and\na consumer that can name its own documents should not pay for names it\nalready has. Pass `titles=true` to have them joined server-side; a null\nentry then means the platform has no title for that document either,\nwhich is rare and reported honestly rather than blanked.\n\nReadable by the owning workspace or by a live grantee: the frozen\nmembership is exactly what a grant discloses.\n\n**Access.** Bearer JWT. Authorization is `authorize_retrieval_group` —\nthe same `ViewDocuments` capability check (plus the group-creator\nfallback) every knowledge-documents endpoint runs. Deliberately NOT the\ngroup ids on the token: those are a different set, the more permissive\nof the two, and two opinions about who is in a group is how they drift\ninto a leak.\n", "parameters": [ { "name": "set_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Keyset cursor — the previous page's `next_after`." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 500 } }, { "name": "titles", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "One page of member document ids.", "content": { "application/json": { "schema": { "type": "object", "required": [ "document_ids" ], "properties": { "document_ids": { "type": "array", "items": { "type": "string" } }, "titles": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Parallel to `document_ids`, same order, present only when `titles=true` was asked for. A null entry means the platform has no title for that document either." }, "next_after": { "type": [ "string", "null" ], "description": "Keyset cursor; pass as `after`. Null on the last page." } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_setMembers_Knowledge", "resource_uri": "yf://agents/knowledge/sets", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET \"https://agents.yieldfabric.com/knowledge/sets/$SET_ID/members?limit=500&titles=true\" \\\n -H \"Authorization: Bearer $JWT\"\n" } ], "x-related": [ { "operationId": "getSet_Knowledge", "relation": "parent" }, { "operationId": "matchDocumentsLexical_Knowledge", "relation": "sibling" }, { "guide": "knowledge", "relation": "concept" } ] } }, "/knowledge/sets/{set_id}/samples": { "get": { "operationId": "listSamples_Knowledge", "x-method": "GET", "x-path": "/knowledge/sets/{set_id}/samples", "x-handler": "handlers::knowledge_sets::list_samples", "tags": [ "Knowledge Documents" ], "summary": "List prior draws from a set, with their members.", "description": "Every sample previously drawn from this set, each with its members —\nthe audit trail behind an elusion estimate.\n\n**Owner only**, for the same reason drawing is: prior draws include\n`complement` samples, whose members are documents the set deliberately\nexcludes.\n\n**Access.** Bearer JWT. Authorization is `authorize_retrieval_group` —\nthe same `ViewDocuments` capability check (plus the group-creator\nfallback) every knowledge-documents endpoint runs. Deliberately NOT the\ngroup ids on the token: those are a different set, the more permissive\nof the two, and two opinions about who is in a group is how they drift\ninto a leak.\n", "parameters": [ { "name": "set_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Prior draws, newest-first by creation.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "id", "set_id", "kind", "seed", "requested", "universe_size", "created_by", "created_at", "document_ids" ], "properties": { "id": { "type": "string", "format": "uuid" }, "set_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "member", "complement" ] }, "seed": { "type": "string", "description": "Replaying the same (kind", "seed": null, "size) returns the same draw.": null }, "requested": { "type": "integer" }, "universe_size": { "type": "integer", "description": "How many documents the draw was taken from." }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "document_ids": { "type": "array", "items": { "type": "string" } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listSamples_Knowledge", "resource_uri": "yf://agents/knowledge/sets", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET \"https://agents.yieldfabric.com/knowledge/sets/$SET_ID/samples\" \\\n -H \"Authorization: Bearer $JWT\"\n" } ], "x-related": [ { "operationId": "drawSample_Knowledge", "relation": "parent" }, { "guide": "knowledge", "relation": "concept" } ] }, "post": { "operationId": "drawSample_Knowledge", "x-method": "POST", "x-path": "/knowledge/sets/{set_id}/samples", "x-handler": "handlers::knowledge_sets::draw_sample", "tags": [ "Knowledge Documents" ], "summary": "Draw or replay a seeded sample from a set or its complement.", "description": "`member` draws from inside the frozen membership; `complement` draws\nfrom the owner's documents that the set EXCLUDES — the draw that lets\nyou bound elusion, i.e. estimate what a predicate missed.\n\n**Idempotent by `(kind, seed, size)`.** Re-posting the same triple\nreplays the identical draw rather than taking a new one, so a sample\ncited in a report stays reproducible and re-running a review does not\nquietly change its evidence.\n\n**Owner only** — and this is the case that bites. A `complement` sample\nis drawn from precisely the material the set was narrowed to exclude,\nso handing sampling to a grantee would disclose what they were not\ngiven. `size` is 1–500; `seed` is 1–128 characters.\n\n**Access.** Bearer JWT. Authorization is `authorize_retrieval_group` —\nthe same `ViewDocuments` capability check (plus the group-creator\nfallback) every knowledge-documents endpoint runs. Deliberately NOT the\ngroup ids on the token: those are a different set, the more permissive\nof the two, and two opinions about who is in a group is how they drift\ninto a leak.\n", "parameters": [ { "name": "set_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "kind", "seed", "size" ], "properties": { "kind": { "type": "string", "enum": [ "member", "complement" ], "description": "`member` draws from inside the set; `complement` draws from the owner's documents OUTSIDE it — which is why sampling is owner-only." }, "seed": { "type": "string", "minLength": 1, "maxLength": 128 }, "size": { "type": "integer", "minimum": 1, "maximum": 500 } } } } } }, "responses": { "200": { "description": "The draw, with its members and the universe it came from.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "set_id", "kind", "seed", "requested", "universe_size", "created_by", "created_at", "document_ids" ], "properties": { "id": { "type": "string", "format": "uuid" }, "set_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "member", "complement" ] }, "seed": { "type": "string", "description": "Replaying the same (kind", "seed": null, "size) returns the same draw.": null }, "requested": { "type": "integer" }, "universe_size": { "type": "integer", "description": "How many documents the draw was taken from." }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "document_ids": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Empty or over-long seed, or a size outside 1–500." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_drawSample_Knowledge", "resource_uri": "yf://agents/knowledge/sets", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \"https://agents.yieldfabric.com/knowledge/sets/$SET_ID/samples\" \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"kind\":\"complement\",\"seed\":\"review-2026-08\",\"size\":50}'\n" } ], "x-related": [ { "operationId": "listSamples_Knowledge", "relation": "list" }, { "operationId": "setMembers_Knowledge", "relation": "sibling" }, { "guide": "knowledge", "relation": "concept" } ] } }, "/macro-chat": { "post": { "operationId": "macroChatPublicHandler_Misc", "x-method": "POST", "x-path": "/macro-chat", "x-handler": "handlers::assistant_chat::macro_assistant::macro_chat_public_handler", "tags": [ "Chat" ], "security": [], "summary": "Stream an anonymous macro-research answer", "description": "Public, unauthenticated and read-only macro assistant for the research site.\nThe handler executes only the bounded public research toolset: it does not\naccess working groups, persist chat, or collect PII. Requests are rate-limited\nby a trusted proxy-derived client key (or a process-global fallback); a\nnon-empty `X-Monitor-Id` receives a separate but still bounded tier.\n\nThe response is an unnamed SSE stream. Concatenate each JSON payload's\n`chunk` until `is_final` is true. The final normal-answer event also carries\nthe server-inferred `inferred_lane`. Empty or oversized messages receive a\none-event guidance stream. The route body limit is 16 KiB.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "message" ], "description": "Mirrors `ChatRequest` in src/service/types.rs.\n", "properties": { "message": { "type": "string", "minLength": 1, "description": "Nonblank input; at most 64000 UTF-8 bytes." }, "context": { "type": "string", "default": "chat", "description": "Caller surface label. `fabric` with no `thread_id` marks an ephemeral chat — no thread is created or persisted and the reply's `thread_id` is null; every other value keeps the stored thread." }, "thread_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Existing authorized thread. Omit to create a private conversation in the requested group or the caller's personal workspace (or, with `context: fabric`, to run an ephemeral chat with no thread at all)." }, "uiContext": { "description": "Arbitrary JSON value." }, "viewContext": { "oneOf": [ { "type": "object", "description": "Validated dashboard context accepted by the public macro assistant. The\nhandler allow-lists tab ids and validates compare-series values before\nusing them as prompt hints.\n", "properties": { "tab": { "type": [ "string", "null" ] }, "compareSeries": { "type": "array", "items": { "type": "string" }, "default": [] }, "compareMode": { "type": [ "string", "null" ], "description": "Recognized client modes are `pct`, `index`, and `levels`." }, "compareRange": { "type": [ "string", "null" ] }, "compareSpread": { "type": "boolean", "default": false }, "compareShift": { "type": [ "integer", "null" ], "format": "int64" } } }, { "type": "null" } ] }, "workingGroupId": { "type": [ "string", "null" ] }, "kgId": { "type": [ "string", "null" ] }, "systemPrompt": { "type": [ "string", "null" ] }, "conversationHistory": { "description": "Accepted for compatibility but ignored; persisted thread messages are the only prior conversation context.", "deprecated": true, "oneOf": [ { "type": "array", "items": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string" }, "content": { "type": "string" } } } }, { "type": "null" } ] }, "reasoning": { "type": [ "boolean", "null" ], "description": "False omits automatic retrieval tools for the default assistant. A selected agent retains its configured tools and effort; no intent-classifier call is performed." }, "skipRag": { "type": "boolean", "default": false }, "asAgent": { "type": [ "string", "null" ], "description": "Invoke a caller-visible registered agent with its composed prompt, configured model, effort, output limit, grants and caller-private memory. Unknown agents return 404." }, "model": { "type": [ "string", "null" ], "description": "Which configured chat model serves this request: a registry id (`default`, `mini`) or a deployment name, case-insensitively. Unknown values are a 400 listing the servable models (see `GET /api/models`). Omit for the deployment default. An explicit model selector on the selected agent takes precedence." }, "maxOutputTokens": { "type": [ "integer", "null" ], "minimum": 1, "description": "Per-request output-token cap (server-clamped to 32000). Omit to use api.yieldfabric.com for the default assistant. Selected agents also enforce their own cap." }, "temperature": { "type": [ "number", "null" ], "description": "Sampling temperature, forwarded verbatim when present. Models that reject explicit temperatures (reasoning family) surface the upstream error. Omit for the upstream default." } } } ], "description": "Public macro-assistant input. `message` is required and bounded to 2,000\nbytes by the handler; `thread_id` is optional and generated when absent.\nThe public path consumes `viewContext` as a validated dashboard hint and\nignores the authenticated workspace fields accepted by the shared\n`ChatRequest` deserializer.\n" }, "examples": { "dashboard-question": { "value": { "message": "What is leading credit spreads right now?", "thread_id": "0b222bc1-4e8f-4fe5-9d66-453635d224b0", "viewContext": { "tab": "macro" } } } } } } }, "responses": { "200": { "description": "Unnamed SSE events carrying JSON chat chunks.", "content": { "text/event-stream": { "schema": { "type": "object", "description": "JSON payload in each unnamed `text/event-stream` event. Concatenate\n`chunk` values until `is_final` is true. `inferred_lane` is present only\non the final normal-answer chunk; canned validation and unavailable-feed\nresponses omit it.\n", "required": [ "chunk", "thread_id", "is_final", "complexity", "processing_mode", "sender" ], "properties": { "chunk": { "type": "string" }, "thread_id": { "type": "string" }, "is_final": { "type": "boolean" }, "complexity": { "type": "string", "const": "simple" }, "processing_mode": { "type": "string", "const": "macro_public" }, "sender": { "type": "object", "required": [ "entity_id", "display_name", "type" ], "properties": { "entity_id": { "type": "string", "const": "agent:macro" }, "display_name": { "type": "string", "const": "Markets Analyst" }, "type": { "type": "string", "const": "agent" } } }, "inferred_lane": { "type": "string", "enum": [ "dealer", "borrower", "builder", "unknown" ] } } } } } }, "400": { "description": "Malformed JSON request.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "413": { "description": "Request exceeds the 16 KiB route body limit.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "429": { "description": "Client rate limit exceeded.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "Market-research support is not enabled in this deployment.", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_macroChatPublicHandler_Misc", "resource_uri": "yf://agents/misc", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -N -X POST https://agents.yieldfabric.com/macro-chat \\\n -H \"Content-Type: application/json\" \\\n -d '{\"message\":\"What is leading credit spreads right now?\",\"viewContext\":{\"tab\":\"macro\"}}'\n" } ], "x-related": [ { "operationId": "macroLeadCaptureHandler_Misc", "relation": "related" } ] } }, "/macro-lead": { "post": { "operationId": "macroLeadCaptureHandler_Misc", "x-method": "POST", "x-path": "/macro-lead", "x-handler": "handlers::assistant_chat::macro_lead::macro_lead_capture_handler", "tags": [ "Conversation" ], "summary": "Capture a consented lead from the public macro chat", "description": "Public, anonymous lead capture for the macro-research chat. `consent: true`\nis a hard server-side requirement. When `viewContext` is present, the\nserver re-infers the lead lane instead of trusting `inferredLane`.\n\nThe route has a 32 KiB transport body limit and a process-local per-client\nrate limit. Thread summaries are truncated to 1,000 characters and\ntranscripts to 20,000 characters before persistence. Persistence and the\noptional Slack notification are best-effort: after valid consent/input, a\ntransient database or webhook failure still returns a fresh opaque\n`monitor_id` so the visitor flow is not interrupted.\n", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "consent" ], "description": "Explicitly consented public lead capture. The handler rejects\n`consent: false`, validates the email, and re-infers the lane from\n`viewContext` when it is present.\n", "properties": { "email": { "type": "string", "minLength": 5, "maxLength": 320, "description": "The handler applies a deliberately minimal `@` / whitespace shape check." }, "consent": { "type": "boolean", "const": true }, "threadId": { "type": [ "string", "null" ] }, "inferredLane": { "type": [ "string", "null" ], "description": "Recognized values are `dealer`, `borrower`, and `builder`; others normalize to `unknown`." }, "viewContext": { "oneOf": [ { "type": "object", "description": "Validated dashboard context accepted by the public macro assistant. The\nhandler allow-lists tab ids and validates compare-series values before\nusing them as prompt hints.\n", "properties": { "tab": { "type": [ "string", "null" ] }, "compareSeries": { "type": "array", "items": { "type": "string" }, "default": [] }, "compareMode": { "type": [ "string", "null" ], "description": "Recognized client modes are `pct`, `index`, and `levels`." }, "compareRange": { "type": [ "string", "null" ] }, "compareSpread": { "type": "boolean", "default": false }, "compareShift": { "type": [ "integer", "null" ], "format": "int64" } } }, { "type": "null" } ] }, "threadSummary": { "type": [ "string", "null" ], "description": "The handler retains at most the first 1,000 characters." }, "transcript": { "type": [ "string", "null" ], "description": "The handler retains at most the first 20,000 characters." }, "turnIndex": { "type": [ "integer", "null" ], "format": "int32" } } }, "examples": { "consented": { "value": { "email": "analyst@example.com", "consent": true, "inferredLane": "dealer", "threadSummary": "Interested in private-credit stress signals." } } } } } }, "responses": { "200": { "description": "Input accepted and a non-PII monitor tier token issued.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "monitor_id" ], "properties": { "ok": { "type": "boolean", "const": true }, "monitor_id": { "type": "string", "format": "uuid", "description": "Opaque non-PII token for the post-capture chat rate-limit tier." } } } } } }, "400": { "description": "Consent is false/missing, the email fails the minimal shape check, or JSON is malformed.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "413": { "description": "Request exceeds the route's 32 KiB transport limit.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "422": { "description": "JSON is valid but cannot be deserialized as the request shape (for example, `email` is absent or not a string).", "content": { "text/plain": { "schema": { "type": "string" } } } }, "429": { "description": "The anonymous per-client rate limit was exceeded.", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_macroLeadCaptureHandler_Misc", "resource_uri": "yf://agents/macro-leads", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Content-Type: application/json\" \\\n -d '{\"email\":\"analyst@example.com\",\"consent\":true,\"inferredLane\":\"dealer\"}' \\\n https://agents.yieldfabric.com/macro-lead\n" } ], "x-related": [ { "operationId": "macroChatPublicHandler_Misc", "relation": "source-flow" }, { "operationId": "macroLeadsExportHandler_Misc", "relation": "staff-export" } ] } }, "/macro-leads/export": { "get": { "operationId": "macroLeadsExportHandler_Misc", "x-method": "GET", "x-path": "/macro-leads/export", "x-handler": "handlers::assistant_chat::macro_lead::macro_leads_export_handler", "tags": [ "Chat" ], "summary": "Export the latest consented macro-chat leads", "description": "Staff-only export of up to 1,000 lead dossiers, newest first. The handler\nenforces both credential presence and a staff role itself because anonymous\nrequests are allowed through the surrounding request-auth middleware.\nRows can contain email addresses, transcripts and the internal client key;\ndo not expose this response to browser users without the staff gate.\n", "responses": { "200": { "description": "Newest captured lead dossiers, up to 1,000 rows.", "content": { "application/json": { "schema": { "type": "array", "maxItems": 1000, "items": { "type": "object", "required": [ "id", "email", "inferred_lane", "consent", "created_at" ], "description": "Staff-only captured-lead dossier row.", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "inferred_lane": { "type": "string", "enum": [ "dealer", "borrower", "builder", "unknown" ] }, "view_context": { "type": [ "string", "null" ], "description": "Serialized JSON text containing the capture-time view context." }, "thread_id": { "type": [ "string", "null" ], "format": "uuid" }, "thread_summary": { "type": [ "string", "null" ] }, "transcript": { "type": [ "string", "null" ] }, "turn_index": { "type": [ "integer", "null" ], "format": "int32" }, "consent": { "type": "boolean" }, "client_key": { "type": [ "string", "null" ], "description": "Internal rate-limit key; exposed only by the staff-gated export." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } } }, "401": { "description": "No valid caller credential was supplied." }, "403": { "description": "The authenticated caller is not staff." }, "500": { "description": "Export query failed.", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_macroLeadsExportHandler_Misc", "resource_uri": "yf://agents/misc", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/macro-leads/export" } ], "x-related": [ { "operationId": "macroLeadCaptureHandler_Misc", "relation": "related" } ] } }, "/mcp": { "post": { "operationId": "handleMcpHttp_Misc", "x-method": "POST", "x-path": "/mcp", "x-handler": "yieldfabric_mcp_transport::http::handle_post::", "tags": [ "MCP" ], "summary": "Spec-compliant MCP endpoint (JSON-RPC 2.0, stateless Streamable HTTP)", "description": "The Model Context Protocol endpoint real MCP clients connect to —\nClaude Code (`claude mcp add --transport http`), Claude Desktop, and\nclaude.ai custom connectors. Speaks JSON-RPC 2.0 in **stateless**\nStreamable-HTTP mode: plain JSON responses, no `Mcp-Session-Id`,\nnotifications (requests without an `id`) return `202 Accepted` with no\nbody, batch arrays are rejected with `-32600`, and `GET /mcp` returns\n405 (no server-initiated stream).\n\nMethods served: `initialize` (protocolVersion negotiation across\n2024-11-05 / 2025-03-26 / 2025-06-18 / 2025-11-25), `ping`,\n`tools/list`, `tools/call`, and `notifications/*`. The tool catalog is\nthe intent-shaped set of **nineteen** — eighteen reads over the\nalready-post-processed knowledge graph and the deal-room state, plus\n`freeze_set`, the one entry declaring `readOnlyHint: false` (it\ninserts a freeze job; `idempotentHint: false, destructiveHint: false`).\n`tools/list` is the authoritative enumeration; the catalog is pinned\nby `catalog_is_the_agreed_read_only_set`. Corpus reading: `graphs`,\n`fetch`, `files`, `entities`, `explore`, `search`, `ask`, `whoami`.\nCounted and frozen-set family: `count`, `enumerate`, `freeze_set`,\n`set_status`, `count_in_set`, `get_set`, `sets`. Deal-room state: `deal_list {workspace_id, thread_id?, include_terminal?, limit?\n(default 20, cap 100), cursor?}`, `deal_get {deal_id}`,\n`intent_status {intent_id, workspace_id?}` — authorised reads (the\ncreator / proposer, the pinned actor, or an active member of the\nworkspace; anything else is `not_found`, existence undisclosed).\nEvery entry but `fetch` advertises an `outputSchema` generated from\nits typed response and returns `structuredContent` the\nreference clients validate; `fetch` can return an image block and\ntherefore none. A failure on a schema-bearing entry travels in the\ntext block only (the typed reads: `{\"error\": {\"code\", \"message\"}}`;\nthe knowledge tools: the plain message). Every list-shaped tool takes\n`limit` (per-tool default, hard cap 100, clamped) and an opaque\n`cursor` and returns `next_cursor` while more remain (`truncated:\ntrue` when a page was cut short by size); older per-tool names\n(`after` / `next_after`, `nextCursor`, `has_more`) stay as aliases.\nThe whole serialised result is capped at 256 KiB — the host pages\ninside its own paging first, so the cap is a backstop. `search`/`ask` run\naccess-scoped retrieval across the caller's knowledge graphs (`ask`\nanswers from one room at a time and names its scope in `scope_note`);\n`fetch` reads one item by a prefixed id (`DOC:`/`KG:`/`FRAME:`/`FILE:`);\n`count`/`enumerate` are exhaustive rather than ranked, and are what\ncan establish absence. `freeze_set` is the only async arm — it returns\na `job_id` polled via `set_status` until `done`/`failed`.\nNO write tool: deals are committed and cancelled in the app, and\nfinancial proposals are filed through the payments connector's\n`propose_*` tools — `intent_status` reads their state. The legacy\ninternal tool surface at `POST /api/mcp/tools/call` keeps its routes\nand bodies; `yieldfabric/deal/list`, `yieldfabric/deal/get` and\n`yieldfabric/intent/status` there are aliases of the three reads.\n\nAuth: **connector credentials only** — a\n`yf_api_…` key minted with `kind: \"connector\"` (`POST\n/auth/api-key/generate`, exchanged by the router-wide middleware and\nbound to this server by that exchange), or an OAuth 2.1 grant whose\n`aud` names this server's resource URI\n(`https://agents.yieldfabric.com/mcp`, verified locally under the\nshared `JWT_SECRET`). A personal login JWT or personal key is refused\nwith the hint to mint a connector credential; a grant bound to another\nresource with \"Token was not issued for this resource\". Every refusal\n— an anonymous request included, `initialize` included — is `401`\nwith a `WWW-Authenticate` challenge pointing at\n`/.well-known/oauth-protected-resource`, which starts the OAuth 2.1\nconnector login against the auth service; never `403`. An auth outage\nwhile the bearer is validated is `503` + `Retry-After`, no challenge.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "description": "Request id. Absent = notification (202, no body).", "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "method": { "type": "string", "enum": [ "initialize", "ping", "tools/list", "tools/call", "notifications/initialized" ] }, "params": { "type": "object", "description": "Method params. For `tools/call`, `{name, arguments}`." } } }, "examples": { "initialize": { "summary": "MCP handshake", "value": { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-06-18", "clientInfo": { "name": "claude-code", "version": "2.0" } } } }, "toolCall": { "summary": "RAG query with citations", "value": { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "ask", "arguments": { "question": "What were the key terms of the Acme facility?" } } } } } } } }, "responses": { "200": { "description": "JSON-RPC response — carries either `result` or `error`; HTTP status is 200 either way, per JSON-RPC convention.", "content": { "application/json": { "schema": { "type": "object", "required": [ "jsonrpc", "id" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": {}, "result": { "type": "object" }, "error": { "type": "object", "properties": { "code": { "type": "integer", "description": "-32700 parse error, -32600 invalid request / batch, -32601 unknown method, -32602 invalid params" }, "message": { "type": "string" } } } } } } } }, "202": { "description": "Notification accepted (request had no id) — empty body." }, "401": { "description": "Missing, invalid, non-connector (`This session is not a connector credential: …`) or wrong-audience (`Token was not issued for this resource (…)`) credential. Carries a `WWW-Authenticate` header with a `resource_metadata` pointer (RFC 9728) so OAuth-capable MCP clients can discover the login flow. Body `{\"error\": \"\"}`.\n" }, "503": { "description": "Auth service unreachable while the bearer was being validated — the credential was not judged. `Retry-After: 5`, no `WWW-Authenticate` challenge; body `{\"error\": \"…\", \"code\": \"AUTH_SERVICE_UNAVAILABLE\"}`.\n" } }, "x-mcp": { "tool_name": "yieldfabric_agents_handleMcpHttp_Misc", "resource_uri": "yf://agents/mcp", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST https://agents.yieldfabric.com/mcp \\\n -H \"Authorization: Bearer $YF_CONNECTOR_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}'" } ], "x-related": [ "/.well-known/oauth-protected-resource", "/api/mcp/tools/call" ] }, "get": { "operationId": "methodNotAllowed_Misc", "x-method": "GET", "x-path": "/mcp", "x-handler": "yieldfabric_mcp_transport::http::method_not_allowed", "tags": [ "MCP" ], "summary": "GET /mcp — 405 (stateless server, no SSE stream)", "description": "The MCP endpoint runs in stateless Streamable-HTTP mode and never\npushes server-initiated messages, so the optional `GET` stream of the\nMCP spec is not offered. Clients that probe it receive\n`405 Method Not Allowed` and fall back to plain request/response —\nwhich is spec-conformant behavior on both sides.\n", "responses": { "405": { "description": "Method not allowed — use POST /mcp." } }, "x-mcp": { "tool_name": "yieldfabric_agents_methodNotAllowed_Misc", "resource_uri": "yf://agents/mcp", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -i https://agents.yieldfabric.com/mcp" } ], "x-related": [ "/mcp" ] } }, "/pipelines/ingest-document": { "post": { "operationId": "ingestDocument_Pipelines", "x-method": "POST", "x-path": "/pipelines/ingest-document", "x-handler": "handlers::pipelines::ingest_document", "tags": [ "Pipelines" ], "summary": "Ingest a document at selectable source, vector, or KG depth", "description": "Upload a document and kick off a file-extraction pipeline against it.\nAccepts plain text (`content`), base64-encoded binary document bytes\n(`content_base64`, dispatched by `content_media_type`), or a URL the server\nfetches on the caller's behalf (`url` — bypasses browser CORS; PDF responses\nflow through the base64 path, HTML/text through the content path). Supported\nbinary media types cover PDF, Word `.doc`/`.docx`, Excel\n`.xls`/`.xlsx`/`.xlsm`, and Outlook `.msg`; omission of\n`content_media_type` retains the historical `application/pdf` default. URL\ningestion accepts public HTTP(S) destinations only. DNS results and every\nredirect hop are checked against private/reserved address ranges and pinned\nfor the connection; response streaming is capped at 20 MiB. The retained\noriginal is also subject to `YF_SOURCE_MAX_BYTES` (100 MiB by default) and\ntransactional per-working-group byte/file quotas.\n\nBefore returning, the service commits the source-bearing document frame,\nAES-256-GCM-sealed replay payload, and resumable pipeline-run row in one\nPostgreSQL transaction. Binary document bytes are retained exactly; only the\nsearchable text is derived. Fetched HTML is retained after the same\nHTML-to-text normalization used by extraction. New\nrun specs contain an opaque `source_object_id`\ninstead of inline `content`, `content_base64`, or a credential-bearing\n`url`. This envelope protects the original replay/download payload; for\n`vector` and `full`, the extracted document text and chunks become\nsearchable KG data.\n\nExecution is admission-controlled for bulk robustness: when a local\ningest permit is free (bound `YF_INGEST_CONCURRENCY`, default 4 per\nreplica) the pipeline starts immediately; otherwise the run is accepted\nas durable `queued` work. Queue claims rotate across working groups and\nremain FIFO within each group, preventing one large tenant backlog from\nstarving others. A short PostgreSQL advisory-lock transaction serializes\nscheduler choice across replicas; execution begins after the claim commits\nand remains concurrent. Either way this endpoint returns the same\n`{run_id, kg_id, thread_id}` immediately — poll\n`GET /pipelines/{run_id}` for `queued → running → complete`. A folder\nof N files is therefore N calls that all return instantly and drain at\nbounded concurrency; a service restart mid-backlog requeues\ncrash-orphaned runs automatically (bounded attempts) instead of\nstranding per-file failures.\n\nBy default a fresh per-document KG is created and linked back to a\n`knowledge_documents` row by content hash. Notebook drop-doc flows set\n`target_kg_id` to place the document's selected processing output in an\nexisting personal notebook KG instead. For target-KG ingestion, the KG row is authoritative:\nthe service derives the run's `working_group_id` from that row, rejects a\nsupplied mismatching group with `400`, and does not create a separate\nfile-extraction discussion thread. `dedup_scope` defaults to the deployment's\n`YF_DEDUP_SCOPE_DEFAULT`, and a request may narrow but cannot widen that\npolicy. Document-frame identity is always deduplicated only inside the\ntarget KG. The canonical generation-bound HTTP path does not consult or\nregister the legacy immutable-artifact cache: without generation-scoped\nprovenance, cloning cannot prove lifecycle ownership across replacement,\ndeletion, and graph promotion. `working_group` and `global` therefore retain\ntheir compatible wire values and policy clamp but currently behave as\n`kg_only` for processing reuse.\n\nOptional `credibility` (NATO admiralty grade) and\n`source_class` (HUMINT / SIGINT / OSINT / IMINT / GEOINT / FININT) are\nstamped onto the document frame and inherited by SpeechActs that cite\nit. Auth: bearer JWT plus direct Member-or-higher `UploadDocuments`\nauthority when creating a new working-group KG (target-KG writes use the\nequivalent KG write gate). Not idempotent for new docs; idempotent at the\ncontent-hash level when targeting a notebook KG.\n\nProcessing depth is selected with the additive `processing_tier` query\nparameter. `store_only` commits the encrypted original and document\nmetadata without chunking; `vector` also chunks and embeds the document so\nit is discoverable through low-cost retrieval; `full` additionally extracts\nand publishes the KG. Omission remains `full`, exactly preserving the\nbehavior of existing clients. A vector-indexed document can be promoted\nlater with\n`POST /pipelines/kgs/{kg_id}/documents/{document_id}/promote-graph`\nwithout uploading or embedding its chunks again.\n\nOutlook extraction prefers the plain body, falls back to readable HTML,\nand includes available Subject, From, To, Cc, sent date, and attachment\nfilenames. Attachment payloads and embedded/OLE objects are not opened.\nAutomatic vision OCR remains a PDF-only fallback and is never applied to\nWord or Outlook bytes. Corrupt, encrypted/protected, or unsupported binary\nvariants fail with `400` extraction errors instead of being treated as text.\n", "parameters": [ { "name": "processing_tier", "in": "query", "required": false, "description": "Maximum processing depth for this ingest. `store_only` retains the\nencrypted source and document metadata without creating a retrieval\nindex; `vector` additionally chunks and embeds the current document\ngeneration for low-cost discovery/RAG; `full` additionally extracts and\npublishes its knowledge graph. Omission preserves the pre-tier behavior\nand is therefore equivalent to `full`. Bulk-upload clients that want\ninexpensive discovery should send `processing_tier=vector` explicitly.\n", "schema": { "type": "string", "enum": [ "store_only", "vector", "full" ], "default": "full", "description": "Maximum processing depth for a document-ingest run. Capabilities are\nmonotonic: `store_only` persists the source and metadata; `vector` adds\nchunks and embeddings; `full` adds graph extraction. The default is\n`full` for compatibility with callers that predate tier selection.\n" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Starts document ingestion from text, a base64 PDF, or a public URL. The\naccepted original payload is stored separately under authenticated\nencryption and the resumable run specification retains only an opaque\nsource reference. At `vector` and `full` depth, extracted text and chunks\nbecome queryable KG data and are not encrypted by this source-blob\nenvelope.\n", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Display name for the target KG." }, "title": { "type": [ "string", "null" ], "description": "Document title (used for chunk-link provenance)." }, "content": { "type": [ "string", "null" ], "description": "Plain text content. Exclusive with `content_base64` / `url`." }, "content_base64": { "type": [ "string", "null" ], "description": "Base64-encoded binary document bytes, extracted per\n`content_media_type` (default PDF).\n" }, "content_media_type": { "type": [ "string", "null" ], "description": "Additive. Media type of `content_base64`; omission means\n`application/pdf` (historical behavior). Accepted:\nPDF (`application/pdf`), legacy Word `.doc`\n(`application/msword`; aliases `application/x-msword`,\n`application/vnd.ms-word`, `application/word`, `application/doc`,\n`application/x-doc`), docx\n(`application/vnd.openxmlformats-officedocument.wordprocessingml.document`),\nxlsx (`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`),\nxlsm (`application/vnd.ms-excel.sheet.macroEnabled.12`), and legacy\nxls (`application/vnd.ms-excel`), and Outlook `.msg`\n(`application/vnd.ms-outlook`; aliases `application/x-msg`,\n`application/msg`, `application/x-outlook-msg`). Multipart uploads\nderive this automatically from the file's recognized content type or\n`.pdf`/`.doc`/`.docx`/`.xlsx`/`.xlsm`/`.xls`/`.msg` extension. Generic\n`application/octet-stream` and OLE MIME types do not identify a format;\na matching extension is still required. A scanned\n(image-only) PDF is OCR'd automatically via the vision model\n(metered as `document_ocr`; kill switch `YF_INGEST_OCR=off`,\nper-document page cap `YF_OCR_MAX_PAGES`, default 50). When OCR\nis disabled, capped, or fails, ingestion fails with a 400 whose\nmessage starts with `needs_ocr`. Word and Outlook inputs never enter\nthis OCR fallback. Corrupt/encrypted `.doc`, corrupt/encrypted or\nprotected `.msg`, and unidentified OLE2 containers return actionable\nextraction errors.\n" }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "Public HTTP(S) URL to fetch server-side. Private/reserved DNS results\nand redirect destinations are rejected; response body cap is 20 MiB.\n" }, "working_group_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Owner for a new per-document KG. When `target_kg_id` is supplied,\nthe service derives this value from the target KG; an explicitly\nsupplied different group is rejected.\n" }, "source_document_id": { "type": [ "string", "null" ], "format": "uuid" }, "vocab_context": { "type": [ "string", "null" ] }, "vocab_passes": { "type": "integer", "default": 1 }, "require_vocab_review": { "type": "boolean", "default": false }, "run_structural_completion": { "type": "boolean", "default": true }, "target_kg_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Home's drop-doc flow — write the document frame into this KG\ninstead of creating a new per-document KG. Its persisted owner is\nauthoritative for the run scope, and this flow does not create a\nfile-extraction discussion thread.\n" }, "provisional_extraction": { "type": "boolean", "default": false }, "credibility": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ], "description": "NATO admiralty grade for the source (see notebook::profile::Credibility)." }, "source_class": { "type": [ "string", "null" ], "description": "Multi-INT source class (HUMINT / SIGINT / OSINT / IMINT / GEOINT / FININT)." }, "dedup_scope": { "type": "string", "enum": [ "kg_only", "working_group", "global" ], "description": "Requested immutable-artifact dedup scope. When omitted, the service\nuses `YF_DEDUP_SCOPE_DEFAULT` (unset or invalid fails closed to\n`kg_only`). A request may narrow that deployment policy but cannot\nwiden it. All current values keep mutable document-frame identity\nlocal to the target KG; broader values are reserved for future\nimmutable-artifact reuse.\n" } } }, "examples": { "text": { "summary": "Plain text content", "value": { "name": "Acme Whitepaper", "title": "Acme Whitepaper v2", "content": "# Acme Whitepaper\n\nThe firm was founded in...", "working_group_id": "6c1c79bb-7e2e-4a06-83a7-9d4d6c7a0e21", "vocab_context": "fintech, structured finance", "vocab_passes": 2, "dedup_scope": "kg_only" } }, "url": { "summary": "Server-side fetch from a URL", "value": { "name": "BIS Quarterly Review Mar 2026", "url": "https://example.bis.org/publ/qtrpdf/r_qt2603.pdf", "working_group_id": "6c1c79bb-7e2e-4a06-83a7-9d4d6c7a0e21", "source_class": "OSINT", "credibility": "B2" } }, "notebook-drop": { "summary": "Drop a doc into a personal notebook KG", "value": { "name": "Counterparty memo - Globex", "content": "...", "target_kg_id": "4f1c7a8e-2b6f-4f01-9a2d-3a5d2c1e7b81", "provisional_extraction": true, "source_class": "HUMINT", "credibility": "C3" } }, "pdf": { "summary": "Base64-encoded PDF", "value": { "name": "Loan agreement Q2", "title": "Loan agreement, Globex Q2 2026", "content_base64": "JVBERi0xLjQK...", "working_group_id": "6c1c79bb-7e2e-4a06-83a7-9d4d6c7a0e21" } }, "legacy-word": { "summary": "Base64-encoded Word 97–2003 document", "value": { "name": "Legacy credit memo", "content_base64": "0M8R4KGxGuEAAAAA...", "content_media_type": "application/msword", "working_group_id": "6c1c79bb-7e2e-4a06-83a7-9d4d6c7a0e21" } } } } } }, "responses": { "200": { "description": "Ingestion accepted. Returns `run_id` and the target `kg_id`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "run_id", "kg_id" ], "properties": { "run_id": { "type": "string", "format": "uuid" }, "kg_id": { "type": "string", "format": "uuid" }, "thread_id": { "type": [ "string", "null" ] } } }, "examples": { "accepted": { "summary": "Accepted", "value": { "run_id": "9d3b1a2c-5e6f-4d7a-8b9c-0d1e2f3a4b5c", "kg_id": "4f1c7a8e-2b6f-4f01-9a2d-3a5d2c1e7b81", "thread_id": null } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "413": { "description": "The source or owning working group exceeds a configured file/byte limit.", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_ingestDocument_Pipelines", "resource_uri": "yf://agents/pipelines", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Memo\",\"content\":\"# Memo\\n\\nText...\",\"working_group_id\":\"6c1c79bb-7e2e-4a06-83a7-9d4d6c7a0e21\"}' \\\n 'https://agents.yieldfabric.com/pipelines/ingest-document?processing_tier=vector'\n" } ], "x-related": [ { "operationId": "startPipeline_Pipelines" }, { "operationId": "pipelineEvents_Pipelines" }, { "operationId": "getPipelineRun_Pipelines" }, { "operationId": "promoteDocumentGraph_Pipelines" }, { "url": "guides/pipelines-and-kgs.md", "description": "Pipelines and KGs guide" } ] } }, "/pipelines/ingest-document-upload": { "post": { "operationId": "ingestDocumentUpload_Pipelines", "x-method": "POST", "x-path": "/pipelines/ingest-document-upload", "x-handler": "handlers::pipelines::ingest_document_upload", "tags": [ "Pipelines" ], "summary": "Upload a supported document at selectable source, vector, or KG depth", "description": "Multipart counterpart to `POST /pipelines/ingest-document`. The `file`\npart accepts PDF, Word `.doc`/`.docx`, Excel `.xls`/`.xlsx`/`.xlsm`,\nOutlook `.msg`, or plain-text bytes; filename supplies `name`/`title` when\nthose fields are omitted. Classification prefers a recognized declared\nmedia type and otherwise uses the filename extension. Unknown OLE2\ncontainers remain unsupported. The handler uses the deployment's\n`YF_DEDUP_SCOPE_DEFAULT` and does not accept a per-request `dedup_scope`.\nAn optional `source_document_id` makes delivery idempotent: retries with the\nsame id and working group converge on the existing document KG/run.\n\nThe original payload is bounded by `YF_SOURCE_MAX_BYTES` (100 MiB by\ndefault) plus transactional per-working-group byte/file quotas, sealed\nunder `PAYMENT_DATA_ENCRYPTION_KEY`, and committed atomically with its document\nframe and pipeline-run row. The saved run spec contains only an opaque\nsource reference; `vector` and `full` tiers additionally publish searchable\ntext chunks. When `target_kg_id` is supplied, the service derives ownership from\nthe KG row, rejects a mismatching `working_group_id` with `400`, and keeps\nthe target/notebook flow threadless. Auth: bearer JWT.\n\nSelect processing depth with the `processing_tier` query parameter:\n`store_only` retains the source and metadata, `vector` also creates the\nlow-cost retrieval index, and `full` additionally extracts the graph.\nOmission remains `full` for existing callers. Use `vector` for bulk uploads\nintended for discovery-first triage, then call the document graph-promotion\nendpoint only for sources worth the additional extraction cost.\n\nAdmission and backlog scheduling match the JSON counterpart: work starts\ninline while a per-replica ingest permit is available, otherwise it is\ndurably queued. Claims rotate across working groups and are FIFO within one\ngroup; only the brief cross-replica scheduler choice is serialized, while\nclaimed pipelines execute concurrently.\n\nOriginal binary bytes are retained unchanged. Searchable text is derived\nwith format-specific parsers. Outlook output includes available Subject,\nFrom, To, Cc, sent date, body, and attachment filenames; attachment payloads\nand embedded/OLE objects are not opened. Automatic vision OCR remains a\nPDF-only fallback and is never applied to Word or Outlook content.\n", "parameters": [ { "name": "processing_tier", "in": "query", "required": false, "description": "Maximum processing depth for this ingest. `store_only` retains the\nencrypted source and document metadata without creating a retrieval\nindex; `vector` additionally chunks and embeds the current document\ngeneration for low-cost discovery/RAG; `full` additionally extracts and\npublishes its knowledge graph. Omission preserves the pre-tier behavior\nand is therefore equivalent to `full`. Bulk-upload clients that want\ninexpensive discovery should send `processing_tier=vector` explicitly.\n", "schema": { "type": "string", "enum": [ "store_only", "vector", "full" ], "default": "full", "description": "Maximum processing depth for a document-ingest run. Capabilities are\nmonotonic: `store_only` persists the source and metadata; `vector` adds\nchunks and embeddings; `full` adds graph extraction. The default is\n`full` for compatibility with callers that predate tier selection.\n" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "PDF, Word `.doc`/`.docx`, Excel `.xls`/`.xlsx`/`.xlsm`, Outlook\n`.msg`, or plain-text bytes. Classification uses a recognized declared\nmedia type first, then the filename extension.\n" }, "name": { "type": "string", "description": "Target KG display name; defaults to the filename stem." }, "title": { "type": "string", "description": "Document title; defaults to the filename." }, "working_group_id": { "type": "string", "format": "uuid", "description": "Owner for a new per-document KG. When `target_kg_id` is supplied,\nit must match the target KG's persisted owner.\n" }, "source_document_id": { "type": "string", "format": "uuid", "description": "Stable caller-supplied document identity. Repeating the same id in the\nsame working group converges on the existing per-document KG and a\nreusable pipeline run, making multipart delivery retry-safe.\n" }, "target_kg_id": { "type": "string", "format": "uuid", "description": "Existing notebook KG to receive the document. Its persisted owner is\nauthoritative and this flow does not create a separate extraction\nthread.\n" }, "vocab_context": { "type": "string" }, "require_vocab_review": { "type": "boolean", "default": false }, "run_structural_completion": { "type": "boolean", "default": true }, "provisional_extraction": { "type": "boolean", "default": false }, "source_class": { "type": "string", "description": "Multi-INT source class (HUMINT / SIGINT / OSINT / IMINT / GEOINT / FININT)." } }, "description": "Multipart upload form. This endpoint uses the deployment's\n`YF_DEDUP_SCOPE_DEFAULT`; it does not accept a per-request `dedup_scope`.\nThe retained original is encrypted and the saved run spec contains only\nits opaque source reference, matching the JSON ingest endpoint.\n" }, "examples": { "pdf": { "summary": "PDF upload into a working group", "value": { "file": "", "name": "Loan agreement Q2", "title": "Loan agreement, Globex Q2 2026", "working_group_id": "6c1c79bb-7e2e-4a06-83a7-9d4d6c7a0e21", "source_document_id": "c62b0e9c-b75d-5fac-b529-b5faafc6fcb3", "source_class": "OSINT" } }, "outlook-message": { "summary": "Outlook message upload", "value": { "file": "", "name": "Counterparty email", "working_group_id": "6c1c79bb-7e2e-4a06-83a7-9d4d6c7a0e21" } } } } } }, "responses": { "200": { "description": "Ingestion accepted. Returns the run and target KG identifiers.", "content": { "application/json": { "schema": { "type": "object", "required": [ "run_id", "kg_id" ], "properties": { "run_id": { "type": "string", "format": "uuid" }, "kg_id": { "type": "string", "format": "uuid" }, "thread_id": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "413": { "description": "The upload or owning working group exceeds a configured file/byte limit.", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_ingestDocumentUpload_Pipelines", "resource_uri": "yf://agents/pipelines", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -F 'file=@./agreement.pdf;type=application/pdf' \\\n -F 'working_group_id=6c1c79bb-7e2e-4a06-83a7-9d4d6c7a0e21' \\\n -F 'source_document_id=c62b0e9c-b75d-5fac-b529-b5faafc6fcb3' \\\n 'https://agents.yieldfabric.com/pipelines/ingest-document-upload?processing_tier=vector'\n" } ], "x-related": [ { "operationId": "ingestDocument_Pipelines" }, { "operationId": "pipelineEvents_Pipelines" }, { "operationId": "getPipelineRun_Pipelines" }, { "operationId": "promoteDocumentGraph_Pipelines" } ] } }, "/pipelines/kgs/{kg_id}/documents/{document_id}/promote-graph": { "post": { "operationId": "promoteDocumentGraph_Pipelines", "x-method": "POST", "x-path": "/pipelines/kgs/{kg_id}/documents/{document_id}/promote-graph", "x-handler": "handlers::pipelines::promote_document_graph", "tags": [ "Pipelines" ], "summary": "Start or return vector-to-KG promotion for a document generation", "description": "Start the optional graph-extraction stage for the document's current,\nalready admitted generation. This is the explicit second-stage operation\nfor documents originally ingested with `processing_tier=vector`; clients do\nnot upload the file again.\n\nThe service reuses the retained source, published chunks, and chunk\nembeddings for that exact generation. Graph extraction runs in an isolated,\nnon-readable staging KG and becomes visible in the target KG only when the\ncomplete frame/edge/lexicon materialization is promoted atomically. A\nfailed, cancelled, superseded, or stale run leaves the previously published\nvector index and graph unchanged. Promotion never re-embeds chunks, though\ngraph extraction may still embed newly extracted semantic frames.\n\nThe caller needs write access to `kg_id`; `document_id` must identify a\ndocument in that KG. Promotion fails closed if the document generation\nchanges while work is running or if its retained replay source is no longer\navailable. The endpoint returns a normal pipeline start response. Track the\nreturned run through `GET /pipelines/{run_id}` or the pipeline SSE stream.\nRepeating the request while promotion is queued, running, or paused returns\nthat run; after success it returns the completed run for the already-ready\ngraph. A failed prior run may be replaced by a new attempt.\n", "parameters": [ { "name": "kg_id", "in": "path", "required": true, "description": "KG that owns the document and receives the promoted graph.", "schema": { "type": "string", "format": "uuid" } }, { "name": "document_id", "in": "path", "required": true, "description": "Current document frame id in the target KG.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "New or existing graph-promotion pipeline run.", "content": { "application/json": { "schema": { "type": "object", "required": [ "run_id", "kg_id" ], "properties": { "run_id": { "type": "string", "format": "uuid" }, "kg_id": { "type": "string", "format": "uuid" }, "thread_id": { "type": [ "string", "null" ] } } }, "examples": { "accepted-or-existing": { "summary": "Promotion run", "value": { "run_id": "9d3b1a2c-5e6f-4d7a-8b9c-0d1e2f3a4b5c", "kg_id": "4f1c7a8e-2b6f-4f01-9a2d-3a5d2c1e7b81", "thread_id": null } } } } } }, "400": { "description": "Malformed path input.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing or invalid caller credential.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "403": { "description": "Caller lacks write access to the target KG.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "The document is not a current document in the target KG.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Vector publication or its retained immutable source is unavailable.", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_promoteDocumentGraph_Pipelines", "resource_uri": "yf://agents/pipelines", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n https://agents.yieldfabric.com/pipelines/kgs/4f1c7a8e-2b6f-4f01-9a2d-3a5d2c1e7b81/documents/8b6b31b8-3a7d-4d98-a759-e2160f1e1f28/promote-graph\n" } ], "x-related": [ { "operationId": "ingestDocument_Pipelines" }, { "operationId": "ingestDocumentUpload_Pipelines" }, { "operationId": "getPipelineRun_Pipelines" }, { "operationId": "pipelineEvents_Pipelines" }, { "url": "guides/pipelines-and-kgs.md", "description": "Pipelines and KGs guide" } ] } }, "/pipelines/run": { "post": { "operationId": "startPipeline_Pipelines", "x-method": "POST", "x-path": "/pipelines/run", "x-handler": "handlers::pipelines::start_pipeline", "tags": [ "Pipelines" ], "summary": "Start a named pipeline (file_extraction, reasoning, or extract_then_reason)", "description": "Kick off a Pipeline run. The body is a `PipelineStartRequest` discriminated\nby `kind`: `file_extraction` ingests a pre-chunked document into a fresh\nKG; `reasoning` spins up a multi-agent team that thinks through a problem\nagainst an existing parent KG; `extract_then_reason` chains the two.\nThe handler pre-creates the target KG and `pipeline_runs` row, then\nspawns the executor in a background task and returns synchronously with\n`{run_id, kg_id, thread_id}`. Auth: bearer JWT plus direct Member-or-higher\n`CreateSession` authority in the effective working group; economy-derived\nvisibility alone is read-only. A supplied reasoning `thread_id` must name a\npublic thread in that same group. The user's group + economy memberships\nscope which agents are eligible. Not idempotent —\nevery call creates a new run. For document upload flows, prefer\n`POST /pipelines/ingest-document` which handles chunking for you.\nStream progress via `GET /pipelines/{run_id}/events`.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Tagged union — one of `file_extraction`, `reasoning`, or\n`extract_then_reason`. Field shape depends on `kind`.\n", "oneOf": [ { "type": "object", "required": [ "kind", "name", "doc_text", "chunks" ], "properties": { "kind": { "type": "string", "enum": [ "file_extraction" ] }, "name": { "type": "string" }, "doc_text": { "type": "string" }, "chunks": { "type": "array", "items": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string" }, "id": { "type": [ "string", "null" ], "format": "uuid" }, "index": { "type": "integer", "default": 0 }, "total": { "type": "integer", "default": 1 }, "doc_title": { "type": [ "string", "null" ] }, "doc_id": { "type": [ "string", "null" ], "format": "uuid" } } } }, "working_group_id": { "type": [ "string", "null" ], "format": "uuid" }, "vocab_context": { "type": [ "string", "null" ] }, "vocab_passes": { "type": "integer", "default": 1 }, "require_vocab_review": { "type": "boolean", "default": false }, "run_structural_completion": { "type": "boolean", "default": true } } }, { "type": "object", "required": [ "kind", "name", "problem" ], "properties": { "kind": { "type": "string", "enum": [ "reasoning" ] }, "name": { "type": "string" }, "problem": { "type": "string" }, "working_group_id": { "type": [ "string", "null" ], "format": "uuid" }, "parent_kg_id": { "type": [ "string", "null" ], "format": "uuid" }, "thread_id": { "type": [ "string", "null" ] }, "require_team_formation": { "type": "boolean", "default": false }, "require_vocab_review": { "type": "boolean", "default": false }, "run_vocab_discovery": { "type": "boolean", "default": true }, "max_turns": { "type": [ "integer", "null" ] }, "conversational_pause": { "type": "boolean", "default": false }, "agents": { "oneOf": [ { "type": "array", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" }, "version": { "type": [ "string", "null" ] } } } }, { "type": "null" } ] }, "model_overrides": { "oneOf": [ { "type": "object", "additionalProperties": { "type": "object", "description": "Per-agent model routing. The `ProviderRegistry` resolves this to a\nconcrete LLMProvider at runtime.\n", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "default", "tagged", "exact" ] }, "tag": { "type": [ "string", "null" ], "description": "Used when kind=tagged." }, "provider": { "type": [ "string", "null" ], "description": "Used when kind=exact." }, "model": { "type": [ "string", "null" ], "description": "Used when kind=exact." } } } }, { "type": "null" } ] } } }, { "type": "object", "required": [ "kind", "name", "doc_text", "chunks", "problem" ], "properties": { "kind": { "type": "string", "enum": [ "extract_then_reason" ] }, "name": { "type": "string" }, "doc_text": { "type": "string" }, "chunks": { "type": "array", "items": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string" }, "id": { "type": [ "string", "null" ], "format": "uuid" }, "index": { "type": "integer", "default": 0 }, "total": { "type": "integer", "default": 1 }, "doc_title": { "type": [ "string", "null" ] }, "doc_id": { "type": [ "string", "null" ], "format": "uuid" } } } }, "problem": { "type": "string" }, "working_group_id": { "type": [ "string", "null" ], "format": "uuid" }, "vocab_context": { "type": [ "string", "null" ] } } } ] }, "examples": { "file-extraction": { "summary": "Extract a pre-chunked document", "value": { "kind": "file_extraction", "name": "Acme Whitepaper KG", "doc_text": "# Acme Whitepaper\n\nThe Acme whitepaper...", "chunks": [ { "content": "## Section 1\n\nThe firm was founded in...", "index": 0, "total": 2, "doc_title": "Acme Whitepaper" }, { "content": "## Section 2\n\nThe yield strategy...", "index": 1, "total": 2, "doc_title": "Acme Whitepaper" } ], "working_group_id": "6c1c79bb-7e2e-4a06-83a7-9d4d6c7a0e21", "vocab_context": "fintech, structured finance", "vocab_passes": 2, "require_vocab_review": true } }, "reasoning": { "summary": "Multi-agent reasoning over an existing KG", "value": { "kind": "reasoning", "name": "Cash deployment options", "problem": "What are three viable options for deploying the new $5M cash balance, given the current yield environment?", "working_group_id": "6c1c79bb-7e2e-4a06-83a7-9d4d6c7a0e21", "parent_kg_id": "4f1c7a8e-2b6f-4f01-9a2d-3a5d2c1e7b81", "require_team_formation": true, "run_vocab_discovery": false, "max_turns": 8 } }, "extract-then-reason": { "summary": "Ingest a memo and immediately reason over it", "value": { "kind": "extract_then_reason", "name": "Q2 memo follow-up", "doc_text": "# Q2 memo\n\n...", "chunks": [ { "content": "## Strategy\n\n...", "index": 0, "total": 1 } ], "problem": "What are the risks the memo doesn't address?", "working_group_id": "6c1c79bb-7e2e-4a06-83a7-9d4d6c7a0e21" } } } } } }, "responses": { "200": { "description": "Pipeline accepted. `run_id` is the cursor for status/events/cancel/resume; `kg_id` is the target KG.", "content": { "application/json": { "schema": { "type": "object", "required": [ "run_id", "kg_id" ], "properties": { "run_id": { "type": "string", "format": "uuid" }, "kg_id": { "type": "string", "format": "uuid" }, "thread_id": { "type": [ "string", "null" ] } } }, "examples": { "started": { "summary": "Started", "value": { "run_id": "9d3b1a2c-5e6f-4d7a-8b9c-0d1e2f3a4b5c", "kg_id": "4f1c7a8e-2b6f-4f01-9a2d-3a5d2c1e7b81", "thread_id": "22222222-3333-4444-5555-666666666666" } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_startPipeline_Pipelines", "resource_uri": "yf://agents/pipelines", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" \\\n -d '{\"kind\":\"reasoning\",\"name\":\"Test\",\"problem\":\"What is X?\",\"working_group_id\":\"6c1c79bb-7e2e-4a06-83a7-9d4d6c7a0e21\"}' \\\n https://agents.yieldfabric.com/pipelines/run\n" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx, os\nr = httpx.post(\n \"https://agents.yieldfabric.com/pipelines/run\",\n headers={\"Authorization\": f\"Bearer {os.environ['JWT']}\"},\n json={\n \"kind\": \"reasoning\",\n \"name\": \"Cash deployment options\",\n \"problem\": \"What are three viable options for deploying $5M?\",\n \"working_group_id\": \"6c1c79bb-7e2e-4a06-83a7-9d4d6c7a0e21\",\n \"max_turns\": 8,\n },\n)\nr.raise_for_status()\nrun = r.json()\nprint(f\"run_id={run['run_id']} kg_id={run['kg_id']}\")\n# Then stream:\n# with httpx.stream(\"GET\", f\"https://agents.yieldfabric.com/pipelines/{run['run_id']}/events\", ...) as s: ...\n" } ], "x-related": [ { "operationId": "ingestDocument_Pipelines" }, { "operationId": "getPipelineRun_Pipelines" }, { "operationId": "pipelineEvents_Pipelines" }, { "operationId": "resumePipeline_Pipelines" }, { "operationId": "cancelPipeline_Pipelines" }, { "url": "guides/pipelines-and-kgs.md", "description": "Pipelines and KGs guide" } ] } }, "/pipelines/{run_id}": { "get": { "operationId": "getPipelineRun_Pipelines", "x-method": "GET", "x-path": "/pipelines/{run_id}", "x-handler": "handlers::pipelines::get_pipeline_run", "tags": [ "Pipelines" ], "summary": "Get the persisted record for a pipeline run", "description": "Return the persisted `PipelineRunRecord` for `run_id`. Carries status\n(`queued` / `running` / `paused` / `complete` / `failed` / `cancelled` /\n`rewound`), target KG, working group, parent run, the saved spec used for\nresume/rewind, current step and turn, paused reason, and any error message.\nThis compatibility projection does not include the row's thread, problem,\nor timestamp columns. For new\ndocument-ingest runs, `spec` contains an opaque `source_object_id` and the\neffective `dedup_scope` and `processing_tier`; it does not expose inline\nsource text, PDF base64, or the submitted URL. Internal source/generation\nidentifiers are not bearer capabilities.\nAuth: bearer JWT. Idempotent and safe to poll.\nNote: this is the persisted snapshot, not a live tick. For real-time\nprogress events use `GET /pipelines/{run_id}/events` (SSE).\n", "parameters": [ { "name": "run_id", "in": "path", "required": true, "description": "Pipeline run id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Pipeline run record.", "content": { "application/json": { "schema": { "type": "object", "description": "One pipeline run's persisted state. `spec` is an opaque replay contract,\nnot a copy of every submitted byte. New document-ingest runs replace\n`content`, `content_base64`, and `url` with an internal\n`source_object_id` that identifies the separately encrypted original\nsource. Clients must not treat that identifier as a download capability.\n", "required": [ "id", "kind", "name", "spec", "state", "current_step_index", "current_turn", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "file_extraction", "reasoning", "extract_then_reason", "reason_over", "ingest_document" ] }, "name": { "type": "string" }, "working_group_id": { "type": [ "string", "null" ], "format": "uuid" }, "target_kg_id": { "type": [ "string", "null" ], "format": "uuid" }, "parent_run_id": { "type": [ "string", "null" ], "format": "uuid" }, "spec": { "description": "Arbitrary JSON value." }, "state": { "description": "Arbitrary JSON value." }, "current_step_index": { "type": "integer" }, "current_turn": { "type": "integer" }, "status": { "type": "string", "enum": [ "queued", "running", "paused", "complete", "failed", "cancelled", "rewound" ], "description": "`queued` = accepted durable work awaiting an execution slot. Ingest-document runs are born queued when the replica's ingest concurrency bound (`YF_INGEST_CONCURRENCY`, default 4) is busy — the normal shape for bulk folder uploads. Backend workers claim the queued backlog round-robin across `working_group_id` and FIFO within each working group. Scheduler choice is serialized briefly across replicas; claimed runs execute concurrently. Crash-orphaned ingest runs are requeued automatically under a bounded attempt cap. Queued runs can be cancelled but not resumed (a worker owns their execution)." }, "paused_reason": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] } } }, "examples": { "queued-ingest": { "summary": "A vector ingest waiting for an execution slot", "value": { "id": "9d3b1a2c-5e6f-4d7a-8b9c-0d1e2f3a4b5c", "kind": "file_extraction", "name": "Memo", "working_group_id": "6c1c79bb-7e2e-4a06-83a7-9d4d6c7a0e21", "target_kg_id": "4f1c7a8e-2b6f-4f01-9a2d-3a5d2c1e7b81", "parent_run_id": null, "spec": { "name": "Memo", "processing_tier": "vector", "dedup_scope": "kg_only", "source_object_id": "1e8e56a2-4a74-4d82-9fc0-32f8ef5a1b11", "document_generation_id": "79e71113-d086-4f47-9890-d7cdd42acbde" }, "state": {}, "current_step_index": 0, "current_turn": 0, "status": "queued", "paused_reason": null, "error": null } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getPipelineRun_Pipelines", "resource_uri": "yf://agents/pipelines", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/pipelines/9d3b1a2c-5e6f-4d7a-8b9c-0d1e2f3a4b5c" } ], "x-related": [ { "operationId": "startPipeline_Pipelines" }, { "operationId": "pipelineEvents_Pipelines" }, { "operationId": "cancelPipeline_Pipelines" }, { "operationId": "resumePipeline_Pipelines" }, { "url": "guides/pipelines-and-kgs.md", "description": "Pipelines and KGs guide" } ] } }, "/pipelines/{run_id}/cancel": { "post": { "operationId": "cancelPipeline_Pipelines", "x-method": "POST", "x-path": "/pipelines/{run_id}/cancel", "x-handler": "handlers::pipelines::cancel_pipeline", "tags": [ "Pipelines" ], "summary": "Cancel an in-flight pipeline run", "description": "Atomically mark a running pipeline cancelled in PostgreSQL and invalidate\nits execution lease/generation. This works when the request is routed to a\ndifferent replica than the executor; a same-process cancel flag only wakes\nthe worker sooner. Already-authorized writes may finish before the database\nfence is acquired, but a superseded executor cannot commit new writes.\nAuth: bearer JWT plus direct Member-or-higher `ParticipateSession`\nauthority in the run's working group. Returns 404 when the durable run is no longer running.\nNo request body required; clients should POST an empty body.\n", "parameters": [ { "name": "run_id", "in": "path", "required": true, "description": "Pipeline run id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Durable run cancelled and its execution generation invalidated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "cancelled" ], "properties": { "cancelled": { "type": "boolean" } } }, "examples": { "ok": { "summary": "Cancelled", "value": { "cancelled": true, "run_id": "9d3b1a2c-5e6f-4d7a-8b9c-0d1e2f3a4b5c" } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_cancelPipeline_Pipelines", "resource_uri": "yf://agents/pipelines", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/pipelines/9d3b1a2c-5e6f-4d7a-8b9c-0d1e2f3a4b5c/cancel" } ], "x-related": [ { "operationId": "startPipeline_Pipelines" }, { "operationId": "getPipelineRun_Pipelines" }, { "operationId": "resumePipeline_Pipelines" }, { "url": "guides/pipelines-and-kgs.md", "description": "Pipelines and KGs guide" } ] } }, "/pipelines/{run_id}/events": { "get": { "operationId": "pipelineEvents_Pipelines", "x-method": "GET", "x-path": "/pipelines/{run_id}/events", "x-handler": "handlers::pipelines::pipeline_events", "tags": [ "Pipelines" ], "summary": "Server-Sent Events stream of pipeline progress", "description": "Open a Server-Sent Events stream of `TransformProgress` events for the\npipeline identified by `run_id`. The handler first replays the buffered\nin-memory event log so a reconnecting client never misses events, then\nswitches to the live broadcast subscription. Internal control events\nare filtered server-side. Auth: bearer JWT. Idempotent at the read\nlevel — multiple clients can subscribe to the same run.\nWhen the run has no in-memory broadcaster (paused, finished, or\norphaned), the handler returns `410 Gone` with the persisted status so\nthe client can decide whether to call `POST /pipelines/{run_id}/resume`\nor stop polling.\n", "parameters": [ { "name": "run_id", "in": "path", "required": true, "description": "Pipeline run id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "access_token", "in": "query", "required": false, "description": "JWT — used by browser `EventSource` clients that cannot send the `Authorization` header.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "SSE stream. Each event is a JSON `TransformProgress` payload (see `x-event-types`).", "content": { "text/event-stream": { "schema": { "type": "object", "description": "Each SSE event has an `event` name (the wire-level `event:` line) and a\n`data` JSON payload (the wire-level `data:` line, JSON-decoded). The exact\nschemas for each event variant are documented in the operation's\n`x-event-types` extension.\n", "required": [ "event", "data" ], "properties": { "event": { "type": "string", "description": "Event name from the operation's `x-event-types` enumeration." }, "data": { "description": "JSON payload. Shape depends on `event` — see `x-event-types`." }, "id": { "type": [ "string", "null" ], "description": "Optional SSE event id (used for resume cursors)." } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "410": { "description": "No active stream for this run. Body carries the persisted status — the\nclient can POST `/resume` for a paused or orphaned run, or stop polling\nif the run has terminated.\n", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-event-types": [ { "name": "pipeline_started", "description": "Run is starting. Carries `run_id`, `kind`, `total_steps`." }, { "name": "pipeline_step_started", "description": "Pipeline step starting. Carries `step_index`, `step_kind`, `name`." }, { "name": "pipeline_step_complete", "description": "Pipeline step finished. Carries `step_index`." }, { "name": "pipeline_checkpoint", "description": "Pipeline reached a named checkpoint. Carries `checkpoint_id`, `reason`, optional `payload`, optional `requires_user_action`." }, { "name": "pipeline_paused", "description": "Pipeline paused at a checkpoint. Carries `run_id`, `checkpoint_id`. Resume via POST /pipelines/{run_id}/resume." }, { "name": "pipeline_complete", "description": "Pipeline finished successfully. Carries `run_id`, `kg_id`, `total_nodes`, `total_edges`." }, { "name": "pipeline_failed", "description": "Pipeline failed. Carries `run_id`, optional `phase`, `error`." }, { "name": "transform_started", "description": "A transform within the pipeline started. Carries `kind`, optional `total_inputs`." }, { "name": "transform_complete", "description": "Transform finished. Carries `kind`, `node_count`, `edge_count`." }, { "name": "transform_extension", "description": "Catch-all for transform-specific events. Carries `kind` + a free-form `payload`." }, { "name": "turn_started", "description": "A reasoning turn started. Carries `turn`, `input_kind`, optional `input_label`." }, { "name": "turn_complete", "description": "Turn finished. Carries `turn`, `total_nodes`, `total_edges`." }, { "name": "input_processed", "description": "An input chunk was processed. Carries `index`, `total`, optional `label`." }, { "name": "agent_invoked", "description": "An agent was invoked for a turn. Carries `agent_id`, `turn`, `round`." }, { "name": "agent_inner_round_complete", "description": "Inner agent round finished. Carries `agent_id`, `turn`, `round`, `mutations`, `reads`." }, { "name": "agent_done", "description": "Agent finished for a turn. Carries `agent_id`, `turn`." }, { "name": "node_added", "description": "Node committed to the KG. Carries `key`, `label`, `node_type`, `layer`." }, { "name": "edge_added", "description": "Edge committed. Carries `from`, `to`, `edge_type`, `layer`, `agent_id`." }, { "name": "dedup_collapsed", "description": "Two nodes/edges deduplicated into one." }, { "name": "edge_dropped", "description": "Edge dropped during reconciliation." }, { "name": "vocabulary_evolved", "description": "Lexicon updated (new predicates/types added)." }, { "name": "schema_verified", "description": "Schema-verification pass succeeded for a snapshot." }, { "name": "convergence_update", "description": "Convergence metric tick (ontological/epistemic axes)." }, { "name": "persisted", "description": "Snapshot persisted to durable storage." }, { "name": "kg_updated", "description": "KG row updated (counters, latest snapshot pointer)." }, { "name": "read_tool_called", "description": "An agent invoked a read tool." }, { "name": "read_tool_result", "description": "Read-tool result returned." }, { "name": "side_effect_executed", "description": "A side-effect transform executed (HTTP call, etc.)." }, { "name": "waiting_for_input", "description": "Pipeline blocked on human input. Use POST /pipelines/{run_id}/input to respond." }, { "name": "human_input_received", "description": "Input delivered to the pipeline (echo confirmation)." }, { "name": "suppress_persist", "description": "Persistence intentionally suppressed for this delta (transient)." } ], "x-mcp": { "tool_name": "yieldfabric_agents_pipelineEvents_Pipelines", "resource_uri": "yf://agents/pipelines", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -N -H \"Authorization: Bearer $JWT\" -H \"Accept: text/event-stream\" https://agents.yieldfabric.com/pipelines/9d3b1a2c-5e6f-4d7a-8b9c-0d1e2f3a4b5c/events" } ], "x-related": [ { "operationId": "startPipeline_Pipelines" }, { "operationId": "getPipelineRun_Pipelines" }, { "operationId": "pipelineInput_Pipelines" }, { "operationId": "cancelPipeline_Pipelines" }, { "operationId": "resumePipeline_Pipelines" }, { "url": "guides/pipelines-and-kgs.md", "description": "Pipelines and KGs guide" } ] } }, "/pipelines/{run_id}/input": { "post": { "operationId": "pipelineInput_Pipelines", "x-method": "POST", "x-path": "/pipelines/{run_id}/input", "x-handler": "handlers::pipelines::pipeline_input", "tags": [ "Pipelines" ], "summary": "Deliver per-turn human input to a waiting pipeline", "description": "Deliver a `HumanInput` to a running pipeline whose durable input window is\nopen (the SSE stream will have emitted `waiting_for_input`). The body is\na discriminated `HumanInput` JSON: `proceed` (continue with accumulated\nguidance), `done` (finish now), `cancel` (set the cancel flag), `guidance`\n(free-form prompt prepended to subsequent agent turns), `agent_done`\n(mark a specific agent finished), `proxy_mutation` (apply a user-authored\nmutation as if the user were an agent), or `rewind` (cancel + ask the\nclient to follow up with `/rewind`). Multiple inputs may be posted in\nsequence; the executor processes them until it sees `proceed`, `done`,\nor `cancel`. Auth: bearer JWT plus direct Member-or-higher\n`PostMessages` authority in the run's working group. Without\n`Idempotency-Key`, each request is a\ndistinct input. With the header, a retry with the same body returns the\noriginal success; reusing the key with a different body returns 409.\nThe chat message and run-scoped input queue row commit atomically in\nPostgreSQL, and the owning executor polls that queue across replicas. The\nevent relay is only a low-latency wake-up/UI fan-out path.\nReturns 404 when the run has no associated public thread in its working\ngroup (private threads cannot back group-visible pipeline runs), and 409 for\na new input outside the active\n`waiting_for_input` window.\n", "parameters": [ { "name": "run_id", "in": "path", "required": true, "description": "Pipeline run id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Opaque caller-generated key (1-256 characters). Retrying the same run,\nkey, authenticated actor, and body returns the original 200 even after the\naccepting window closes. Reuse with a different actor or body returns 409.\n", "schema": { "type": "string", "minLength": 1, "maxLength": 256 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Deliver per-turn human input to a paused pipeline — wire shape of\n`pipeline::types::HumanInput`, a tagged union on `kind`. The wait\nloop terminates on `proceed`, `done`, `cancel`, or `rewind`; other\nvariants accumulate state and the loop keeps waiting.\n", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "proceed", "done", "guidance", "agent_done", "cancel", "proxy_mutation", "rewind" ] }, "content": { "type": [ "string", "null" ], "description": "For `guidance` — free-form NL prepended to subsequent agent prompts." }, "target_agent": { "type": [ "string", "null" ], "description": "For `guidance` — when set, only this agent sees the guidance." }, "agent_id": { "type": [ "string", "null" ], "description": "For `agent_done` — mark this agent done; excluded from subsequent turns." }, "mutation": { "oneOf": [ { "type": "null" }, { "description": "Arbitrary JSON value." } ], "description": "For `proxy_mutation` — a `Mutation` payload defined by the pipeline runtime (opaque shape)." }, "to_step_id": { "type": [ "string", "null" ], "description": "For `rewind` — named earlier step to backtrack to." } } }, "examples": { "proceed": { "summary": "Just continue", "value": { "kind": "proceed" } }, "guidance": { "summary": "Inject guidance for the next turns", "value": { "kind": "guidance", "content": "Don't go below A2 credit quality for cash deployment." } }, "target-guidance": { "summary": "Guidance for one specific agent only", "value": { "kind": "guidance", "content": "Focus on the dividend impact.", "target_agent": "critic" } }, "cancel": { "summary": "Cancel the run", "value": { "kind": "cancel" } }, "agent-done": { "summary": "Excuse one agent from subsequent turns", "value": { "kind": "agent_done", "agent_id": "critic" } } } } } }, "responses": { "200": { "description": "Input accepted into the durable run queue. The existing `delivered` response field is retained for wire compatibility.", "content": { "application/json": { "schema": { "type": "object", "description": "Acknowledgement payload — input was delivered into the thread.", "required": [ "delivered", "run_id" ], "properties": { "delivered": { "type": "boolean" }, "run_id": { "type": "string", "format": "uuid" } } }, "examples": { "delivered": { "summary": "Delivered", "value": { "delivered": true, "run_id": "9d3b1a2c-5e6f-4d7a-8b9c-0d1e2f3a4b5c" } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "409": { "description": "The run is not waiting for new input, or the idempotency key was reused with a different input.", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_pipelineInput_Pipelines", "resource_uri": "yf://agents/pipelines", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" \\\n -d '{\"kind\":\"proceed\"}' \\\n https://agents.yieldfabric.com/pipelines/9d3b1a2c-5e6f-4d7a-8b9c-0d1e2f3a4b5c/input\n" } ], "x-related": [ { "operationId": "pipelineEvents_Pipelines" }, { "operationId": "cancelPipeline_Pipelines" }, { "operationId": "rewindPipeline_Pipelines" }, { "url": "guides/pipelines-and-kgs.md", "description": "Pipelines and KGs guide" } ] } }, "/pipelines/{run_id}/invocations": { "get": { "operationId": "listInvocations_Pipelines", "x-method": "GET", "x-path": "/pipelines/{run_id}/invocations", "x-handler": "handlers::agent_registry::list_invocations", "tags": [ "Pipelines" ], "summary": "List agent invocations recorded for a pipeline run", "description": "Requires access to the run and each returned invocation's agent and KG. All attributed run KGs, working groups and private threads are authorized.\nReturn the invocation log for a pipeline run. Each row carries the\ninvoking agent, the turn index, parse success, token usage, latency,\nand a pointer to the prompt + response payloads. Filter by `agent_id`,\nby turn range (`turn_from` / `turn_to`), and by `parse_ok` to find\nfailed parses. Pagination is offset-based (`limit`, `offset`); default\nlimit is 100. Auth: bearer JWT. Idempotent.\nUse this to debug pipeline behaviour — combined with\n`/invocations/{id}/prompt` and `/invocations/{id}/response` you can see\nexactly what each agent saw and replied with.\n", "parameters": [ { "name": "run_id", "in": "path", "required": true, "description": "Pipeline run id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "agent_id", "in": "query", "required": false, "description": "Filter to invocations made by this agent.", "schema": { "type": "string" } }, { "name": "turn_from", "in": "query", "required": false, "description": "Inclusive lower bound on turn index.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "turn_to", "in": "query", "required": false, "description": "Inclusive upper bound on turn index.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "parse_ok", "in": "query", "required": false, "description": "True returns only successful parses; false returns only parse failures.", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum rows. Default 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Skip the first N rows.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Array of `InvocationRow` records.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "One agent invocation in a pipeline run (LLM call trace).", "required": [ "id", "run_id", "kg_id", "agent_id", "turn", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "run_id": { "type": "string", "format": "uuid" }, "kg_id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string" }, "turn": { "type": "integer" }, "prompt_tokens": { "type": [ "integer", "null" ] }, "completion_tokens": { "type": [ "integer", "null" ] }, "latency_ms": { "type": [ "integer", "null" ] }, "parse_ok": { "type": [ "boolean", "null" ] }, "error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } }, "examples": { "two-rows": { "summary": "Two invocations", "value": [ { "id": "11111111-aaaa-bbbb-cccc-222222222222", "run_id": "9d3b1a2c-5e6f-4d7a-8b9c-0d1e2f3a4b5c", "kg_id": "4f1c7a8e-2b6f-4f01-9a2d-3a5d2c1e7b81", "agent_id": "yieldfabric.proposer", "turn": 0, "parse_ok": true, "prompt_tokens": 1240, "completion_tokens": 312, "latency_ms": 980, "created_at": "2027-05-17T13:00:05Z" }, { "id": "22222222-aaaa-bbbb-cccc-333333333333", "run_id": "9d3b1a2c-5e6f-4d7a-8b9c-0d1e2f3a4b5c", "kg_id": "4f1c7a8e-2b6f-4f01-9a2d-3a5d2c1e7b81", "agent_id": "yieldfabric.critic", "turn": 0, "parse_ok": false, "prompt_tokens": 1380, "completion_tokens": 96, "latency_ms": 720, "created_at": "2027-05-17T13:00:06Z" } ] } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listInvocations_Pipelines", "resource_uri": "yf://agents/pipelines", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/pipelines/9d3b1a2c-5e6f-4d7a-8b9c-0d1e2f3a4b5c/invocations?parse_ok=false&limit=20\"" } ], "x-related": [ { "operationId": "getInvocationPrompt_Pipelines" }, { "operationId": "getInvocationResponse_Pipelines" }, { "operationId": "getPipelineRun_Pipelines" }, { "url": "guides/pipelines-and-kgs.md", "description": "Pipelines and KGs guide" } ] } }, "/pipelines/{run_id}/invocations/{invocation_id}/prompt": { "get": { "operationId": "getInvocationPrompt_Pipelines", "x-method": "GET", "x-path": "/pipelines/{run_id}/invocations/{invocation_id}/prompt", "x-handler": "handlers::agent_registry::get_invocation_prompt", "tags": [ "Pipelines" ], "summary": "Fetch the full prompt text for a single agent invocation", "description": "Requires a matching invocation and run, a visible agent, and access to all run resources and the invocation KG.\nReturn the raw prompt text that was sent to the LLM for the named\ninvocation. Useful for debugging — see exactly what context the agent\nwas given (system prompt, memory prompt, KG context, message history,\ncurrent user turn). The response is `text/plain`. Auth: bearer JWT.\nIdempotent. Returns 404 if no invocation row exists for the\n`(run_id, invocation_id)` pair.\n", "parameters": [ { "name": "run_id", "in": "path", "required": true, "description": "Pipeline run id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "invocation_id", "in": "path", "required": true, "description": "Invocation id (UUID) from `GET /pipelines/{run_id}/invocations`.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Raw prompt text (UTF-8). Can be very long.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getInvocationPrompt_Pipelines", "resource_uri": "yf://agents/pipelines", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/pipelines/9d3b1a2c-5e6f-4d7a-8b9c-0d1e2f3a4b5c/invocations/11111111-aaaa-bbbb-cccc-222222222222/prompt" } ], "x-related": [ { "operationId": "listInvocations_Pipelines" }, { "operationId": "getInvocationResponse_Pipelines" }, { "url": "guides/pipelines-and-kgs.md", "description": "Pipelines and KGs guide" } ] } }, "/pipelines/{run_id}/invocations/{invocation_id}/response": { "get": { "operationId": "getInvocationResponse_Pipelines", "x-method": "GET", "x-path": "/pipelines/{run_id}/invocations/{invocation_id}/response", "x-handler": "handlers::agent_registry::get_invocation_response", "tags": [ "Pipelines" ], "summary": "Fetch the raw LLM response text for a single agent invocation", "description": "Requires a matching invocation and run, a visible agent, and access to all run resources and the invocation KG.\nReturn the raw response text the LLM produced for the named invocation,\nbefore parsing into tool calls or prose. Useful for debugging parse\nfailures (combine with `parse_ok=false` on the invocation list) — you\ncan see exactly what the agent said and why the parser rejected it.\nThe response is `text/plain`. Auth: bearer JWT. Idempotent. Returns\n404 if no invocation row exists for the `(run_id, invocation_id)` pair.\n", "parameters": [ { "name": "run_id", "in": "path", "required": true, "description": "Pipeline run id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "invocation_id", "in": "path", "required": true, "description": "Invocation id (UUID) from `GET /pipelines/{run_id}/invocations`.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Raw response text (UTF-8). May include JSON tool-call blocks intermixed with prose.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getInvocationResponse_Pipelines", "resource_uri": "yf://agents/pipelines", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/pipelines/9d3b1a2c-5e6f-4d7a-8b9c-0d1e2f3a4b5c/invocations/11111111-aaaa-bbbb-cccc-222222222222/response" } ], "x-related": [ { "operationId": "listInvocations_Pipelines" }, { "operationId": "getInvocationPrompt_Pipelines" }, { "url": "guides/pipelines-and-kgs.md", "description": "Pipelines and KGs guide" } ] } }, "/pipelines/{run_id}/resume": { "post": { "operationId": "resumePipeline_Pipelines", "x-method": "POST", "x-path": "/pipelines/{run_id}/resume", "x-handler": "handlers::pipelines::resume_pipeline", "tags": [ "Pipelines" ], "summary": "Resume a paused pipeline or recover a run with an expired execution lease", "description": "Resume a `paused` pipeline at the next step after its checkpoint. The\nhandler reconstructs the original `Pipeline` from the spec saved at start\ntime, then atomically claims a unique Postgres execution lease before\nspawning a fresh executor task. Also accepts `failed` runs marked by the\nstartup reaper with `pipeline execution lease expired`, and `running` runs\nwhose persisted lease is expired. Active leases remain owned even when the\nowner is another service replica. Paused checkpoints resume at saved index\nN+1; lease-expiry recovery repeats the recorded in-flight index N. Any other\nstate returns 409. Auth: bearer JWT plus direct Member-or-higher\n`ParticipateSession` authority in the run's working group; economy-derived\nvisibility alone is read-only. Concurrent resume calls are fenced by\nthe atomic claim: one may succeed and all others return 409. No request body\nrequired.\nThe response shape matches `POST /pipelines/run`.\n", "parameters": [ { "name": "run_id", "in": "path", "required": true, "description": "Pipeline run id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Resumed. Returns `run_id` (same as input) and `kg_id`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "run_id", "kg_id" ], "properties": { "run_id": { "type": "string", "format": "uuid" }, "kg_id": { "type": "string", "format": "uuid" }, "thread_id": { "type": [ "string", "null" ] } } }, "examples": { "resumed": { "summary": "Resumed", "value": { "run_id": "9d3b1a2c-5e6f-4d7a-8b9c-0d1e2f3a4b5c", "kg_id": "4f1c7a8e-2b6f-4f01-9a2d-3a5d2c1e7b81", "thread_id": "22222222-3333-4444-5555-666666666666" } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "409": { "description": "Conflicting state (e.g. step already completed, intent already cancelled, duplicate idempotency key with different body).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_resumePipeline_Pipelines", "resource_uri": "yf://agents/pipelines", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/pipelines/9d3b1a2c-5e6f-4d7a-8b9c-0d1e2f3a4b5c/resume" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx, os\nrun_id = \"9d3b1a2c-5e6f-4d7a-8b9c-0d1e2f3a4b5c\"\nr = httpx.post(\n f\"https://agents.yieldfabric.com/pipelines/{run_id}/resume\",\n headers={\"Authorization\": f\"Bearer {os.environ['JWT']}\"},\n)\nr.raise_for_status()\nprint(r.json())\n" } ], "x-related": [ { "operationId": "getPipelineRun_Pipelines" }, { "operationId": "pipelineEvents_Pipelines" }, { "operationId": "pipelineInput_Pipelines" }, { "operationId": "rewindPipeline_Pipelines" }, { "url": "guides/pipelines-and-kgs.md", "description": "Pipelines and KGs guide" } ] } }, "/pipelines/{run_id}/rewind": { "post": { "operationId": "rewindPipeline_Pipelines", "x-method": "POST", "x-path": "/pipelines/{run_id}/rewind", "x-handler": "handlers::pipelines::rewind_pipeline", "tags": [ "Pipelines" ], "summary": "Branch a new run from an earlier named step of an existing pipeline", "description": "Rewind to a named earlier step in a pipeline, creating a fresh KG and a\nnew `pipeline_runs` row whose `parent_run_id` points at the original.\nThe original run is marked `rewound` and its `paused_reason` records the\nbranch point. The handler rebuilds the pipeline from the saved spec,\nvalidates `to_step_id` against the actual step list, and spawns a new\nexecutor task at the target index. A new KG is allocated so any state\nthe original wrote past the rewind point is not poisoned. Auth: bearer\nJWT plus direct Member-or-higher `ParticipateSession` authority in the\nrun's working group. Not idempotent — each call creates a new branch. Common\n`to_step_id` values: `\"vocab_review\"`, `\"team_formation\"`,\n`\"vocab_discovery\"`, `\"file_extraction\"` (you get these names from\n`pipeline_step_started` SSE events).\n", "parameters": [ { "name": "run_id", "in": "path", "required": true, "description": "Pipeline run id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "to_step_id" ], "properties": { "to_step_id": { "type": "string", "description": "Named step to rewind to. Common values: `vocab_review`,\n`team_formation`, `vocab_discovery`, `file_extraction`.\n" } } }, "examples": { "to-vocab-review": { "summary": "Rewind to the vocab review checkpoint", "value": { "to_step_id": "vocab_review" } }, "to-team-formation": { "summary": "Rewind to team formation", "value": { "to_step_id": "team_formation" } } } } } }, "responses": { "200": { "description": "New branched run created. Pairs the original and new run ids.", "content": { "application/json": { "schema": { "type": "object", "required": [ "original_run_id", "new_run_id", "new_kg_id", "rewound_to_step", "rewound_to_index" ], "properties": { "original_run_id": { "type": "string", "format": "uuid" }, "new_run_id": { "type": "string", "format": "uuid" }, "new_kg_id": { "type": "string", "format": "uuid" }, "rewound_to_step": { "type": "string" }, "rewound_to_index": { "type": "integer", "minimum": 0 } } }, "examples": { "rewound": { "summary": "Rewound + new run", "value": { "original_run_id": "9d3b1a2c-5e6f-4d7a-8b9c-0d1e2f3a4b5c", "new_run_id": "7b8c9d0e-1f2a-3b4c-5d6e-7f8a9b0c1d2e", "new_kg_id": "5c2d8b9f-3e7f-4f02-9a3e-4a6e3d2f8c92", "rewound_to_step": "vocab_review", "rewound_to_index": 3 } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_rewindPipeline_Pipelines", "resource_uri": "yf://agents/pipelines", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" \\\n -d '{\"to_step_id\":\"vocab_review\"}' \\\n https://agents.yieldfabric.com/pipelines/9d3b1a2c-5e6f-4d7a-8b9c-0d1e2f3a4b5c/rewind\n" } ], "x-related": [ { "operationId": "startPipeline_Pipelines" }, { "operationId": "getPipelineRun_Pipelines" }, { "operationId": "resumePipeline_Pipelines" }, { "operationId": "cancelPipeline_Pipelines" }, { "url": "guides/pipelines-and-kgs.md", "description": "Pipelines and KGs guide" } ] } }, "/presence/disconnect": { "post": { "operationId": "presenceDisconnect_Presence", "x-method": "POST", "x-path": "/presence/disconnect", "x-handler": "wg::presence_disconnect", "tags": [ "Presence" ], "summary": "Mark the bearer offline (keepalive-friendly)", "description": "Removes the bearer's `user_presence` row, then broadcasts an `offline`\n`PresenceUpdate` to every room it held. The body's `entity_id` is\nignored in favour of the bearer. The body is small and the handler is\nfire-and-forget, so a browser can call it on tab close with a\n`keepalive` fetch — not `navigator.sendBeacon`, which carries no\n`Authorization` header and is always credentialed, so it cannot pass\nthis route's bearer check nor a wildcard CORS origin. Auth: bearer\nJWT.\n", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "entity_id" ], "properties": { "entity_id": { "type": "string", "description": "Accepted for wire compatibility and ignored; the bearer is the entity." } } }, "examples": { "leave": { "summary": "Mark Alice offline", "value": { "entity_id": "usr_alice" } } } } } }, "responses": { "200": { "description": "Disconnected.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "offline" ] } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_presenceDisconnect_Presence", "resource_uri": "yf://agents/presence", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"entity_id\":\"usr_alice\"}' \\\n https://agents.yieldfabric.com/presence/disconnect\n" } ], "x-related": [ { "operationId": "presenceJoin_Presence", "relation": "sibling" }, { "operationId": "presenceHeartbeat_Presence", "relation": "sibling" }, { "guide": "streaming", "relation": "concept" } ] } }, "/presence/heartbeat": { "post": { "operationId": "presenceHeartbeat_Presence", "x-method": "POST", "x-path": "/presence/heartbeat", "x-handler": "wg::presence_heartbeat", "tags": [ "Presence" ], "summary": "Refresh presence TTL and update visibility mode", "description": "Bumps `last_heartbeat` for the bearer and re-sets `visibility_mode`.\nThe row's `group_ids` is re-derived from `working_group_members` on\nevery heartbeat (see `presenceJoin_Presence`); the body's `group_ids`,\nwhen present, only refreshes the auth-group hints, and when absent the\nstored hints stand. When the visibility mode changes versus the prior\nrow, a `PresenceUpdate` is broadcast into every room the bearer is a\nmember of. The body's `entity_id` is ignored in favour of the bearer.\nClients should call this on a short interval (around once per 30s) —\nthe background sweep expires any row older than 5 min. If membership\ncannot be read the heartbeat still counts and nothing is rescoped or\nannounced. Auth: bearer JWT.\n", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "entity_id" ], "properties": { "entity_id": { "type": "string", "description": "Accepted for wire compatibility and ignored; the bearer is the entity." }, "group_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Optional. Refreshes the auth-group hints only; absent, the stored hints stand. Rooms are re-derived from membership on every heartbeat." }, "visibility_mode": { "type": "string", "default": "online", "enum": [ "online", "away", "busy", "invisible" ] } } }, "examples": { "keepalive": { "summary": "Plain heartbeat — keep current groups", "value": { "entity_id": "usr_alice" } }, "change-mode": { "summary": "Switch to do-not-disturb", "value": { "entity_id": "usr_alice", "visibility_mode": "dnd" } } } } } }, "responses": { "200": { "description": "Heartbeat accepted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_presenceHeartbeat_Presence", "resource_uri": "yf://agents/presence", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"entity_id\":\"usr_alice\"}' \\\n https://agents.yieldfabric.com/presence/heartbeat\n" } ], "x-related": [ { "operationId": "presenceJoin_Presence", "relation": "sibling" }, { "operationId": "presenceDisconnect_Presence", "relation": "sibling" }, { "guide": "streaming", "relation": "concept" } ] } }, "/presence/join": { "post": { "operationId": "presenceJoin_Presence", "x-method": "POST", "x-path": "/presence/join", "x-handler": "wg::presence_join", "tags": [ "Presence" ], "summary": "Announce that an entity is online in a set of groups", "description": "Upserts the bearer's `user_presence` row, setting `visibility_mode`\n(`online` by default; `away`, `dnd`, `invisible` also accepted) and\nstamping `last_heartbeat`, then broadcasts a `PresenceUpdate` into\nevery working group the bearer is an active member of (invisible mode\nis mirrored as `offline`).\n\nThe server decides where you are present; the client decides what it\nwants to see. The row's `group_ids` is derived on every call from\n`working_group_members` — the body's `group_ids` never adds a room —\nand the request's ids only select which rosters come back: a working\ngroup is answered only if the bearer is a member of it, and an id that\nis not a working group (an auth-service group) is kept as a hint so\nmembers of the same auth group can see each other in bulk reads, but\nis never broadcast into. The body's `entity_id` is accepted for wire\ncompatibility and ignored: presence is written for whoever the bearer\nis, and a mismatch is logged. Returns a `PresenceBulk` snapshot keyed\nby the requested group ids that were answered. Fails 503, storing and\nannouncing nothing, if membership cannot be read. Auth: bearer JWT.\n", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "entity_id", "group_ids" ], "properties": { "entity_id": { "type": "string", "description": "Accepted for wire compatibility and ignored; the bearer is the entity." }, "group_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Rosters to return. Never adds a room — presence rooms come from membership. A working group is answered only if the bearer is a member; a non-working-group id (an auth-service group) is kept as a bulk-read hint and never broadcast into." }, "visibility_mode": { "type": "string", "default": "online", "enum": [ "online", "away", "busy", "invisible" ] } } }, "examples": { "online": { "summary": "Join three groups as online", "value": { "entity_id": "usr_alice", "group_ids": [ "8c7e1a32-1111-4e44-b9d1-aaaaaaaaaaaa" ], "visibility_mode": "online" } } } } } }, "responses": { "200": { "description": "Joined; per-group presence returned.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "presence" ], "properties": { "status": { "type": "string", "enum": [ "joined" ] }, "presence": { "type": "object", "description": "Map keyed by working-group UUID → list of visible members in that group.", "additionalProperties": { "type": "array", "items": { "type": "object", "required": [ "entity_id", "status", "last_seen_at" ], "properties": { "entity_id": { "type": "string" }, "status": { "type": "string", "enum": [ "online", "away", "busy", "invisible", "offline" ] }, "last_seen_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_presenceJoin_Presence", "resource_uri": "yf://agents/presence", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"entity_id\":\"usr_alice\",\"group_ids\":[\"\"]}' \\\n https://agents.yieldfabric.com/presence/join\n" } ], "x-related": [ { "operationId": "presenceHeartbeat_Presence", "relation": "sibling" }, { "operationId": "presenceDisconnect_Presence", "relation": "sibling" }, { "guide": "streaming", "relation": "concept" } ] } }, "/skills": { "get": { "operationId": "listSkills_ToolsSkills", "x-method": "GET", "x-path": "/skills", "x-handler": "handlers::agent_registry::list_skills", "tags": [ "Tools & Skills" ], "summary": "List all suggested skill bundles the framework ships.", "description": "Returns the inline skill catalogue — the curated bundles of\nprompt fragments, tool grants, and behavioural defaults agents can\nopt into via their `AgentSpec`. Used by the agent studio to populate\nthe skill picker. Read-only, side-effect free, and not bound to any\nscope. Auth: bearer JWT.\n", "responses": { "200": { "description": "Catalog of inline skills.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "name", "prompt_addendum" ], "properties": { "name": { "type": "string" }, "prompt_addendum": { "type": "string" }, "tool_grants": { "description": "Arbitrary JSON value." } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listSkills_ToolsSkills", "resource_uri": "yf://agents/skills", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/skills\"" } ], "x-related": [ { "operationId": "listTools_ToolsSkills", "relation": "sibling" }, { "guide": "agents-studio", "relation": "concept" } ] } }, "/tools": { "get": { "operationId": "listTools_ToolsSkills", "x-method": "GET", "x-path": "/tools", "x-handler": "handlers::agent_registry::list_tools", "tags": [ "Tools & Skills" ], "summary": "List every tool the framework can invoke on behalf of an agent.", "description": "Returns the framework catalog (`ToolDef`) plus canonical native knowledge\ntools, deduplicated by name. Entries carry kind, description and params_hint;\nnative tools also carry input_schema and their supported surfaces.\nDrives the agent-studio's tool grants UI and is the source of truth\nfor available tool ids; actual invocations bind their supported subset and\nenforce the selected agent's grants. Read-only, side-\neffect free, and not bound to any scope. Auth: bearer JWT.\n", "responses": { "200": { "description": "Tool catalogue.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "A tool definition; availability depends on the invocation surface and its grants.", "required": [ "name", "kind", "description", "params_hint" ], "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "read", "mutation", "side_effect", "control", "spawn", "memory", "propose" ] }, "description": { "type": "string" }, "params_hint": { "type": "string", "description": "Human-readable parameter shape." }, "input_schema": { "description": "Arbitrary JSON value." }, "surfaces": { "type": "array", "items": { "type": "string" }, "description": "Native tool bindings identify the surfaces where they are offered." } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listTools_ToolsSkills", "resource_uri": "yf://agents/tools", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/tools\"" } ], "x-related": [ { "operationId": "listSkills_ToolsSkills", "relation": "sibling" }, { "guide": "agents-studio", "relation": "concept" } ] } }, "/users/me/presence/visibility": { "get": { "operationId": "getVisibilityPreference_Misc", "x-method": "GET", "x-path": "/users/me/presence/visibility", "x-handler": "wg::get_visibility_preference", "tags": [ "Presence" ], "summary": "Get the caller's persisted presence visibility", "description": "Returns the visibility mode saved independently of the caller's ephemeral\n`user_presence` row. Users without a saved preference receive `online`.\nAuth: bearer JWT.\n", "responses": { "200": { "description": "Persisted visibility preference, or the `online` default.", "content": { "application/json": { "schema": { "type": "object", "required": [ "visibility_mode" ], "properties": { "visibility_mode": { "type": "string", "enum": [ "online", "away", "dnd", "invisible" ] } } } } } }, "401": { "description": "Missing or invalid bearer credential." }, "500": { "description": "Preference lookup failed.", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getVisibilityPreference_Misc", "resource_uri": "yf://agents/presence", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/users/me/presence/visibility" } ], "x-related": [ { "operationId": "patchVisibilityPreference_Misc", "relation": "sibling" } ] }, "patch": { "operationId": "patchVisibilityPreference_Misc", "x-method": "PATCH", "x-path": "/users/me/presence/visibility", "x-handler": "wg::patch_visibility_preference", "tags": [ "Presence" ], "summary": "Persist the caller's presence visibility", "description": "Upserts the caller's preferred visibility mode so it survives disconnects\nand future sessions. This does not create or refresh the short-lived live\npresence row. Auth: bearer JWT.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "visibility_mode" ], "properties": { "visibility_mode": { "type": "string", "enum": [ "online", "away", "dnd", "invisible" ] } } }, "examples": { "do-not-disturb": { "value": { "visibility_mode": "dnd" } } } } } }, "responses": { "200": { "description": "Saved preference.", "content": { "application/json": { "schema": { "type": "object", "required": [ "visibility_mode" ], "properties": { "visibility_mode": { "type": "string", "enum": [ "online", "away", "dnd", "invisible" ] } } } } } }, "400": { "description": "Unknown visibility mode or malformed JSON.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing or invalid bearer credential." }, "500": { "description": "Preference persistence failed.", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_patchVisibilityPreference_Misc", "resource_uri": "yf://agents/presence", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PATCH https://agents.yieldfabric.com/users/me/presence/visibility \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"visibility_mode\":\"dnd\"}'\n" } ], "x-related": [ { "operationId": "getVisibilityPreference_Misc", "relation": "sibling" } ] } }, "/v1/chat/completions": { "post": { "operationId": "chatCompletions_Openai", "x-method": "POST", "x-path": "/v1/chat/completions", "x-handler": "handlers::openai_compat::chat_completions", "tags": [ "OpenAI Compatibility" ], "summary": "OpenAI-compatible chat completions (streaming and non-streaming).", "description": "Point any OpenAI SDK at this service (`base_url = https://agents.…`,\n`api_key = `) and call chat completions\nagainst the deployment's model catalog (`default`, `mini`, or a\ndeployment name — see `GET /v1/models`).\n\nMaps onto the same model registry, provider, and metering the native\n`POST /chat` uses (feature label `compat_chat`). `stream: true`\nreturns OpenAI-format SSE chunks ending in `data: [DONE]`.\n`response_format: json_schema` maps to the provider's strict\nstructured-output path.\n\n**Tool calling**: client `tools` are forwarded; model calls return\nas `tool_calls` with `finish_reason: \"tool_calls\"`, and `assistant`\ntool-call turns + `tool`-role results round-trip. Tool-involving\nrequests with `stream: true` run buffered upstream and are\nre-emitted as chunk frames.\n\n**Durable client tools**: each tool_calls response includes an opaque\n`yf.continuation_id`. Echo it with one result for every pending client call;\nretain the model, catalog, instructions, token cap, credentials and scope.\nNative reasoning state stays server-side. Handles expire after 30 minutes;\nan indexed maintenance sweep runs every 30 seconds and deletes expired\nprivate payloads in bounded batches, safely across replicas.\nIdentical retries return the cached response without another dispatch;\nconcurrent claims return 409 `continuation_busy`, changed results return\n409 `continuation_conflict`, changed binding returns 409\n`continuation_mismatch`, and expired/unknown handles return 410\n`continuation_expired`. Retry a busy call unchanged; start a new question\nfor other continuation errors. Client turns share a 16-round cumulative\nbudget and token ceilings. Mixed read-only builtins preserve the complete\nnative tool group. `start_reasoning` with client tools is rejected before\ndispatch; execute it as a separate request.\n\n**Durable conversation**: optional `yf.thread_id` plus stable `yf.turn_id`\nauthorize PostMessages, derive the working group and persist one human and\none assistant message per question. The assistant is updated through tool\nhandoffs and completion; older retries cannot overwrite a later answer.\nWork continues after HTTP disconnect. The durable human message prevents\nan expired or deleted private initial claim from restarting an old turn UUID;\nsuch retries return 410 and require a fresh turn. `yf.client_state` carries\nbounded, inert display/rounds/surfaces/pending_preview metadata. The human\nmessage persists only the display text; other UI state belongs to the reply. Native reasoning is\nnever stored in public message references. Reloaded pending proposals need\nfresh review and are never automatically executed.\n\n`yf.completion` distinguishes answers, tool handoffs, output limits and\nbudget stops on both JSON and terminal SSE frames. Premature provider EOF\nis an error, never a successful finish. `reasoning_effort` selects native\nlow/medium/high/max effort on compatible models (max maps to high).\n\n**YF substrate (`yf` vendor extension, via `extra_body`)**:\n`working_group_id` plus additive `kg_id` / `kg_ids` and source-document\ninclude/exclude filters auto-ground the completion in the caller's\nknowledge substrate (citations in the response's `yf.sources`).\nRequested KGs are deduplicated and must belong to the authenticated\nworking group. Document predicates are applied before ranking and remain\neffective across merged provenance; exclusion wins. Explicit empty KG or\ndocument-include scopes match nothing. `builtin_tools:\n[\"rag_search\", \"start_reasoning\"]`\nregisters server-executed tools — model-directed retrieval and\nasync multi-agent reasoning runs — executed in a bounded loop (max\n4 rounds) and reported in `yf.tool_activity`, never as client\ntool_calls. Working-group membership is enforced (403).\n\nExplicitly rejected (400, OpenAI error envelope): legacy\n`functions`, `n > 1`, `response_format: json_object`, and\n`response_format` combined with `stream` or tools. Tuning\nparameters with no provider lever (`top_p`, penalties, `seed`,\n`stop`, `logit_bias`) are accepted and ignored. Honoured:\n`temperature`, `max_completion_tokens` / `max_tokens` (clamped to\n32000), `tools`, `tool_choice`.\n\nAuth: bearer JWT or `yf_api_…` API key.\n", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "messages" ], "description": "Supported subset of the OpenAI Chat Completions request, plus the\n`yf` vendor extension. Mirrors `ChatCompletionsRequest` in\nsrc/service/handlers/openai_compat.rs.\n", "properties": { "model": { "type": "string", "description": "Registry id (`default`, `mini`) or deployment name, case-insensitively. Catalog at `GET /v1/models` / `GET /api/models`." }, "messages": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "system", "developer", "user", "assistant", "tool" ] }, "content": { "description": "A string, or an array of `{type: \"text\", text}` parts. May be null on assistant messages that carry `tool_calls`.", "oneOf": [ { "type": "string" }, { "type": "null" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } } } } ] }, "tool_calls": { "type": "array", "description": "On assistant messages — prior model tool calls being replayed.", "items": { "type": "object", "required": [ "id", "function" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "arguments": { "type": "string", "description": "JSON-encoded arguments." } } } } } }, "tool_call_id": { "type": "string", "description": "Required on `tool`-role messages — the call being answered." } } } }, "stream": { "type": "boolean", "default": false, "description": "True token streaming on tool-free requests. Requests involving tools run buffered upstream and are re-emitted as OpenAI chunk frames (single tool_calls/content delta)." }, "reasoning_effort": { "type": [ "string", "null" ], "enum": [ "low", "medium", "high", "max", null ], "description": "Native reasoning effort for compatible reasoning models; max maps to high. Known Claude 4.5 uses a bounded manual budget (cap must exceed 1024; tool_choice auto/none only), known 4.6+ adaptive models use native effort. Omitted or unknown model aliases retain provider defaults." }, "temperature": { "type": [ "number", "null" ], "description": "Forwarded verbatim; models that reject it surface the upstream error." }, "max_completion_tokens": { "type": [ "integer", "null" ], "description": "Output-token cap (server-clamped to 32000). Takes precedence over `max_tokens`." }, "max_tokens": { "type": [ "integer", "null" ], "description": "Legacy alias for `max_completion_tokens`." }, "tools": { "type": "array", "description": "Client function tools, forwarded to the model. Calls come back as `tool_calls` with `finish_reason: \"tool_calls\"`; answer them with `tool`-role messages. `type` must be `function`.", "items": { "type": "object", "required": [ "type", "function" ], "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "JSON Schema for the arguments object." } } } } } }, "tool_choice": { "description": "`auto` (default) / `none` / `required` / `{type: \"function\", function: {name}}`. Applies to the first model round; server-side builtin rounds use `auto`.", "oneOf": [ { "type": "string", "enum": [ "auto", "none", "required" ] }, { "type": "object" } ] }, "response_format": { "type": [ "object", "null" ], "description": "`{type: \"json_schema\", json_schema: {name, schema}}` maps to the provider's strict structured-output path. `json_object` is rejected with a 400 (use `json_schema`). Cannot be combined with `stream: true` or with tools." }, "n": { "type": [ "integer", "null" ], "description": "Must be 1 (or omitted). `n > 1` is rejected." }, "yf": { "type": [ "object", "null" ], "description": "YieldFabric vendor extension (OpenAI SDKs pass it via `extra_body`). Grounds the completion in the caller's knowledge substrate and/or registers server-executed builtin tools.", "properties": { "continuation_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Opaque handle from the preceding tool_calls response. Echo with the exact pending tool result batch, unchanged model, tool catalog, instructions, token cap, credentials and scope. Expires after 30 minutes. Never contains public native reasoning." }, "thread_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Persist the turn in this authorized discussion. Requires PostMessages permission and turn_id; group is derived and checked. Canonical thread history is loaded server-side. Cannot be used with json_schema." }, "turn_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Stable UUID for this user question, retained across retries and tool rounds. Required with thread_id; creates one human and one assistant message, updating the assistant through handoffs." }, "client_state": { "type": [ "object", "null" ], "description": "Optional inert UI metadata, at most 64000 bytes. Only display, rounds, surfaces and pending_preview are persisted under message references.console. This is never tool authority; restored proposals require fresh review." }, "working_group_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Ground in this working group's substrate (documents + KGs). Membership is enforced (403 otherwise). Unless `rag_search` is registered, retrieval runs automatically against the last user message and citations return in the response's `yf.sources`." }, "kg_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Narrow grounding/search to one knowledge graph (e.g. a reasoning run's output). Requires `working_group_id`." }, "kg_ids": { "type": [ "array", "null" ], "maxItems": 1000, "uniqueItems": true, "items": { "type": "string", "format": "uuid" }, "description": "Additive multi-KG scope, unioned with `kg_id`. Every KG must belong to `working_group_id`. An explicit empty array (with no `kg_id`) matches nothing." }, "include_document_ids": { "type": [ "array", "null" ], "maxItems": 1000, "uniqueItems": true, "items": { "type": "string", "format": "uuid" }, "description": "Immutable source-document allow-list. Omitted means no allow-list; an explicit empty array matches nothing." }, "exclude_document_ids": { "type": [ "array", "null" ], "maxItems": 1000, "uniqueItems": true, "items": { "type": "string", "format": "uuid" }, "description": "Immutable source-document deny-list. Exclusion wins over an overlapping include. Provenance is projected before ranking." }, "builtin_tools": { "type": "array", "items": { "type": "string", "enum": [ "rag_search", "start_reasoning", "yf_rag_search", "yf_start_reasoning" ] }, "description": "Server-executed tools, run in a bounded loop (max 4 rounds) and never surfaced as client tool_calls. `rag_search` = model-directed substrate retrieval (requires working_group_id; supersedes auto-grounding). `start_reasoning` = kick off an async multi-agent reasoning run; returns run_id/kg_id/thread_id to follow. Repeating the same operation within a durable thread turn reuses the original run even if a later provider call fails. Cannot be combined with client tools. A fresh user turn may intentionally start a new run." } } } } }, "examples": { "minimal": { "summary": "Non-streaming completion on the mini model", "value": { "model": "mini", "messages": [ { "role": "user", "content": "Summarise these terms in one line." } ] } }, "grounded-with-builtins": { "summary": "Substrate-grounded with server-executed search", "value": { "model": "default", "messages": [ { "role": "user", "content": "What payment schedule did we agree with Acme?" } ], "yf": { "working_group_id": "11111111-1111-1111-1111-111111111111", "builtin_tools": [ "rag_search" ] } } }, "multi-kg-document-grounding": { "summary": "Auto-ground over selected KGs and source documents", "value": { "model": "default", "messages": [ { "role": "user", "content": "Summarise the R&D eligibility advice." } ], "yf": { "working_group_id": "11111111-1111-1111-1111-111111111111", "kg_id": "22222222-2222-2222-2222-222222222222", "kg_ids": [ "33333333-3333-3333-3333-333333333333" ], "include_document_ids": [ "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaa1", "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaa2" ], "exclude_document_ids": [ "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaa1" ] } } }, "client-tools": { "summary": "Standard client tool calling", "value": { "model": "default", "messages": [ { "role": "user", "content": "What's the weather in Oslo?" } ], "tools": [ { "type": "function", "function": { "name": "get_weather", "description": "Current weather for a city.", "parameters": { "type": "object", "properties": { "city": { "type": "string" } }, "required": [ "city" ] } } } ] } } } } } }, "responses": { "200": { "headers": { "x-yf-usage-request-id": { "description": "Server-generated request UUID shared by token metering and billing records. It carries attribution only, not authority.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Chat completion. SSE chunk stream when `stream: true`, otherwise a single `chat.completion` object.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "object", "created", "model", "choices", "usage" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "created": { "type": "integer" }, "model": { "type": "string", "description": "Upstream deployment name." }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "message": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "assistant" ] }, "content": { "type": [ "string", "null" ] }, "tool_calls": { "type": "array", "description": "Present when the model requests client tool calls.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } } } } } }, "finish_reason": { "type": "string", "enum": [ "stop", "tool_calls", "length" ] } } } }, "usage": { "type": "object", "description": "Summed across server-side builtin rounds when the yf tool loop ran.", "properties": { "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } }, "yf": { "type": [ "object", "null" ], "description": "Present when the `yf` extension did work. On streamed responses it rides the finish chunk.", "properties": { "continuation_id": { "type": "string", "format": "uuid", "description": "Present only for pending client tool calls. Native provider transcript remains private server-side; repeated identical results return the cached response." }, "stop_reason": { "type": "string", "enum": [ "answered", "awaiting_tool_results", "rounds_exhausted", "budget_exhausted", "output_limit", "empty", "failed" ] }, "truncated": { "type": "boolean" }, "rounds_used": { "type": "integer" }, "completion": { "type": "object", "required": [ "stop_reason", "truncated" ], "description": "The actual execution boundary, persisted with the assistant message.\nA truncated result needs follow-up; it is not a complete answer. Usage\naccumulates across server and durable browser tool rounds. Native provider\nreasoning state is never included in this public object.\n", "properties": { "stop_reason": { "type": "string", "enum": [ "answered", "awaiting_tool_results", "rounds_exhausted", "budget_exhausted", "output_limit", "empty", "failed", "interrupted" ] }, "truncated": { "type": "boolean" }, "rounds_used": { "type": "integer", "minimum": 0 }, "prompt_tokens": { "type": "integer", "minimum": 0 }, "completion_tokens": { "type": "integer", "minimum": 0 }, "reasoning_tokens": { "type": "integer", "minimum": 0, "description": "Subset of completion_tokens, never additional billed tokens." }, "elided_groups": { "type": "integer", "minimum": 0 }, "reused_calls": { "type": "integer", "minimum": 0 } } }, "grounded": { "type": "boolean" }, "sources": { "type": "array", "description": "Source references from grounding / rag_search (same shape as the native chat SSE `sources`).", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Document id for chunk evidence or node key for graph evidence." }, "label": { "type": "string" }, "citation_id": { "type": "integer", "minimum": 1 }, "document_id": { "type": "string", "format": "uuid" }, "kg_id": { "type": "string", "format": "uuid" }, "node_key": { "type": "string" }, "type": { "type": "string" }, "typeColor": { "type": "string" }, "description": { "type": "string" } } } }, "tool_activity": { "type": "array", "description": "Server-executed builtin calls — `{tool, arguments, result}` (or deferred-round markers).", "items": { "type": "object" } } } } } } }, "text/event-stream": { "schema": { "type": "object", "description": "Each SSE event has an `event` name (the wire-level `event:` line) and a\n`data` JSON payload (the wire-level `data:` line, JSON-decoded). The exact\nschemas for each event variant are documented in the operation's\n`x-event-types` extension.\n", "required": [ "event", "data" ], "properties": { "event": { "type": "string", "description": "Event name from the operation's `x-event-types` enumeration." }, "data": { "description": "JSON payload. Shape depends on `event` — see `x-event-types`." }, "id": { "type": [ "string", "null" ], "description": "Optional SSE event id (used for resume cursors)." } } } } } }, "400": { "description": "Unsupported/invalid parameter, in the OpenAI error envelope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "description": "OpenAI-style error envelope used by every /v1 response ≥ 400 (including the middleware's 401s).", "properties": { "error": { "type": "object", "required": [ "message", "type" ], "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "billing_error", "api_error" ] }, "param": { "type": [ "string", "null" ] }, "code": { "type": [ "string", "null" ], "description": "Stable billing recovery reason on a 402 (`card_required`, `credit_plan_required`, `credit_exhausted`, or `billing_paused`); null for non-billing errors." } } } } } } } }, "401": { "description": "Missing/invalid credential, in the OpenAI error envelope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "description": "OpenAI-style error envelope used by every /v1 response ≥ 400 (including the middleware's 401s).", "properties": { "error": { "type": "object", "required": [ "message", "type" ], "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "billing_error", "api_error" ] }, "param": { "type": [ "string", "null" ] }, "code": { "type": [ "string", "null" ], "description": "Stable billing recovery reason on a 402 (`card_required`, `credit_plan_required`, `credit_exhausted`, or `billing_paused`); null for non-billing errors." } } } } } } } }, "402": { "description": "Paid access is gated. `error.code` is one of `card_required`, `credit_plan_required`, `credit_exhausted`, or `billing_paused`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "description": "OpenAI-style error envelope used by every /v1 response ≥ 400 (including the middleware's 401s).", "properties": { "error": { "type": "object", "required": [ "message", "type" ], "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "billing_error", "api_error" ] }, "param": { "type": [ "string", "null" ] }, "code": { "type": [ "string", "null" ], "description": "Stable billing recovery reason on a 402 (`card_required`, `credit_plan_required`, `credit_exhausted`, or `billing_paused`); null for non-billing errors." } } } } } } } }, "403": { "description": "Caller is not a member of the `yf.working_group_id` group.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "description": "OpenAI-style error envelope used by every /v1 response ≥ 400 (including the middleware's 401s).", "properties": { "error": { "type": "object", "required": [ "message", "type" ], "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "billing_error", "api_error" ] }, "param": { "type": [ "string", "null" ] }, "code": { "type": [ "string", "null" ], "description": "Stable billing recovery reason on a 402 (`card_required`, `credit_plan_required`, `credit_exhausted`, or `billing_paused`); null for non-billing errors." } } } } } } } }, "429": { "description": "Inference admission exceeded. The OpenAI error type is rate_limit_error and code is inference_limit.", "headers": { "Retry-After": { "description": "Suggested retry delay in seconds.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "description": "OpenAI-style error envelope used by every /v1 response ≥ 400 (including the middleware's 401s).", "properties": { "error": { "type": "object", "required": [ "message", "type" ], "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "billing_error", "api_error" ] }, "param": { "type": [ "string", "null" ] }, "code": { "type": [ "string", "null" ], "description": "Stable billing recovery reason on a 402 (`card_required`, `credit_plan_required`, `credit_exhausted`, or `billing_paused`); null for non-billing errors." } } } } } } } }, "502": { "description": "Upstream model failure, in the OpenAI error envelope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "description": "OpenAI-style error envelope used by every /v1 response ≥ 400 (including the middleware's 401s).", "properties": { "error": { "type": "object", "required": [ "message", "type" ], "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "billing_error", "api_error" ] }, "param": { "type": [ "string", "null" ] }, "code": { "type": [ "string", "null" ], "description": "Stable billing recovery reason on a 402 (`card_required`, `credit_plan_required`, `credit_exhausted`, or `billing_paused`); null for non-billing errors." } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_chatCompletions_Openai", "resource_uri": "yf://agents/openai", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST https://agents.yieldfabric.com/v1/chat/completions \\\n -H \"Authorization: Bearer $YF_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"model\":\"mini\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n" }, { "lang": "typescript", "label": "OpenAI SDK (TS)", "source": "import OpenAI from 'openai';\n\nconst client = new OpenAI({\n baseURL: 'https://agents.yieldfabric.com/v1',\n apiKey: process.env.YF_API_KEY, // yf_api_… key or a YF JWT\n});\n\n// Plain completion on the cheap model\nconst out = await client.chat.completions.create({\n model: 'mini',\n messages: [{ role: 'user', content: 'hello' }],\n});\nconsole.log(out.choices[0].message.content);\n\n// Grounded in your workspace, with model-directed search\nconst grounded = await client.chat.completions.create({\n model: 'default',\n messages: [{ role: 'user', content: 'What schedule did we agree with Acme?' }],\n // @ts-expect-error vendor extension\n yf: { working_group_id: WG_ID, builtin_tools: ['rag_search'] },\n});\n" }, { "lang": "python", "label": "OpenAI SDK (Python)", "source": "import os\nfrom openai import OpenAI\n\nclient = OpenAI(base_url=\"https://agents.yieldfabric.com/v1\",\n api_key=os.environ[\"YF_API_KEY\"]) # yf_api_… key or a YF JWT\n\n# Plain completion on the cheap model\nout = client.chat.completions.create(\n model=\"mini\",\n messages=[{\"role\": \"user\", \"content\": \"hello\"}],\n)\nprint(out.choices[0].message.content)\n\n# Grounded in your workspace, with model-directed search\ngrounded = client.chat.completions.create(\n model=\"default\",\n messages=[{\"role\": \"user\", \"content\": \"What schedule did we agree with Acme?\"}],\n extra_body={\"yf\": {\"working_group_id\": WG_ID,\n \"builtin_tools\": [\"rag_search\"]}},\n)\nprint(grounded.model_extra[\"yf\"][\"sources\"])\n" } ], "x-related": [ { "operationId": "listModelsV1_Openai", "relation": "sibling" }, { "operationId": "assistantChatHandler_Misc", "relation": "concept" } ] } }, "/v1/embeddings": { "post": { "operationId": "embeddings_Openai", "x-method": "POST", "x-path": "/v1/embeddings", "x-handler": "handlers::openai_compat::embeddings", "tags": [ "OpenAI Compatibility" ], "summary": "OpenAI-compatible embeddings (single or batch input).", "description": "Embeds one string or a batch (max 256 items, order-preserving,\nbounded upstream concurrency) into fixed 1,536-element vectors with the\ndeployment's embedding model. Azure defaults to `text-embedding-3-large`\nshortened through its `dimensions` parameter. `model` accepts the registry\nid `embedding`, the deployment name, or the deprecated\n`text-embedding-ada-002` compatibility alias.\n`encoding_format` must be `float` (or omitted). Usage token counts\nare reported as zeros — the embeddings upstream path doesn't return\nthem (calls are still metered internally under `compat_embed`).\n\nAuth: bearer JWT or `yf_api_…` API key.\n", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "input" ], "properties": { "model": { "type": "string", "description": "Embedding registry id (`embedding`) or deployment alias. The deprecated `text-embedding-ada-002` alias resolves to the current `text-embedding-3-large` deployment." }, "input": { "description": "One string or a batch (max 256 items).", "oneOf": [ { "type": "string" }, { "type": "array", "maxItems": 256, "items": { "type": "string" } } ] }, "encoding_format": { "type": [ "string", "null" ], "enum": [ "float", null ], "description": "Only `float` is supported; `base64` is rejected." } } } } } }, "responses": { "200": { "description": "Embedding vectors in input order.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "model", "usage" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "embedding" ] }, "index": { "type": "integer" }, "embedding": { "type": "array", "minItems": 1536, "maxItems": 1536, "items": { "type": "number" } } } } }, "model": { "type": "string" }, "usage": { "type": "object", "description": "Token counts are not returned by the embeddings upstream path; zeros are reported rather than fabricated numbers.", "properties": { "prompt_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } } } } } } }, "400": { "description": "Unsupported/invalid parameter, in the OpenAI error envelope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "description": "OpenAI-style error envelope used by every /v1 response ≥ 400 (including the middleware's 401s).", "properties": { "error": { "type": "object", "required": [ "message", "type" ], "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "billing_error", "api_error" ] }, "param": { "type": [ "string", "null" ] }, "code": { "type": [ "string", "null" ], "description": "Stable billing recovery reason on a 402 (`card_required`, `credit_plan_required`, `credit_exhausted`, or `billing_paused`); null for non-billing errors." } } } } } } } }, "401": { "description": "Missing/invalid credential, in the OpenAI error envelope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "description": "OpenAI-style error envelope used by every /v1 response ≥ 400 (including the middleware's 401s).", "properties": { "error": { "type": "object", "required": [ "message", "type" ], "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "billing_error", "api_error" ] }, "param": { "type": [ "string", "null" ] }, "code": { "type": [ "string", "null" ], "description": "Stable billing recovery reason on a 402 (`card_required`, `credit_plan_required`, `credit_exhausted`, or `billing_paused`); null for non-billing errors." } } } } } } } }, "402": { "description": "Paid access is gated. `error.code` is one of `card_required`, `credit_plan_required`, `credit_exhausted`, or `billing_paused`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "description": "OpenAI-style error envelope used by every /v1 response ≥ 400 (including the middleware's 401s).", "properties": { "error": { "type": "object", "required": [ "message", "type" ], "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "billing_error", "api_error" ] }, "param": { "type": [ "string", "null" ] }, "code": { "type": [ "string", "null" ], "description": "Stable billing recovery reason on a 402 (`card_required`, `credit_plan_required`, `credit_exhausted`, or `billing_paused`); null for non-billing errors." } } } } } } } }, "429": { "description": "Inference admission exceeded. The OpenAI error type is rate_limit_error and code is inference_limit.", "headers": { "Retry-After": { "description": "Suggested retry delay in seconds.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "description": "OpenAI-style error envelope used by every /v1 response ≥ 400 (including the middleware's 401s).", "properties": { "error": { "type": "object", "required": [ "message", "type" ], "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "billing_error", "api_error" ] }, "param": { "type": [ "string", "null" ] }, "code": { "type": [ "string", "null" ], "description": "Stable billing recovery reason on a 402 (`card_required`, `credit_plan_required`, `credit_exhausted`, or `billing_paused`); null for non-billing errors." } } } } } } } }, "502": { "description": "Upstream model failure, in the OpenAI error envelope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "description": "OpenAI-style error envelope used by every /v1 response ≥ 400 (including the middleware's 401s).", "properties": { "error": { "type": "object", "required": [ "message", "type" ], "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "billing_error", "api_error" ] }, "param": { "type": [ "string", "null" ] }, "code": { "type": [ "string", "null" ], "description": "Stable billing recovery reason on a 402 (`card_required`, `credit_plan_required`, `credit_exhausted`, or `billing_paused`); null for non-billing errors." } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_embeddings_Openai", "resource_uri": "yf://agents/openai", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST https://agents.yieldfabric.com/v1/embeddings \\\n -H \"Authorization: Bearer $YF_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"model\":\"embedding\",\"input\":[\"alpha\",\"beta\"]}'\n" }, { "lang": "typescript", "label": "OpenAI SDK (TS)", "source": "import OpenAI from 'openai';\nconst client = new OpenAI({\n baseURL: 'https://agents.yieldfabric.com/v1',\n apiKey: process.env.YF_API_KEY,\n});\nconst out = await client.embeddings.create({ model: 'embedding', input: ['alpha', 'beta'] });\nconsole.log(out.data[0].embedding.length);\n" }, { "lang": "python", "label": "OpenAI SDK (Python)", "source": "import os\nfrom openai import OpenAI\nclient = OpenAI(base_url=\"https://agents.yieldfabric.com/v1\",\n api_key=os.environ[\"YF_API_KEY\"])\nout = client.embeddings.create(model=\"embedding\", input=[\"alpha\", \"beta\"])\nprint(len(out.data[0].embedding))\n" } ], "x-related": [ { "operationId": "chatCompletions_Openai", "relation": "sibling" } ] } }, "/v1/models": { "get": { "operationId": "listModelsV1_Openai", "x-method": "GET", "x-path": "/v1/models", "x-handler": "handlers::openai_compat::list_models", "tags": [ "OpenAI Compatibility" ], "summary": "Model catalog in OpenAI list shape.", "description": "The same registry `GET /api/models` serves, shaped for OpenAI SDK\n`models.list()` calls. Entry ids are the stable registry ids\n(`default`, `mini`, `embedding`); deployment names also resolve on\nthe POST endpoints.\n\nAuth: bearer JWT or `yf_api_…` API key.\n", "parameters": [], "responses": { "200": { "description": "`{ object: \"list\", data: [{ id, object: \"model\", created, owned_by }] }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "object" ], "properties": { "id": { "type": "string", "description": "Registry id: `default`, `mini`, or `embedding`." }, "object": { "type": "string", "enum": [ "model" ] }, "created": { "type": "integer" }, "owned_by": { "type": "string" } } } } } } } } }, "401": { "description": "Missing/invalid credential, in the OpenAI error envelope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "description": "OpenAI-style error envelope used by every /v1 response ≥ 400 (including the middleware's 401s).", "properties": { "error": { "type": "object", "required": [ "message", "type" ], "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "billing_error", "api_error" ] }, "param": { "type": [ "string", "null" ] }, "code": { "type": [ "string", "null" ], "description": "Stable billing recovery reason on a 402 (`card_required`, `credit_plan_required`, `credit_exhausted`, or `billing_paused`); null for non-billing errors." } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listModelsV1_Openai", "resource_uri": "yf://agents/openai", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $YF_API_KEY\" https://agents.yieldfabric.com/v1/models\n" }, { "lang": "python", "label": "OpenAI SDK (Python)", "source": "import os\nfrom openai import OpenAI\nclient = OpenAI(base_url=\"https://agents.yieldfabric.com/v1\",\n api_key=os.environ[\"YF_API_KEY\"])\nprint([m.id for m in client.models.list().data])\n" } ], "x-related": [ { "operationId": "listModels_Misc", "relation": "sibling" } ] } }, "/version": { "get": { "operationId": "versionInfo_Misc", "x-method": "GET", "x-path": "/version", "x-handler": "handlers::version_info", "tags": [ "Health" ], "summary": "Build/version identity", "description": "Returns the running build's identity:\n`{\"service\",\"api_version\",\"git_sha\",\"built_at\"}`. `api_version` is\nbaked from this spec's `info.version` at compile time (by `build.rs`),\nso a deployment **cannot report a version it doesn't implement** — the\nintended way to confirm which API contract a server serves without\nprobing individual routes for presence. No auth required.\n", "parameters": [], "responses": { "200": { "description": "Build identity of the running service.", "content": { "application/json": { "schema": { "type": "object", "required": [ "service", "api_version", "git_sha", "built_at" ], "properties": { "service": { "type": "string", "description": "Static service identifier.", "example": "yieldfabric-agents" }, "api_version": { "type": "string", "description": "Agents REST API spec version, baked from this document's `info.version` at build time. Matches the CHANGELOG.", "example": "0.12.1" }, "git_sha": { "type": "string", "description": "Short git commit of the build, or `unknown` when built without a reachable git repo / CI SHA env.", "example": "e45bea7b3a30" }, "built_at": { "type": "string", "description": "UTC timestamp (RFC3339) when this build's version was baked.", "example": "2026-06-14T10:42:33.000Z" } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_versionInfo_Misc", "resource_uri": "yf://agents/misc", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl https://agents.yieldfabric.com/version" } ], "x-related": [ { "operationId": "healthCheck_Misc", "relation": "sibling" } ] } }, "/work/attention": { "get": { "operationId": "attention_Work", "x-method": "GET", "x-path": "/work/attention", "x-handler": "attention", "tags": [ "Work" ], "summary": "What needs the caller in a scope", "description": "Mounted only when the agents service runs with `AGENTS_WORK=on`; otherwise 404. The caller must be an active member of the scope group (`require_group_action`); deal rooms additionally require signed terms. Delegation and service tokens are refused on every `/work` route. Pending proposals, plus the caller's open items that are due within the horizon, overdue, or carry an unanswered `needs_answer` comment from someone else. Read from the work tables only; the caller's own view.", "parameters": [ { "name": "scope", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The working group whose work to read. A personal workspace is a one-member group." }, { "name": "horizon_days", "in": "query", "schema": { "type": "integer", "default": 7, "minimum": 0, "maximum": 365 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "pending_proposals": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "description": "A work item (`work::model::WorkItem`).", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string", "example": "W-42" }, "scope_group_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "epic", "task", "bug", "story", "investigation", "wish" ] }, "is_outcome": { "type": "boolean" }, "title": { "type": "string" }, "body": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "in_progress", "blocked", "in_review", "done", "cancelled" ] }, "pre_block_status": { "type": [ "string", "null" ] }, "status_changed_at": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "description": "Optimistic-concurrency version; every write bumps it." }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "assignee_entity_id": { "type": [ "string", "null" ] }, "reporter_entity_id": { "type": "string" }, "parent_id": { "type": [ "string", "null" ], "format": "uuid" }, "position": { "type": "integer" }, "hill_position": { "type": "integer", "minimum": 0, "maximum": 100 }, "labels": { "type": "array", "items": { "type": "string" } }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "due_tz": { "type": [ "string", "null" ] }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "thread_id": { "type": [ "string", "null" ], "format": "uuid" }, "requires_evidence": { "type": "boolean" }, "origin": { "type": "string", "enum": [ "person", "agent", "rule" ], "description": "Who decided this exists — derived from the credential, never from the payload." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Not a member of the scope, or a credential this route refuses (assistant, delegation, service)." }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_attention_Work", "resource_uri": "yf://agents/work", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/work/attention" } ], "x-related": [] } }, "/work/digest": { "get": { "operationId": "digest_Work", "x-method": "GET", "x-path": "/work/digest", "x-handler": "digest", "tags": [ "Work" ], "summary": "What came to the caller, per local calendar day", "description": "Mounted only when the agents service runs with `AGENTS_WORK=on`; otherwise 404. Delegation and service tokens are refused on every `/work` route. The queue's sources counted on the LOCAL day they arrived, from each row's own timestamp — proposals filed for the caller (`decide`), requests opened to them and unanswered `needs_answer` comments on their items (`asked`), requests they filed (`waiting_on`), and due dates that fell (`due`). Arrivals, not what is still open: the live queue answers that. Derived from the work tables on every read, never stored, so a day nobody opened the app still has an answer. Without `scope` it spans every workspace the caller can read (the same `scopes` CTE as the queue); with it, the caller must be able to read that workspace. The window is whole local days from the start of the day `days - 1` days ago through the end of today, so the oldest day is never a partial count. Days with nothing on them are absent.", "parameters": [ { "name": "scope", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "One working group. Absent, every workspace the caller can read." }, { "name": "days", "in": "query", "schema": { "type": "integer", "default": 60, "minimum": 1, "maximum": 180 }, "description": "Local days back, today included. Out-of-range values are clamped." }, { "name": "tz", "in": "query", "schema": { "type": "string", "example": "Australia/Sydney" }, "description": "The caller's IANA zone, checked against the server's `pg_timezone_names`. Absent, malformed or unknown reads as UTC." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "One local calendar day (`work::model::DigestDay`), ascending.", "properties": { "day": { "type": "string", "format": "date", "example": "2026-09-07" }, "decide": { "type": "integer" }, "asked": { "type": "integer" }, "waiting_on": { "type": "integer" }, "due": { "type": "integer" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Not a member of the scope, or a credential this route refuses (delegation, service)." }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_digest_Work", "resource_uri": "yf://agents/work", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/work/digest?days=60&tz=Australia/Sydney\"" } ], "x-related": [ "queue_Work" ] } }, "/work/items": { "get": { "operationId": "listItems_Work", "x-method": "GET", "x-path": "/work/items", "x-handler": "list_items", "tags": [ "Work" ], "summary": "List items in a scope", "description": "Mounted only when the agents service runs with `AGENTS_WORK=on`; otherwise 404. The caller must be an active member of the scope group (`require_group_action`); deal rooms additionally require signed terms. Delegation and service tokens are refused on every `/work` route. Keyset-paginated, newest activity first; `next_cursor` is null on the last page.", "parameters": [ { "name": "scope", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The working group whose work to read. A personal workspace is a one-member group." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "open", "in_progress", "blocked", "in_review", "done", "cancelled" ] } }, { "name": "assignee", "in": "query", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "epic", "task", "bug", "story", "investigation", "wish" ] } }, { "name": "parent", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "`next_cursor` from the previous page." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "description": "A work item (`work::model::WorkItem`).", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string", "example": "W-42" }, "scope_group_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "epic", "task", "bug", "story", "investigation", "wish" ] }, "is_outcome": { "type": "boolean" }, "title": { "type": "string" }, "body": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "in_progress", "blocked", "in_review", "done", "cancelled" ] }, "pre_block_status": { "type": [ "string", "null" ] }, "status_changed_at": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "description": "Optimistic-concurrency version; every write bumps it." }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "assignee_entity_id": { "type": [ "string", "null" ] }, "reporter_entity_id": { "type": "string" }, "parent_id": { "type": [ "string", "null" ], "format": "uuid" }, "position": { "type": "integer" }, "hill_position": { "type": "integer", "minimum": 0, "maximum": 100 }, "labels": { "type": "array", "items": { "type": "string" } }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "due_tz": { "type": [ "string", "null" ] }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "thread_id": { "type": [ "string", "null" ], "format": "uuid" }, "requires_evidence": { "type": "boolean" }, "origin": { "type": "string", "enum": [ "person", "agent", "rule" ], "description": "Who decided this exists — derived from the credential, never from the payload." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Invalid input, or a move the state machine refuses (the message says why)." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Not a member of the scope, or a credential this route refuses (assistant, delegation, service)." }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listItems_Work", "resource_uri": "yf://agents/work", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/work/items" } ], "x-related": [] }, "post": { "operationId": "createItem_Work", "x-method": "POST", "x-path": "/work/items", "x-handler": "create_item", "tags": [ "Work" ], "summary": "Create an item (a person's direct write)", "description": "Mounted only when the agents service runs with `AGENTS_WORK=on`; otherwise 404. The caller must be an active member of the scope group (`require_group_action`); deal rooms additionally require signed terms. Delegation and service tokens are refused on every `/work` route. An assistant credential (JWT `agent_id` or `mcp_agent_id`) may only propose and comment; every other mutation is refused to it with 403. A person's own capture is a direct create; assistants file proposals instead.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "scope_group_id" ], "properties": { "scope_group_id": { "type": "string", "format": "uuid" } } }, { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "maxLength": 300 }, "body": { "type": "string", "maxLength": 20000 }, "kind": { "type": "string", "enum": [ "epic", "task", "bug", "story", "investigation", "wish" ] }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "assignee_entity_id": { "type": "string" }, "parent_id": { "type": "string", "format": "uuid" }, "labels": { "type": "array", "items": { "type": "string" } }, "due_at": { "type": "string", "format": "date-time" }, "due_tz": { "type": "string" }, "links": { "type": "array", "items": { "type": "object", "required": [ "subject_kind", "subject_id" ], "properties": { "subject_kind": { "type": "string", "enum": [ "item", "message", "thread", "event", "file", "contact", "document", "url" ] }, "subject_id": { "type": "string" }, "relation": { "type": "string", "default": "about" }, "subject_label": { "type": "string" }, "note": { "type": "string" } } } }, "position": { "type": "integer" }, "requires_evidence": { "type": "boolean" }, "is_outcome": { "type": "boolean" } } } ] }, "examples": { "minimal": { "value": { "scope_group_id": "898513fd-9d28-471f-81b6-6d011d2b4804", "title": "Send Maria the invoice" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "description": "A work item (`work::model::WorkItem`).", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string", "example": "W-42" }, "scope_group_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "epic", "task", "bug", "story", "investigation", "wish" ] }, "is_outcome": { "type": "boolean" }, "title": { "type": "string" }, "body": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "in_progress", "blocked", "in_review", "done", "cancelled" ] }, "pre_block_status": { "type": [ "string", "null" ] }, "status_changed_at": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "description": "Optimistic-concurrency version; every write bumps it." }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "assignee_entity_id": { "type": [ "string", "null" ] }, "reporter_entity_id": { "type": "string" }, "parent_id": { "type": [ "string", "null" ], "format": "uuid" }, "position": { "type": "integer" }, "hill_position": { "type": "integer", "minimum": 0, "maximum": 100 }, "labels": { "type": "array", "items": { "type": "string" } }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "due_tz": { "type": [ "string", "null" ] }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "thread_id": { "type": [ "string", "null" ], "format": "uuid" }, "requires_evidence": { "type": "boolean" }, "origin": { "type": "string", "enum": [ "person", "agent", "rule" ], "description": "Who decided this exists — derived from the credential, never from the payload." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Invalid input, or a move the state machine refuses (the message says why)." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Not a member of the scope, or a credential this route refuses (assistant, delegation, service)." }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_createItem_Work", "resource_uri": "yf://agents/work", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/work/items -H 'Content-Type: application/json' -d '{}'" } ], "x-related": [] } }, "/work/items/by-subject": { "get": { "operationId": "itemsBySubject_Work", "x-method": "GET", "x-path": "/work/items/by-subject", "x-handler": "items_by_subject", "tags": [ "Work" ], "summary": "Items linked to one subject", "description": "Mounted only when the agents service runs with `AGENTS_WORK=on`; otherwise 404. The caller must be an active member of the scope group (`require_group_action`); deal rooms additionally require signed terms. Delegation and service tokens are refused on every `/work` route. How an assistant matches a finding to an item without holding work state: 'is there an item about this thread key / this contact'.", "parameters": [ { "name": "scope", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The working group whose work to read. A personal workspace is a one-member group." }, { "name": "subject_kind", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "item", "message", "thread", "event", "file", "contact", "document", "url" ] } }, { "name": "subject_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "A work item (`work::model::WorkItem`).", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string", "example": "W-42" }, "scope_group_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "epic", "task", "bug", "story", "investigation", "wish" ] }, "is_outcome": { "type": "boolean" }, "title": { "type": "string" }, "body": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "in_progress", "blocked", "in_review", "done", "cancelled" ] }, "pre_block_status": { "type": [ "string", "null" ] }, "status_changed_at": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "description": "Optimistic-concurrency version; every write bumps it." }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "assignee_entity_id": { "type": [ "string", "null" ] }, "reporter_entity_id": { "type": "string" }, "parent_id": { "type": [ "string", "null" ], "format": "uuid" }, "position": { "type": "integer" }, "hill_position": { "type": "integer", "minimum": 0, "maximum": 100 }, "labels": { "type": "array", "items": { "type": "string" } }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "due_tz": { "type": [ "string", "null" ] }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "thread_id": { "type": [ "string", "null" ], "format": "uuid" }, "requires_evidence": { "type": "boolean" }, "origin": { "type": "string", "enum": [ "person", "agent", "rule" ], "description": "Who decided this exists — derived from the credential, never from the payload." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } }, "400": { "description": "Invalid input, or a move the state machine refuses (the message says why)." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Not a member of the scope, or a credential this route refuses (assistant, delegation, service)." }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_itemsBySubject_Work", "resource_uri": "yf://agents/work", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/work/items/by-subject" } ], "x-related": [] } }, "/work/items/{id}": { "get": { "operationId": "getItem_Work", "x-method": "GET", "x-path": "/work/items/{id}", "x-handler": "get_item", "tags": [ "Work" ], "summary": "One item with its links, events and legal moves", "description": "Mounted only when the agents service runs with `AGENTS_WORK=on`; otherwise 404. The scope is derived from the row and the caller gated on it. The caller must be an active member of the scope group (`require_group_action`); deal rooms additionally require signed terms. Delegation and service tokens are refused on every `/work` route. The view also carries `requests` (the item's questions, approvals and handoffs) and `held_by_request_id` (the open approval holding its moves, if any).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The item's (or proposal's) id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "A work item (`work::model::WorkItem`).", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string", "example": "W-42" }, "scope_group_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "epic", "task", "bug", "story", "investigation", "wish" ] }, "is_outcome": { "type": "boolean" }, "title": { "type": "string" }, "body": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "in_progress", "blocked", "in_review", "done", "cancelled" ] }, "pre_block_status": { "type": [ "string", "null" ] }, "status_changed_at": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "description": "Optimistic-concurrency version; every write bumps it." }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "assignee_entity_id": { "type": [ "string", "null" ] }, "reporter_entity_id": { "type": "string" }, "parent_id": { "type": [ "string", "null" ], "format": "uuid" }, "position": { "type": "integer" }, "hill_position": { "type": "integer", "minimum": 0, "maximum": 100 }, "labels": { "type": "array", "items": { "type": "string" } }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "due_tz": { "type": [ "string", "null" ] }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "thread_id": { "type": [ "string", "null" ], "format": "uuid" }, "requires_evidence": { "type": "boolean" }, "origin": { "type": "string", "enum": [ "person", "agent", "rule" ], "description": "Who decided this exists — derived from the credential, never from the payload." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, { "type": "object", "properties": { "legal_targets": { "type": "array", "items": { "type": "string" } }, "links": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "subject_kind": { "type": "string", "enum": [ "item", "message", "thread", "event", "file", "contact", "document", "url" ] }, "subject_id": { "type": "string" }, "relation": { "type": "string", "enum": [ "about", "blocks", "blocked_by", "duplicates", "relates_to", "evidences", "discovered_in" ] }, "subject_label": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "origin": { "type": "string", "enum": [ "person", "agent", "rule" ] }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "actor_entity_id": { "type": "string" }, "actor_kind": { "type": "string", "enum": [ "user", "agent", "system" ] }, "agent_id": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] }, "payload": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" } } } } } } ] } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Not a member of the scope, or a credential this route refuses (assistant, delegation, service)." }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getItem_Work", "resource_uri": "yf://agents/work", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/work/items/{id}" } ], "x-related": [] }, "patch": { "operationId": "patchItem_Work", "x-method": "PATCH", "x-path": "/work/items/{id}", "x-handler": "patch_item", "tags": [ "Work" ], "summary": "Patch an item", "description": "Mounted only when the agents service runs with `AGENTS_WORK=on`; otherwise 404. The caller must be an active member of the scope group (`require_group_action`); deal rooms additionally require signed terms. Delegation and service tokens are refused on every `/work` route. An assistant credential (JWT `agent_id` or `mcp_agent_id`) may only propose and comment; every other mutation is refused to it with 403. Explicit `null` clears a nullable field; an absent field is left alone. Pass `version` to refuse a stale write with 409.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The item's (or proposal's) id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "body": { "type": "string" }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "kind": { "type": "string", "enum": [ "epic", "task", "bug", "story", "investigation", "wish" ] }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "due_tz": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" } }, "hill_position": { "type": "integer", "minimum": 0, "maximum": 100 }, "assignee_entity_id": { "type": [ "string", "null" ] }, "is_outcome": { "type": "boolean" }, "position": { "type": "integer" }, "parent_id": { "type": [ "string", "null" ], "format": "uuid" }, "version": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "description": "A work item (`work::model::WorkItem`).", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string", "example": "W-42" }, "scope_group_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "epic", "task", "bug", "story", "investigation", "wish" ] }, "is_outcome": { "type": "boolean" }, "title": { "type": "string" }, "body": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "in_progress", "blocked", "in_review", "done", "cancelled" ] }, "pre_block_status": { "type": [ "string", "null" ] }, "status_changed_at": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "description": "Optimistic-concurrency version; every write bumps it." }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "assignee_entity_id": { "type": [ "string", "null" ] }, "reporter_entity_id": { "type": "string" }, "parent_id": { "type": [ "string", "null" ], "format": "uuid" }, "position": { "type": "integer" }, "hill_position": { "type": "integer", "minimum": 0, "maximum": 100 }, "labels": { "type": "array", "items": { "type": "string" } }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "due_tz": { "type": [ "string", "null" ] }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "thread_id": { "type": [ "string", "null" ], "format": "uuid" }, "requires_evidence": { "type": "boolean" }, "origin": { "type": "string", "enum": [ "person", "agent", "rule" ], "description": "Who decided this exists — derived from the credential, never from the payload." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Invalid input, or a move the state machine refuses (the message says why)." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Not a member of the scope, or a credential this route refuses (assistant, delegation, service)." }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "409": { "description": "The item moved underneath the caller (status or version changed). The message names its current status and version; reload and retry." } }, "x-mcp": { "tool_name": "yieldfabric_agents_patchItem_Work", "resource_uri": "yf://agents/work", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PATCH -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/work/items/{id} -H 'Content-Type: application/json' -d '{}'" } ], "x-related": [] } }, "/work/items/{id}/comments": { "post": { "operationId": "comment_Work", "x-method": "POST", "x-path": "/work/items/{id}/comments", "x-handler": "comment", "tags": [ "Work" ], "summary": "Comment on an item", "description": "Mounted only when the agents service runs with `AGENTS_WORK=on`; otherwise 404. The caller must be an active member of the scope group (`require_group_action`); deal rooms additionally require signed terms. Delegation and service tokens are refused on every `/work` route. The one direct write an assistant may make besides a proposal; the event carries `actor_kind`. `needs_answer` marks a question the assignee should answer — it surfaces in `/work/attention`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The item's (or proposal's) id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string", "maxLength": 20000 }, "needs_answer": { "type": "boolean", "default": false } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "actor_entity_id": { "type": "string" }, "actor_kind": { "type": "string", "enum": [ "user", "agent", "system" ] }, "agent_id": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] }, "payload": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Invalid input, or a move the state machine refuses (the message says why)." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Not a member of the scope, or a credential this route refuses (assistant, delegation, service)." }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_comment_Work", "resource_uri": "yf://agents/work", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/work/items/{id}/comments -H 'Content-Type: application/json' -d '{}'" } ], "x-related": [] } }, "/work/items/{id}/events": { "get": { "operationId": "listEvents_Work", "x-method": "GET", "x-path": "/work/items/{id}/events", "x-handler": "list_events", "tags": [ "Work" ], "summary": "An item's history", "description": "Mounted only when the agents service runs with `AGENTS_WORK=on`; otherwise 404. The caller must be an active member of the scope group (`require_group_action`); deal rooms additionally require signed terms. Delegation and service tokens are refused on every `/work` route. Append-only; comments are events.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The item's (or proposal's) id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "actor_entity_id": { "type": "string" }, "actor_kind": { "type": "string", "enum": [ "user", "agent", "system" ] }, "agent_id": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] }, "payload": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Not a member of the scope, or a credential this route refuses (assistant, delegation, service)." }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listEvents_Work", "resource_uri": "yf://agents/work", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/work/items/{id}/events" } ], "x-related": [] } }, "/work/items/{id}/links": { "post": { "operationId": "addLink_Work", "x-method": "POST", "x-path": "/work/items/{id}/links", "x-handler": "add_link", "tags": [ "Work" ], "summary": "Link a subject to an item", "description": "Mounted only when the agents service runs with `AGENTS_WORK=on`; otherwise 404. The caller must be an active member of the scope group (`require_group_action`); deal rooms additionally require signed terms. Delegation and service tokens are refused on every `/work` route. An assistant credential (JWT `agent_id` or `mcp_agent_id`) may only propose and comment; every other mutation is refused to it with 403. Idempotent on `(item, subject_kind, subject_id, relation)`; `created: false` means it was already there.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The item's (or proposal's) id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "subject_kind", "subject_id" ], "properties": { "subject_kind": { "type": "string", "enum": [ "item", "message", "thread", "event", "file", "contact", "document", "url" ] }, "subject_id": { "type": "string" }, "relation": { "type": "string", "default": "about" }, "subject_label": { "type": "string" }, "note": { "type": "string" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "link": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "subject_kind": { "type": "string", "enum": [ "item", "message", "thread", "event", "file", "contact", "document", "url" ] }, "subject_id": { "type": "string" }, "relation": { "type": "string", "enum": [ "about", "blocks", "blocked_by", "duplicates", "relates_to", "evidences", "discovered_in" ] }, "subject_label": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "origin": { "type": "string", "enum": [ "person", "agent", "rule" ] }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, { "type": "null" } ] }, "created": { "type": "boolean" } } } } } }, "400": { "description": "Invalid input, or a move the state machine refuses (the message says why)." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Not a member of the scope, or a credential this route refuses (assistant, delegation, service)." }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_addLink_Work", "resource_uri": "yf://agents/work", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/work/items/{id}/links -H 'Content-Type: application/json' -d '{}'" } ], "x-related": [] } }, "/work/items/{id}/links/{link_id}": { "delete": { "operationId": "removeLink_Work", "x-method": "DELETE", "x-path": "/work/items/{id}/links/{link_id}", "x-handler": "remove_link", "tags": [ "Work" ], "summary": "Remove a link", "description": "Mounted only when the agents service runs with `AGENTS_WORK=on`; otherwise 404. The caller must be an active member of the scope group (`require_group_action`); deal rooms additionally require signed terms. Delegation and service tokens are refused on every `/work` route. An assistant credential (JWT `agent_id` or `mcp_agent_id`) may only propose and comment; every other mutation is refused to it with 403.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The item's (or proposal's) id." }, { "name": "link_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "boolean" } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Not a member of the scope, or a credential this route refuses (assistant, delegation, service)." }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_removeLink_Work", "resource_uri": "yf://agents/work", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X DELETE -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/work/items/{id}/links/{link_id} -H 'Content-Type: application/json' -d '{}'" } ], "x-related": [] } }, "/work/items/{id}/requests": { "get": { "operationId": "listRequests_Work", "x-method": "GET", "x-path": "/work/items/{id}/requests", "x-handler": "list_requests", "tags": [ "Work" ], "summary": "An item's requests (questions, approvals, handoffs)", "description": "Mounted only when the agents service runs with `AGENTS_WORK=on`; otherwise 404. Scope is derived from the row and the caller is gated on it (`require_group_action`; deal rooms additionally require signed terms). Delegation and service tokens are refused on every `/work` route. Every request on the item, open and resolved, oldest first. Readable by any active member of the scope, assistants included.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "scope_group_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "question", "approval", "handoff" ] }, "from_entity_id": { "type": "string" }, "to_entity_id": { "type": "string" }, "body": { "type": "string" }, "payload": { "type": "object", "description": "approval: `{ to, reason }` — the move the approver releases." }, "status": { "type": "string", "enum": [ "open", "answered", "approved", "declined", "accepted", "cancelled" ] }, "response": { "type": [ "string", "null" ] }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "origin": { "type": "string", "enum": [ "person", "agent", "rule" ] }, "resolved_by": { "type": [ "string", "null" ] }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } }, "400": { "description": "Invalid input, or a move the state machine refuses (the message says why)." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Not a member of the scope, or a credential this route refuses (assistant, delegation, service)." }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listRequests_Work", "resource_uri": "yf://agents/work", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/work/items/{id}/requests" } ], "x-related": [ "openRequest_Work", "respondRequest_Work" ] }, "post": { "operationId": "openRequest_Work", "x-method": "POST", "x-path": "/work/items/{id}/requests", "x-handler": "open_request", "tags": [ "Work" ], "summary": "Ask another member for an answer, an approval or a handoff (persons only)", "description": "Mounted only when the agents service runs with `AGENTS_WORK=on`; otherwise 404. Scope is derived from the row and the caller is gated on it (`require_group_action`; deal rooms additionally require signed terms). Delegation and service tokens are refused on every `/work` route. A person asks another ACTIVE member of the same workspace (`to_entity_id`; never themselves) about this item. `question` expects an answer; `approval` names the status it would release the item to (`to`, plus `reason` where the machine requires one) and HOLDS the item — every other transition is refused with 400 until the approval is approved, declined or cancelled, and a second open approval on the same item is refused; `handoff` offers the item, and the addressee becomes its assignee on accept. Refused for assistant credentials: an assistant proposes a request (`propose_Work` with `action: request`) that its person accepts. Records a `request_opened` event.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "kind", "to_entity_id", "body" ], "properties": { "kind": { "type": "string", "enum": [ "question", "approval", "handoff" ] }, "to_entity_id": { "type": "string" }, "body": { "type": "string", "maxLength": 2000 }, "to": { "type": "string", "description": "approval: the status the approver releases the item to; must be a legal move now." }, "reason": { "type": "string", "description": "approval: required when `to` is blocked or cancelled." }, "due_at": { "type": "string", "format": "date-time" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "scope_group_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "question", "approval", "handoff" ] }, "from_entity_id": { "type": "string" }, "to_entity_id": { "type": "string" }, "body": { "type": "string" }, "payload": { "type": "object", "description": "approval: `{ to, reason }` — the move the approver releases." }, "status": { "type": "string", "enum": [ "open", "answered", "approved", "declined", "accepted", "cancelled" ] }, "response": { "type": [ "string", "null" ] }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "origin": { "type": "string", "enum": [ "person", "agent", "rule" ] }, "resolved_by": { "type": [ "string", "null" ] }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Invalid input, or a move the state machine refuses (the message says why)." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Not a member of the scope, or a credential this route refuses (assistant, delegation, service)." }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_openRequest_Work", "resource_uri": "yf://agents/work", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/work/items/{id}/requests -H 'Content-Type: application/json' -d '{\"kind\":\"question\",\"to_entity_id\":\"\",\"body\":\"Which memo?\"}'" } ], "x-related": [ "respondRequest_Work", "cancelRequest_Work", "queue_Work" ] } }, "/work/items/{id}/start-workspace": { "post": { "operationId": "startWorkspace_Work", "x-method": "POST", "x-path": "/work/items/{id}/start-workspace", "x-handler": "start_workspace", "tags": [ "Work" ], "summary": "Start a shared workspace from an item (persons only)", "description": "Mounted only when the agents service runs with `AGENTS_WORK=on`; otherwise 404. The on-ramp from a private board to a shared one. Creates a working group exactly as `POST /working-groups` does (same store, general economy, category `group`, the caller added as `owner`), then in ONE transaction creates a successor item in it — same title, body, kind, priority, labels, due and copies of the original's links — and links the two with `relates_to` in each direction. The original is not moved (an item never leaves its scope) and keeps its provenance. Nothing is sent: inviting the counterpart is the new workspace's existing members flow. The caller must hold `DecideWork` on the item's scope; assistant credentials are refused. `name` defaults to the item's title (≤120 chars).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120 } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace_id": { "type": "string", "format": "uuid" }, "workspace_name": { "type": "string" }, "item": { "type": "object", "description": "The successor item in the new workspace." }, "original": { "type": "object", "description": "The original, now carrying a link forward." } } } } } }, "400": { "description": "Invalid input (a name over 120 characters)." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Not a member of the scope, or a credential this route refuses (assistant, delegation, service)." }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_startWorkspace_Work", "resource_uri": "yf://agents/work", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/work/items/{id}/start-workspace -H 'Content-Type: application/json' -d '{\"name\":\"Invoice with Maria\"}'" } ], "x-related": [ "createItem_Work", "openRequest_Work" ] } }, "/work/items/{id}/rank": { "post": { "operationId": "rank_Work", "x-method": "POST", "x-path": "/work/items/{id}/rank", "x-handler": "rank", "tags": [ "Work" ], "summary": "Restack a card inside its column", "description": "Mounted only when the agents service runs with `AGENTS_WORK=on`; otherwise 404. Same authority as any other move of the card (`DecideWork`): an active member of the scope group, signed terms in a deal room, no delegation or service tokens, and an assistant credential may not call it.\nWhere a card sits in its column is not what state it is in, so this touches no status and runs no transition — a drop that crosses columns is a `transition` first and then this. The card lands immediately behind `after`, or at the top of its column when that is null; the server renumbers the WHOLE column on a stride and returns it in its new order, so the client sends the card it was dropped behind rather than a number and two people dragging at once cannot invent conflicting ranks for one slot.\nThe cards it shuffles past keep their `version`, `updated_at` and their history: no `patched` event is written and no list that sorts by activity reshuffles because somebody tidied a board. Boards stack by `position` ascending and fall back to newest-activity-first, so a column nobody has ranked is unchanged — every card starts at 0. Ranking behind a card in another column is refused; so is ranking a card behind itself.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The card being restacked." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "after": { "type": [ "string", "null" ], "format": "uuid", "description": "The card this one lands behind; null (or absent) puts it at the top of the column." } } }, "examples": { "behind-a-card": { "value": { "after": "7f1c9a5e-2c1b-4c9a-9f3e-0b1d2c3a4b5c" } }, "to-the-top": { "value": { "after": null } } } } } }, "responses": { "200": { "description": "The card's column, in its new order, with the positions the server assigned.", "content": { "application/json": { "schema": { "type": "array", "description": "Work items (`work::model::WorkItem`), ranked ascending by `position`.", "items": { "type": "object", "additionalProperties": true } } } } }, "400": { "description": "The anchor is in another column, is not in this scope, or is the card itself." }, "401": { "description": "Missing or invalid bearer credential." }, "403": { "description": "Not an active member of the scope, unsigned room terms, or an assistant/service credential." }, "404": { "description": "No such card, or `AGENTS_WORK` is off." } }, "x-mcp": { "tool_name": "yieldfabric_agents_rank_Work", "resource_uri": "yf://agents/work", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST https://agents.yieldfabric.com/work/items/{id}/rank \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"after\":\"7f1c9a5e-2c1b-4c9a-9f3e-0b1d2c3a4b5c\"}'\n" } ], "x-related": [ { "guide": "working-groups", "relation": "concept" } ] } }, "/work/items/{id}/transition": { "post": { "operationId": "transition_Work", "x-method": "POST", "x-path": "/work/items/{id}/transition", "x-handler": "transition", "tags": [ "Work" ], "summary": "Move an item one legal step", "description": "Mounted only when the agents service runs with `AGENTS_WORK=on`; otherwise 404. The caller must be an active member of the scope group (`require_group_action`); deal rooms additionally require signed terms. Delegation and service tokens are refused on every `/work` route. An assistant credential (JWT `agent_id` or `mcp_agent_id`) may only propose and comment; every other mutation is refused to it with 403. One guarded statement: `status = expected AND version = v`; a loser sees 409 with the current state. `blocked` and `cancelled` require a reason. Starting unowned work adopts the person as assignee. An item that requires evidence cannot reach `done` without an `evidences` link.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The item's (or proposal's) id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "to" ], "properties": { "to": { "type": "string", "enum": [ "open", "in_progress", "blocked", "in_review", "done", "cancelled" ] }, "reason": { "type": "string" }, "version": { "type": "integer" } } }, "examples": { "block": { "value": { "to": "blocked", "reason": "waiting on legal" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "description": "A work item (`work::model::WorkItem`).", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string", "example": "W-42" }, "scope_group_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "epic", "task", "bug", "story", "investigation", "wish" ] }, "is_outcome": { "type": "boolean" }, "title": { "type": "string" }, "body": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "in_progress", "blocked", "in_review", "done", "cancelled" ] }, "pre_block_status": { "type": [ "string", "null" ] }, "status_changed_at": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "description": "Optimistic-concurrency version; every write bumps it." }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "assignee_entity_id": { "type": [ "string", "null" ] }, "reporter_entity_id": { "type": "string" }, "parent_id": { "type": [ "string", "null" ], "format": "uuid" }, "position": { "type": "integer" }, "hill_position": { "type": "integer", "minimum": 0, "maximum": 100 }, "labels": { "type": "array", "items": { "type": "string" } }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "due_tz": { "type": [ "string", "null" ] }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "thread_id": { "type": [ "string", "null" ], "format": "uuid" }, "requires_evidence": { "type": "boolean" }, "origin": { "type": "string", "enum": [ "person", "agent", "rule" ], "description": "Who decided this exists — derived from the credential, never from the payload." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Invalid input, or a move the state machine refuses (the message says why)." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Not a member of the scope, or a credential this route refuses (assistant, delegation, service)." }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "409": { "description": "The item moved underneath the caller (status or version changed). The message names its current status and version; reload and retry." } }, "x-mcp": { "tool_name": "yieldfabric_agents_transition_Work", "resource_uri": "yf://agents/work", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/work/items/{id}/transition -H 'Content-Type: application/json' -d '{}'" } ], "x-related": [] } }, "/work/items/{id}/walk": { "post": { "operationId": "walk_Work", "x-method": "POST", "x-path": "/work/items/{id}/walk", "x-handler": "walk", "tags": [ "Work" ], "summary": "Move an item several legal steps atomically", "description": "Mounted only when the agents service runs with `AGENTS_WORK=on`; otherwise 404. The caller must be an active member of the scope group (`require_group_action`); deal rooms additionally require signed terms. Delegation and service tokens are refused on every `/work` route. An assistant credential (JWT `agent_id` or `mcp_agent_id`) may only propose and comment; every other mutation is refused to it with 403. Follows the shortest legal path (never through `blocked` or `cancelled`) inside one transaction; a refusal on any hop leaves the item where it was.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The item's (or proposal's) id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "to" ], "properties": { "to": { "type": "string", "enum": [ "open", "in_progress", "blocked", "in_review", "done", "cancelled" ] }, "reason": { "type": "string" }, "version": { "type": "integer" } } }, "examples": { "done": { "value": { "to": "done" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "description": "A work item (`work::model::WorkItem`).", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string", "example": "W-42" }, "scope_group_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "epic", "task", "bug", "story", "investigation", "wish" ] }, "is_outcome": { "type": "boolean" }, "title": { "type": "string" }, "body": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "in_progress", "blocked", "in_review", "done", "cancelled" ] }, "pre_block_status": { "type": [ "string", "null" ] }, "status_changed_at": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "description": "Optimistic-concurrency version; every write bumps it." }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "assignee_entity_id": { "type": [ "string", "null" ] }, "reporter_entity_id": { "type": "string" }, "parent_id": { "type": [ "string", "null" ], "format": "uuid" }, "position": { "type": "integer" }, "hill_position": { "type": "integer", "minimum": 0, "maximum": 100 }, "labels": { "type": "array", "items": { "type": "string" } }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "due_tz": { "type": [ "string", "null" ] }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "thread_id": { "type": [ "string", "null" ], "format": "uuid" }, "requires_evidence": { "type": "boolean" }, "origin": { "type": "string", "enum": [ "person", "agent", "rule" ], "description": "Who decided this exists — derived from the credential, never from the payload." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Invalid input, or a move the state machine refuses (the message says why)." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Not a member of the scope, or a credential this route refuses (assistant, delegation, service)." }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "409": { "description": "The item moved underneath the caller (status or version changed). The message names its current status and version; reload and retry." } }, "x-mcp": { "tool_name": "yieldfabric_agents_walk_Work", "resource_uri": "yf://agents/work", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/work/items/{id}/walk -H 'Content-Type: application/json' -d '{}'" } ], "x-related": [] } }, "/work/meta": { "get": { "operationId": "meta_Work", "x-method": "GET", "x-path": "/work/meta", "x-handler": "meta", "tags": [ "Work" ], "summary": "The state machine as data", "description": "Mounted only when the agents service runs with `AGENTS_WORK=on`; otherwise 404. Statuses, the transition table, which moves require a reason, kinds, relations, subject kinds, priorities, proposal actions and event kinds — served so a client can render only moves the server will take. Any verified caller. Also carries `request_kinds`, `request_statuses` and `queue_kinds`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "statuses": { "type": "array", "items": { "type": "string" } }, "requires_reason": { "type": "array", "items": { "type": "string" } }, "kinds": { "type": "array", "items": { "type": "string" } }, "relations": { "type": "array", "items": { "type": "string" } }, "subject_kinds": { "type": "array", "items": { "type": "string" } }, "priorities": { "type": "array", "items": { "type": "string" } }, "proposal_actions": { "type": "array", "items": { "type": "string" } }, "event_kinds": { "type": "array", "items": { "type": "string" } }, "transitions": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Not a member of the scope, or a credential this route refuses (assistant, delegation, service)." }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_meta_Work", "resource_uri": "yf://agents/work", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/work/meta" } ], "x-related": [] } }, "/work/metrics": { "get": { "operationId": "metrics_Work", "x-method": "GET", "x-path": "/work/metrics", "x-handler": "metrics", "tags": [ "Work" ], "summary": "Proposal metrics for a scope", "description": "Mounted only when the agents service runs with `AGENTS_WORK=on`; otherwise 404. The caller must be an active member of the scope group (`require_group_action`); deal rooms additionally require signed terms. Delegation and service tokens are refused on every `/work` route. Proposals by status over the window, the acceptance rate among decided ones, and how many open items came from suggestions — the v1 metric.", "parameters": [ { "name": "scope", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The working group whose work to read. A personal workspace is a one-member group." }, { "name": "window_days", "in": "query", "schema": { "type": "integer", "default": 14, "minimum": 1, "maximum": 365 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "window_days": { "type": "integer" }, "pending": { "type": "integer" }, "accepted": { "type": "integer" }, "dismissed": { "type": "integer" }, "expired": { "type": "integer" }, "acceptance_rate": { "type": [ "number", "null" ] }, "open_items": { "type": "integer" }, "open_items_from_agent": { "type": "integer" } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Not a member of the scope, or a credential this route refuses (assistant, delegation, service)." }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_metrics_Work", "resource_uri": "yf://agents/work", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/work/metrics" } ], "x-related": [] } }, "/work/proposals": { "get": { "operationId": "listProposals_Work", "x-method": "GET", "x-path": "/work/proposals", "x-handler": "list_proposals", "tags": [ "Work" ], "summary": "Proposals in a scope", "description": "Mounted only when the agents service runs with `AGENTS_WORK=on`; otherwise 404. The caller must be an active member of the scope group (`require_group_action`); deal rooms additionally require signed terms. Delegation and service tokens are refused on every `/work` route. Defaults to `pending`. What assistants suggested; nothing here exists until accepted.", "parameters": [ { "name": "scope", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The working group whose work to read. A personal workspace is a one-member group." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "accepted", "dismissed", "expired" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "scope_group_id": { "type": "string", "format": "uuid" }, "proposer_agent_id": { "type": "string" }, "on_behalf_of": { "type": "string" }, "action": { "type": "string", "enum": [ "create", "link" ] }, "target_item_id": { "type": [ "string", "null" ], "format": "uuid" }, "payload": { "type": "object", "description": "For `create`: a NewItem. For `link`: a NewLink." }, "rationale": { "type": "string", "maxLength": 300 }, "provenance": { "type": "array", "items": { "type": "string" }, "description": "Opaque ids (Javier `MSG:`/`THREAD:` fetch ids) the proposal rests on." }, "dedupe_key": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "accepted", "dismissed", "expired" ] }, "resolved_by": { "type": [ "string", "null" ] }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "result_item_id": { "type": [ "string", "null" ], "format": "uuid" }, "expires_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Not a member of the scope, or a credential this route refuses (assistant, delegation, service)." }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listProposals_Work", "resource_uri": "yf://agents/work", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/work/proposals" } ], "x-related": [] }, "post": { "operationId": "propose_Work", "x-method": "POST", "x-path": "/work/proposals", "x-handler": "propose", "tags": [ "Work" ], "summary": "File a proposal (assistant credentials only)", "description": "Mounted only when the agents service runs with `AGENTS_WORK=on`; otherwise 404. The caller must be an active member of the scope group (`require_group_action`); deal rooms additionally require signed terms. Delegation and service tokens are refused on every `/work` route. Refused with 403 for a person's JWT — a person acts directly. Idempotent on `(scope, dedupe_key)`: `created: false` returns the row already filed (or the card it merged into). Actions: `create` (a NewItem), `link` (a NewLink on `target_item_id`), `comment` (`{body, needs_answer}` on `target_item_id`), `transition` (`{to, reason}`), `update` (an ItemPatch subset), `request` (a NewRequest — see openRequest_Work — to an active member), `respond` (`{request_id, outcome, body}` for a request addressed to the assistant's own person). Every payload is validated now so an accept cannot fail on shape; every accept applies under the ACCEPTING person. `coalesce_key` (optional): while a PENDING proposal with the same key exists in the scope, this one is recorded as `merged` into it — the card gains its provenance and, for two `create`s, the union of their links — and the response carries `merged: true` with the card; once that card is decided, the next proposal starts a fresh card. Javier keys mail proposals on the thread, so one thread is one card. Proposals expire after seven days.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "scope_group_id", "action", "payload", "rationale", "dedupe_key" ], "properties": { "scope_group_id": { "type": "string", "format": "uuid" }, "action": { "type": "string", "enum": [ "create", "link", "comment", "transition", "update", "request", "respond" ] }, "target_item_id": { "type": "string", "format": "uuid", "description": "Required for every action but `create` and `respond`." }, "payload": { "type": "object", "description": "Shape depends on `action`: NewItem · NewLink · `{body, needs_answer}` · `{to, reason}` · ItemPatch fields · NewRequest · `{request_id, outcome, body}`." }, "rationale": { "type": "string", "maxLength": 300 }, "provenance": { "type": "array", "items": { "type": "string" } }, "dedupe_key": { "type": "string", "maxLength": 512 }, "coalesce_key": { "type": "string", "maxLength": 512, "description": "Proposals sharing this key show as ONE card while pending (Javier: the mail thread)." } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "proposal": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "scope_group_id": { "type": "string", "format": "uuid" }, "proposer_agent_id": { "type": "string" }, "on_behalf_of": { "type": "string" }, "action": { "type": "string", "enum": [ "create", "link", "comment", "transition", "update", "request", "respond" ] }, "target_item_id": { "type": [ "string", "null" ], "format": "uuid" }, "payload": { "type": "object", "description": "For `create`: a NewItem. For `link`: a NewLink." }, "rationale": { "type": "string", "maxLength": 300 }, "provenance": { "type": "array", "items": { "type": "string" }, "description": "Opaque ids (Javier `MSG:`/`THREAD:` fetch ids) the proposal rests on." }, "dedupe_key": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "accepted", "dismissed", "expired", "merged" ] }, "resolved_by": { "type": [ "string", "null" ] }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "result_item_id": { "type": [ "string", "null" ], "format": "uuid" }, "expires_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "coalesce_key": { "type": [ "string", "null" ] }, "merged_into": { "type": [ "string", "null" ], "format": "uuid", "description": "On a `merged` row: the pending card that absorbed it." }, "merged_count": { "type": "integer", "description": "On a card: how many later proposals it absorbed." } } }, "created": { "type": "boolean" }, "merged": { "type": "boolean", "description": "This proposal merged into an existing pending card (returned as `proposal`)." } } } } } }, "400": { "description": "Invalid input, or a move the state machine refuses (the message says why)." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Not a member of the scope, or a credential this route refuses (assistant, delegation, service)." }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_propose_Work", "resource_uri": "yf://agents/work", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/work/proposals -H 'Content-Type: application/json' -d '{}'" } ], "x-related": [ "acceptProposal_Work", "openRequest_Work", "queue_Work" ] } }, "/work/proposals/dismiss": { "post": { "operationId": "dismissMany_Work", "x-method": "POST", "x-path": "/work/proposals/dismiss", "x-handler": "dismiss_many", "tags": [ "Work" ], "summary": "Dismiss many proposals", "description": "Mounted only when the agents service runs with `AGENTS_WORK=on`; otherwise 404. The caller must be an active member of the scope group (`require_group_action`); deal rooms additionally require signed terms. Delegation and service tokens are refused on every `/work` route. `ids` empty means every pending proposal in the scope. An assistant credential (JWT `agent_id` or `mcp_agent_id`) may only propose and comment; every other mutation is refused to it with 403.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "scope_group_id" ], "properties": { "scope_group_id": { "type": "string", "format": "uuid" }, "ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "dismissed": { "type": "integer" } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Not a member of the scope, or a credential this route refuses (assistant, delegation, service)." }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_dismissMany_Work", "resource_uri": "yf://agents/work", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/work/proposals/dismiss -H 'Content-Type: application/json' -d '{}'" } ], "x-related": [] } }, "/work/proposals/{id}/accept": { "post": { "operationId": "acceptProposal_Work", "x-method": "POST", "x-path": "/work/proposals/{id}/accept", "x-handler": "accept_proposal", "tags": [ "Work" ], "summary": "Accept a proposal (a person)", "description": "Mounted only when the agents service runs with `AGENTS_WORK=on`; otherwise 404. The caller must be an active member of the scope group (`require_group_action`); deal rooms additionally require signed terms. Delegation and service tokens are refused on every `/work` route. Applies the payload under the ACCEPTING person in one transaction; the result carries `origin='agent'` and the event names the acceptor, the agent and who it acted for. An assistant credential (JWT `agent_id` or `mcp_agent_id`) may only propose and comment; every other mutation is refused to it with 403.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The item's (or proposal's) id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "proposal": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "scope_group_id": { "type": "string", "format": "uuid" }, "proposer_agent_id": { "type": "string" }, "on_behalf_of": { "type": "string" }, "action": { "type": "string", "enum": [ "create", "link" ] }, "target_item_id": { "type": [ "string", "null" ], "format": "uuid" }, "payload": { "type": "object", "description": "For `create`: a NewItem. For `link`: a NewLink." }, "rationale": { "type": "string", "maxLength": 300 }, "provenance": { "type": "array", "items": { "type": "string" }, "description": "Opaque ids (Javier `MSG:`/`THREAD:` fetch ids) the proposal rests on." }, "dedupe_key": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "accepted", "dismissed", "expired" ] }, "resolved_by": { "type": [ "string", "null" ] }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "result_item_id": { "type": [ "string", "null" ], "format": "uuid" }, "expires_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "item": { "type": "object", "description": "A work item (`work::model::WorkItem`).", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string", "example": "W-42" }, "scope_group_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "epic", "task", "bug", "story", "investigation", "wish" ] }, "is_outcome": { "type": "boolean" }, "title": { "type": "string" }, "body": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "in_progress", "blocked", "in_review", "done", "cancelled" ] }, "pre_block_status": { "type": [ "string", "null" ] }, "status_changed_at": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "description": "Optimistic-concurrency version; every write bumps it." }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "assignee_entity_id": { "type": [ "string", "null" ] }, "reporter_entity_id": { "type": "string" }, "parent_id": { "type": [ "string", "null" ], "format": "uuid" }, "position": { "type": "integer" }, "hill_position": { "type": "integer", "minimum": 0, "maximum": 100 }, "labels": { "type": "array", "items": { "type": "string" } }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "due_tz": { "type": [ "string", "null" ] }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "thread_id": { "type": [ "string", "null" ], "format": "uuid" }, "requires_evidence": { "type": "boolean" }, "origin": { "type": "string", "enum": [ "person", "agent", "rule" ], "description": "Who decided this exists — derived from the credential, never from the payload." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Invalid input, or a move the state machine refuses (the message says why)." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Not a member of the scope, or a credential this route refuses (assistant, delegation, service)." }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_acceptProposal_Work", "resource_uri": "yf://agents/work", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/work/proposals/{id}/accept -H 'Content-Type: application/json' -d '{}'" } ], "x-related": [] } }, "/work/proposals/{id}/dismiss": { "post": { "operationId": "dismissProposal_Work", "x-method": "POST", "x-path": "/work/proposals/{id}/dismiss", "x-handler": "dismiss_proposal", "tags": [ "Work" ], "summary": "Dismiss a proposal (a person)", "description": "Mounted only when the agents service runs with `AGENTS_WORK=on`; otherwise 404. The caller must be an active member of the scope group (`require_group_action`); deal rooms additionally require signed terms. Delegation and service tokens are refused on every `/work` route. An assistant credential (JWT `agent_id` or `mcp_agent_id`) may only propose and comment; every other mutation is refused to it with 403.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The item's (or proposal's) id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "scope_group_id": { "type": "string", "format": "uuid" }, "proposer_agent_id": { "type": "string" }, "on_behalf_of": { "type": "string" }, "action": { "type": "string", "enum": [ "create", "link" ] }, "target_item_id": { "type": [ "string", "null" ], "format": "uuid" }, "payload": { "type": "object", "description": "For `create`: a NewItem. For `link`: a NewLink." }, "rationale": { "type": "string", "maxLength": 300 }, "provenance": { "type": "array", "items": { "type": "string" }, "description": "Opaque ids (Javier `MSG:`/`THREAD:` fetch ids) the proposal rests on." }, "dedupe_key": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "accepted", "dismissed", "expired" ] }, "resolved_by": { "type": [ "string", "null" ] }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "result_item_id": { "type": [ "string", "null" ], "format": "uuid" }, "expires_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Invalid input, or a move the state machine refuses (the message says why)." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Not a member of the scope, or a credential this route refuses (assistant, delegation, service)." }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_dismissProposal_Work", "resource_uri": "yf://agents/work", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/work/proposals/{id}/dismiss -H 'Content-Type: application/json' -d '{}'" } ], "x-related": [] } }, "/work/queue/mine": { "get": { "operationId": "queue_Work", "x-method": "GET", "x-path": "/work/queue/mine", "x-handler": "queue", "tags": [ "Work" ], "summary": "The caller's queue: what waits on them and what they wait on", "description": "Mounted only when the agents service runs with `AGENTS_WORK=on`; otherwise 404. A per-person projection over the record (spec A1.1), computed in ONE SQL query, never assembled in memory. Sources: pending proposals filed for the caller (`decide`), open requests addressed to them (`answer`, `approve`, `accept`), unanswered `needs_answer` comments on items assigned to them (`answer`), their own open items that are overdue, due within seven days, urgent or blocked (`do`), and open requests they filed (`waiting`). With `scope`, one workspace (gated like any other read); without it, every workspace the caller can read — the SQL carries the same membership-and-terms predicate the per-scope gate applies (active member; in a deal room, the owner or a member who signed). Ordered: overdue and due today, then urgent, then waiting on me grouped by who waits, then the rest. Snoozed entries are omitted unless `include_snoozed`. An assistant credential may read its person's queue.", "parameters": [ { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "include_snoozed", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 200 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "entry_key": { "type": "string", "description": "Stable key for snoozing: `proposal:`, `request:`, `comment:`, `item:`." }, "kind": { "type": "string", "enum": [ "decide", "answer", "approve", "accept", "do", "waiting" ] }, "scope_group_id": { "type": "string", "format": "uuid" }, "scope_name": { "type": "string" }, "item_id": { "type": [ "string", "null" ], "format": "uuid" }, "item_key": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "detail": { "type": [ "string", "null" ] }, "who": { "type": [ "string", "null" ], "description": "Who waits, or who is waited on." }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "priority": { "type": [ "string", "null" ] }, "rank": { "type": "integer", "description": "0 overdue or due today · 1 urgent · 2 waiting on me · 3 the rest." }, "proposal_id": { "type": [ "string", "null" ], "format": "uuid" }, "request_id": { "type": [ "string", "null" ], "format": "uuid" }, "snoozed_until": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } } } } } }, "400": { "description": "Invalid input, or a move the state machine refuses (the message says why)." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Not a member of the scope, or a credential this route refuses (assistant, delegation, service)." }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_queue_Work", "resource_uri": "yf://agents/work", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/work/queue/mine?scope=" } ], "x-related": [ "snooze_Work", "attention_Work" ] } }, "/work/queue/snooze": { "post": { "operationId": "snooze_Work", "x-method": "POST", "x-path": "/work/queue/snooze", "x-handler": "snooze", "tags": [ "Work" ], "summary": "Snooze a queue entry (persons only)", "description": "Mounted only when the agents service runs with `AGENTS_WORK=on`; otherwise 404. Snooze is the queue's only stored state, keyed by the caller and the entry key; `until: null` clears it. Refused for assistant credentials: an assistant cannot hide things from the person it works for.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "entry_key" ], "properties": { "entry_key": { "type": "string", "maxLength": 128 }, "until": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "entry_key": { "type": "string" }, "until": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "400": { "description": "Invalid input, or a move the state machine refuses (the message says why)." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Not a member of the scope, or a credential this route refuses (assistant, delegation, service)." }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_snooze_Work", "resource_uri": "yf://agents/work", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/work/queue/snooze -H 'Content-Type: application/json' -d '{\"entry_key\":\"request:\",\"until\":\"2026-09-05T09:00:00Z\"}'" } ], "x-related": [ "queue_Work" ] } }, "/work/requests/{id}/cancel": { "post": { "operationId": "cancelRequest_Work", "x-method": "POST", "x-path": "/work/requests/{id}/cancel", "x-handler": "cancel_request", "tags": [ "Work" ], "summary": "Withdraw a request you filed (persons only)", "description": "Mounted only when the agents service runs with `AGENTS_WORK=on`; otherwise 404. Scope is derived from the row and the caller is gated on it (`require_group_action`; deal rooms additionally require signed terms). Delegation and service tokens are refused on every `/work` route. Only the requester may cancel an open request. An approval's hold on the item is released with it. Records a `request_cancelled` event.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "scope_group_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "question", "approval", "handoff" ] }, "from_entity_id": { "type": "string" }, "to_entity_id": { "type": "string" }, "body": { "type": "string" }, "payload": { "type": "object", "description": "approval: `{ to, reason }` — the move the approver releases." }, "status": { "type": "string", "enum": [ "open", "answered", "approved", "declined", "accepted", "cancelled" ] }, "response": { "type": [ "string", "null" ] }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "origin": { "type": "string", "enum": [ "person", "agent", "rule" ] }, "resolved_by": { "type": [ "string", "null" ] }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Invalid input, or a move the state machine refuses (the message says why)." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Not a member of the scope, or a credential this route refuses (assistant, delegation, service)." }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_cancelRequest_Work", "resource_uri": "yf://agents/work", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/work/requests/{id}/cancel" } ], "x-related": [ "openRequest_Work" ] } }, "/work/requests/{id}/respond": { "post": { "operationId": "respondRequest_Work", "x-method": "POST", "x-path": "/work/requests/{id}/respond", "x-handler": "respond_request", "tags": [ "Work" ], "summary": "Resolve a request addressed to you (persons only)", "description": "Mounted only when the agents service runs with `AGENTS_WORK=on`; otherwise 404. Scope is derived from the row and the caller is gated on it (`require_group_action`; deal rooms additionally require signed terms). Delegation and service tokens are refused on every `/work` route. Only the person the request is addressed to may resolve it, in ONE transaction re-validated against the item as it stands now. `question` → `answer` (with `body`; the answer is also recorded as a comment on the item). `approval` → `approve` (applies the held move through the same guarded transition every move takes, releasing the hold) or `decline` (releases without moving). `handoff` → `accept` (the responder becomes the assignee) or `decline`. Records a `request_resolved` event. An assistant proposes a response (`propose_Work` with `action: respond`) that its person accepts.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "outcome" ], "properties": { "outcome": { "type": "string", "enum": [ "answer", "approve", "decline", "accept" ] }, "body": { "type": "string", "maxLength": 20000 } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "request": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "scope_group_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "question", "approval", "handoff" ] }, "from_entity_id": { "type": "string" }, "to_entity_id": { "type": "string" }, "body": { "type": "string" }, "payload": { "type": "object", "description": "approval: `{ to, reason }` — the move the approver releases." }, "status": { "type": "string", "enum": [ "open", "answered", "approved", "declined", "accepted", "cancelled" ] }, "response": { "type": [ "string", "null" ] }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "origin": { "type": "string", "enum": [ "person", "agent", "rule" ] }, "resolved_by": { "type": [ "string", "null" ] }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "item": { "type": "object", "description": "The item as it now stands (a WorkItem; see getItem_Work)." } } } } } }, "400": { "description": "Invalid input, or a move the state machine refuses (the message says why)." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Not a member of the scope, or a credential this route refuses (assistant, delegation, service)." }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_respondRequest_Work", "resource_uri": "yf://agents/work", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/work/requests/{id}/respond -H 'Content-Type: application/json' -d '{\"outcome\":\"approve\"}'" } ], "x-related": [ "openRequest_Work", "queue_Work" ] } }, "/workflow": { "post": { "operationId": "workflowHandler_Workflow", "x-method": "POST", "x-path": "/workflow", "x-handler": "handlers::workflow_handler", "tags": [ "Workflows" ], "summary": "Execute an ad-hoc YAML-defined workflow", "description": "Runs a transient workflow without first creating it in a working\ngroup. Supply either `workflow` (raw YAML body) or `workflow_file`\n(server-side path). The handler parses the YAML, runs it\nsynchronously, and returns the final `result`. There is no\npersistence, no DAG row, no SSE stream — for stateful workflows\nscoped to a group use `createWorkflow_Workflows`. Auth: bearer JWT.\n", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "input" ], "properties": { "workflow": { "type": [ "string", "null" ], "description": "Inline YAML workflow definition." }, "workflow_file": { "type": [ "string", "null" ], "description": "Path on the server's filesystem to a workflow YAML file. Exactly\none of `workflow` / `workflow_file` is required.\n" }, "input": { "type": "string", "description": "Input payload for the workflow. The runner serialises whatever\nthe workflow produces back into the response `result` field.\n" } } }, "examples": { "inline": { "summary": "Inline YAML workflow", "value": { "workflow": "name: example\nsteps:\n - id: hello\n agent: echo\n input: hi\n", "input": "hello world" } } } } } }, "responses": { "200": { "description": "Workflow executed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "properties": { "result": { "type": "string", "description": "Serialised final output produced by the workflow run." } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_workflowHandler_Workflow", "resource_uri": "yf://agents/workflow", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"workflow\":\"name: ex\\nsteps: []\",\"input\":\"\"}' \\\n https://agents.yieldfabric.com/workflow\n" } ], "x-related": [ { "operationId": "createWorkflow_Workflows", "relation": "alternative" }, { "guide": "workflows", "relation": "concept" } ] } }, "/workflow-templates": { "get": { "operationId": "listTemplates_WorkflowTemplates", "x-method": "GET", "x-path": "/workflow-templates", "x-handler": "wg::list_templates", "tags": [ "Workflow Templates" ], "summary": "List installed workflow templates", "description": "Returns a `WorkflowTemplateSummary` for every template registered in\nthe in-process template registry — both built-in templates and\nuser-saved ones. Use `getTemplate_WorkflowTemplates` to fetch the\nfull step DAG for one entry. Auth: bearer JWT.\n", "parameters": [], "responses": { "200": { "description": "Template summaries.", "content": { "application/json": { "schema": { "type": "object", "required": [ "templates" ], "properties": { "templates": { "type": "array", "items": { "type": "object", "description": "Lightweight listing form (omits full step definitions).", "required": [ "name", "display_name", "description", "version", "step_count", "roles" ], "properties": { "name": { "type": "string" }, "display_name": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "string" }, "category": { "type": [ "string", "null" ] }, "variables": { "type": "array", "items": { "type": "object", "required": [ "name", "label", "type" ], "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "description": "e.g. `string`, `enum`, `number`, `entity_id`." }, "options": { "type": "array", "items": { "type": "string" } }, "required": { "type": "boolean", "default": false }, "default": { "type": [ "string", "null" ] } } } }, "step_count": { "type": "integer", "minimum": 0 }, "roles": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listTemplates_WorkflowTemplates", "resource_uri": "yf://agents/workflow-templates", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/workflow-templates" } ], "x-related": [ { "operationId": "getTemplate_WorkflowTemplates", "relation": "child" }, { "operationId": "saveTemplate_WorkflowTemplates", "relation": "sibling" }, { "operationId": "instantiateTemplate_Workflows", "relation": "next-step" }, { "guide": "workflows", "relation": "concept" } ] }, "post": { "operationId": "saveTemplate_WorkflowTemplates", "x-method": "POST", "x-path": "/workflow-templates", "x-handler": "wg::save_template", "tags": [ "Workflow Templates" ], "summary": "Save a new (or overwrite an existing) workflow template", "description": "Persists a `WorkflowTemplate` into the in-process template registry\nunder the supplied `name`. `display_name` and `description` are\nshown in the picker UI; `category` lets the UI group templates;\n`steps` is the ordered template DAG. Auth: bearer JWT — the caller\nis recorded as the template's owner.\n", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "display_name", "steps" ], "properties": { "name": { "type": "string" }, "display_name": { "type": "string" }, "description": { "type": "string", "default": "" }, "category": { "type": [ "string", "null" ] }, "steps": { "type": "array", "items": { "type": "object", "required": [ "key", "name", "type" ], "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "description": "Primitive task type (`human_task`, `agent_task`, `approval_gate`,\n...).\n" }, "description": { "type": [ "string", "null" ] }, "config": { "description": "Arbitrary JSON value." }, "assignee_type": { "type": [ "string", "null" ], "enum": [ "entity", "role", "group", "originator", null ] }, "assignee_id": { "type": [ "string", "null" ] }, "depends_on": { "type": "array", "items": { "type": "string" } }, "input_bindings": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ], "description": "Optional input bindings declared in YAML. Format\n`{ \"field_name\": \"source_step.output_field\" }` — at instantiation\nthe dotted string is parsed into `[step_key, field_name]` arrays.\n" } } } } } }, "examples": { "minimal": { "summary": "Save a minimal one-step template", "value": { "name": "ack_notify", "display_name": "Acknowledge & notify", "description": "Single-step notification template", "category": "notification", "steps": [ { "key": "notify", "name": "Notify", "step_type": "notification", "config": { "channel": "chat" }, "depends_on": [] } ] } } } } } }, "responses": { "201": { "description": "Template saved.", "content": { "application/json": { "schema": { "type": "object", "required": [ "saved", "name" ], "properties": { "saved": { "type": "boolean" }, "name": { "type": "string" } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_saveTemplate_WorkflowTemplates", "resource_uri": "yf://agents/workflow-templates", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"ack_notify\",\"display_name\":\"Notify\",\"steps\":[]}' \\\n https://agents.yieldfabric.com/workflow-templates\n" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx\nr = httpx.post(\n \"https://agents.yieldfabric.com/workflow-templates\",\n headers={\"Authorization\": f\"Bearer {jwt}\"},\n json={\"name\": \"ack_notify\", \"display_name\": \"Notify\", \"steps\": []},\n)\nr.raise_for_status()\n" } ], "x-related": [ { "operationId": "listTemplates_WorkflowTemplates", "relation": "sibling" }, { "operationId": "getTemplate_WorkflowTemplates", "relation": "read-after-write" }, { "operationId": "instantiateTemplate_Workflows", "relation": "next-step" }, { "guide": "workflows", "relation": "concept" } ] } }, "/workflow-templates/{name}": { "get": { "operationId": "getTemplate_WorkflowTemplates", "x-method": "GET", "x-path": "/workflow-templates/{name}", "x-handler": "wg::get_template", "tags": [ "Workflow Templates" ], "summary": "Fetch a single workflow template by name", "description": "Returns the full `WorkflowTemplate` — name, display_name, description,\nversion, category, variable declarations, and the ordered step list.\nUsed by the pipeline-builder UI to render a template before\ninstantiation. Returns 404 if no template is registered under `{name}`.\nAuth: bearer JWT.\n", "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Template name (slug).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Template body.", "content": { "application/json": { "schema": { "type": "object", "description": "A reusable pipeline definition stored in the template registry.", "required": [ "name", "display_name", "description", "version", "steps" ], "properties": { "name": { "type": "string", "description": "Unique slug for lookup." }, "display_name": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "string", "default": "1.0" }, "category": { "type": [ "string", "null" ] }, "variables": { "type": "array", "items": { "type": "object", "required": [ "name", "label", "type" ], "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "description": "e.g. `string`, `enum`, `number`, `entity_id`." }, "options": { "type": "array", "items": { "type": "string" } }, "required": { "type": "boolean", "default": false }, "default": { "type": [ "string", "null" ] } } } }, "steps": { "type": "array", "items": { "type": "object", "required": [ "key", "name", "type" ], "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "description": "Primitive task type (`human_task`, `agent_task`, `approval_gate`,\n...).\n" }, "description": { "type": [ "string", "null" ] }, "config": { "description": "Arbitrary JSON value." }, "assignee_type": { "type": [ "string", "null" ], "enum": [ "entity", "role", "group", "originator", null ] }, "assignee_id": { "type": [ "string", "null" ] }, "depends_on": { "type": "array", "items": { "type": "string" } }, "input_bindings": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ], "description": "Optional input bindings declared in YAML. Format\n`{ \"field_name\": \"source_step.output_field\" }` — at instantiation\nthe dotted string is parsed into `[step_key, field_name]` arrays.\n" } } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getTemplate_WorkflowTemplates", "resource_uri": "yf://agents/workflow-templates", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/workflow-templates/bilateral_payment" } ], "x-related": [ { "operationId": "listTemplates_WorkflowTemplates", "relation": "sibling" }, { "operationId": "instantiateTemplate_Workflows", "relation": "next-step" }, { "guide": "workflows", "relation": "concept" } ] } }, "/workflows/{wid}/retry-setup": { "post": { "operationId": "retryWorkflowSetup_Workflows", "x-method": "POST", "x-path": "/workflows/{wid}/retry-setup", "x-handler": "wg::retry_workflow_setup", "tags": [ "Workflows" ], "summary": "Retry a stalled workflow's on-chain setup", "description": "Rechecks and, only when the prior registration attempt verifiably failed,\nretries on-chain PipelineGate setup for an already-running deal workflow.\nThe workflow's system working group is derived from the workflow row, so\ncallers do not need to know its id. The operation then re-arms the\nauto-execute loop, which does not survive a service restart.\n\nAny active deal party with `ViewWorkflows` may nudge setup; `StartWorkflow`\nis intentionally not required. The caller's own bearer token signs a real\nre-registration. The handler does not replace the workflow's stored\nactivator credential. Account preflight precedes stale registration-id\nclearing or re-registration. A missing account returns the flat\n`CHAIN_ACCOUNT_REQUIRED` 409 before either side effect. No request body.\n", "parameters": [ { "name": "wid", "in": "path", "required": true, "description": "Workflow instance id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Setup was checked/retried and the execution loop was re-armed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "retried" ], "properties": { "retried": { "type": "boolean", "const": true } } }, "example": { "retried": true } } } }, "400": { "description": "Workflow path id is not a UUID.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing or invalid bearer credential.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } }, "402": { "description": "Billing preflight denied the caller. The current handler emits a\ntext body containing a serialized object with `error`, one of the\nself-service billing `code` values, and `billing_url`; clients should\nnot assume a JSON content type on this compatibility path.\n", "content": { "text/plain": { "schema": { "type": "string" }, "example": "{\"error\":\"Add a payment method to continue\",\"code\":\"card_required\",\"billing_url\":\"/me/billing\"}" } } }, "403": { "description": "Caller is not an active member with `ViewWorkflows`.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Workflow not found.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "The effective user or group has no activated smart account on the\nauthenticated session's selected chain. The handler returns this before\nthe gated operation performs a durable write, submits MQ work, or starts\nan on-chain action. Activate the exact returned entity and chain, refresh\nthe same actor's session, then retry the original request once.\n", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "error", "code", "entity_kind", "entity_id", "chain_id", "operation" ], "properties": { "error": { "type": "string", "description": "Human-readable explanation. Branch on `code`, not this text." }, "code": { "type": "string", "const": "CHAIN_ACCOUNT_REQUIRED" }, "entity_kind": { "type": "string", "enum": [ "user", "group" ] }, "entity_id": { "type": "string", "minLength": 1 }, "chain_id": { "type": "string", "minLength": 1, "description": "Chain selected by the authenticated session." }, "operation": { "type": [ "string", "null" ], "description": "Stable operation label that required the account." } } }, "example": { "error": "A smart account must be activated on the selected chain before this operation can continue", "code": "CHAIN_ACCOUNT_REQUIRED", "entity_kind": "user", "entity_id": "usr_alice", "chain_id": "153", "operation": "start_workflow" } } } }, "500": { "description": "Workflow lookup, account preflight, registration, or recovery failed.", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_retryWorkflowSetup_Workflows", "resource_uri": "yf://agents/workflows/{wid}", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/workflows/$WORKFLOW_ID/retry-setup" } ], "x-related": [ { "operationId": "startWorkflow_Workflows", "relation": "recovery-for" }, { "operationId": "getWorkflow_Workflows", "relation": "status" } ] } }, "/working-groups": { "post": { "operationId": "createGroup_WorkingGroups", "x-method": "POST", "x-path": "/working-groups", "x-handler": "wg::create_group", "tags": [ "Working Groups" ], "summary": "Create a new working group", "description": "Provisions a new working group — the unit that scopes membership, threads,\nknowledge graphs, documents, workflows, and intents. The authenticated\ncaller becomes the group's first member with role `owner` and (when a\nlinked wallet header is present) has their on-chain address recorded so\nlater workflows can dispatch signer steps. Normal groups default to the\nbuilt-in General Economy when `economy_id` is omitted, while callers can\nstill pass a specialized economy explicitly.\n\n`idempotency_key` is optional but strongly recommended for consumer flows.\nIt is scoped to the authenticated creator. Retrying the same normalized body\nwith the same key returns the original group, including after a committed\nresponse is lost. Reusing the key with different fields returns 409 without\ncreating another group. Auth: bearer JWT.\n", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "purpose": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "economy_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Link this group to a registered economy. When omitted for a normal\nworkspace, the service defaults the group to the built-in General\nEconomy; DM/system-style groups may intentionally remain economy-less.\n" }, "idempotency_key": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Optional retry identity scoped to the authenticated creator. Replaying\nthe same key with the same normalized request returns the original\nworking group. Reusing it with different request fields returns 409.\n" }, "settings": { "type": "object", "description": "Group-level configuration knobs.", "properties": { "max_members": { "type": [ "integer", "null" ], "minimum": 1 }, "lightweight": { "type": "boolean", "default": false, "description": "When true, skip KG extraction, deal analysis, and proactive agent\nreplies for this group. Used by DM groups.\n" }, "kind": { "type": [ "string", "null" ], "description": "Workspace category. `personal` flags a notebook-backing personal\nworkspace (one per user, sole member, not discoverable in group\nlistings, not invite-able). Absent / null for regular team groups.\n" }, "billing_group_only": { "type": "boolean", "default": false, "description": "The bound auth group currently provides billing only, without a shared wallet." }, "ai_minute_usd": { "type": [ "number", "null" ], "minimum": 0, "description": "Optional group-level USD price per agent-minute." }, "agent_ai_rates": { "type": [ "object", "null" ], "additionalProperties": { "type": "number", "minimum": 0 }, "description": "Normalized agent billing id to USD-per-agent-minute override." } } } } }, "examples": { "minimal": { "summary": "Minimal — name only", "value": { "name": "Demo treasury group" } }, "full": { "summary": "Full request with economy + settings", "value": { "name": "ACME Treasury", "description": "Cross-functional treasury working group", "purpose": "Manage USDC settlement flows", "category": "team", "economy_id": "9d2c1f1a-3e84-4b0d-9c19-cd5b5e9a1c8c", "settings": { "max_members": 20, "lightweight": false } } } } } } }, "responses": { "200": { "description": "Group created or idempotently replayed. Body is the original `WorkingGroup` row.", "content": { "application/json": { "schema": { "type": "object", "description": "A working group is the unit of collaboration in the YieldFabric agents\nservice. It scopes membership, threads, knowledge graphs, documents,\nworkflows, intents, and federation policies.\n", "required": [ "id", "name", "category", "status", "settings", "created_by", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "purpose": { "type": [ "string", "null" ] }, "category": { "type": "string", "description": "Marker for the workspace kind. `team` (or absent) is a normal\nmulti-member group; `dm` is a 2-party direct message group.\n" }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "settings": { "type": "object", "description": "Group-level configuration knobs.", "properties": { "max_members": { "type": [ "integer", "null" ], "minimum": 1 }, "lightweight": { "type": "boolean", "default": false, "description": "When true, skip KG extraction, deal analysis, and proactive agent\nreplies for this group. Used by DM groups.\n" }, "kind": { "type": [ "string", "null" ], "description": "Workspace category. `personal` flags a notebook-backing personal\nworkspace (one per user, sole member, not discoverable in group\nlistings, not invite-able). Absent / null for regular team groups.\n" }, "billing_group_only": { "type": "boolean", "default": false, "description": "The bound auth group currently provides billing only, without a shared wallet." }, "ai_minute_usd": { "type": [ "number", "null" ], "minimum": 0, "description": "Optional group-level USD price per agent-minute." }, "agent_ai_rates": { "type": [ "object", "null" ], "additionalProperties": { "type": "number", "minimum": 0 }, "description": "Normalized agent billing id to USD-per-agent-minute override." } } }, "created_by": { "type": "string", "description": "entity_id of the group creator." }, "economy_id": { "type": [ "string", "null" ], "format": "uuid" }, "auth_group_id": { "type": [ "string", "null" ], "description": "Auth-service group bound to this workspace, or null before billing / shared-wallet configuration." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "409": { "description": "Conflicting state (e.g. step already completed, intent already cancelled, duplicate idempotency key with different body).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_createGroup_WorkingGroups", "resource_uri": "yf://agents/working-groups", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"ACME Treasury\",\"category\":\"team\",\"idempotency_key\":\"550e8400-e29b-41d4-a716-446655440000\"}' \\\n https://agents.yieldfabric.com/working-groups\n" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx\nr = httpx.post(\n \"https://agents.yieldfabric.com/working-groups\",\n headers={\"Authorization\": f\"Bearer {jwt}\"},\n json={\n \"name\": \"ACME Treasury\",\n \"category\": \"team\",\n \"idempotency_key\": \"550e8400-e29b-41d4-a716-446655440000\",\n },\n)\nr.raise_for_status()\ngroup = r.json()\n" } ], "x-related": [ { "operationId": "listGroups_WorkingGroups", "relation": "sibling" }, { "operationId": "getGroup_WorkingGroups", "relation": "read-after-write" }, { "operationId": "addMember_Members", "relation": "next-step" }, { "guide": "working-groups", "relation": "concept" } ] }, "get": { "operationId": "listGroups_WorkingGroups", "x-method": "GET", "x-path": "/working-groups", "x-handler": "wg::list_groups", "tags": [ "Working Groups" ], "summary": "List working groups the caller belongs to", "description": "Returns every active working group where the authenticated caller is a\nmember, omitting personal notebook workspaces (those are an implementation\ndetail of the notebook surface, not teams the user joined). The handler\nalso backfills membership rows for any pipeline whose steps name the\ncaller as an assignee — so a user invited only via a workflow step still\nsees the group here. Auth: bearer JWT.\n", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "groups" ], "properties": { "groups": { "type": "array", "items": { "type": "object", "description": "A working group is the unit of collaboration in the YieldFabric agents\nservice. It scopes membership, threads, knowledge graphs, documents,\nworkflows, intents, and federation policies.\n", "required": [ "id", "name", "category", "status", "settings", "created_by", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "purpose": { "type": [ "string", "null" ] }, "category": { "type": "string", "description": "Marker for the workspace kind. `team` (or absent) is a normal\nmulti-member group; `dm` is a 2-party direct message group.\n" }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "settings": { "type": "object", "description": "Group-level configuration knobs.", "properties": { "max_members": { "type": [ "integer", "null" ], "minimum": 1 }, "lightweight": { "type": "boolean", "default": false, "description": "When true, skip KG extraction, deal analysis, and proactive agent\nreplies for this group. Used by DM groups.\n" }, "kind": { "type": [ "string", "null" ], "description": "Workspace category. `personal` flags a notebook-backing personal\nworkspace (one per user, sole member, not discoverable in group\nlistings, not invite-able). Absent / null for regular team groups.\n" }, "billing_group_only": { "type": "boolean", "default": false, "description": "The bound auth group currently provides billing only, without a shared wallet." }, "ai_minute_usd": { "type": [ "number", "null" ], "minimum": 0, "description": "Optional group-level USD price per agent-minute." }, "agent_ai_rates": { "type": [ "object", "null" ], "additionalProperties": { "type": "number", "minimum": 0 }, "description": "Normalized agent billing id to USD-per-agent-minute override." } } }, "created_by": { "type": "string", "description": "entity_id of the group creator." }, "economy_id": { "type": [ "string", "null" ], "format": "uuid" }, "auth_group_id": { "type": [ "string", "null" ], "description": "Auth-service group bound to this workspace, or null before billing / shared-wallet configuration." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listGroups_WorkingGroups", "resource_uri": "yf://agents/working-groups", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups" } ], "x-related": [ { "operationId": "createGroup_WorkingGroups", "relation": "sibling" }, { "operationId": "getGroup_WorkingGroups", "relation": "child" }, { "guide": "working-groups", "relation": "concept" } ] } }, "/working-groups/deal-workspace": { "post": { "operationId": "ensureDealWorkspace_WorkingGroups", "x-method": "POST", "x-path": "/working-groups/deal-workspace", "x-handler": "wg::ensure_deal_workspace", "tags": [ "Working Groups" ], "summary": "Ensure the shared workspace for a DMS deal draft", "description": "Idempotently finds or creates the collaboration workspace identified by\n`draft_id`, ensures the caller is its owner, upserts the supplied members,\nand returns the canonical shared deal thread. Repeating the request for the\nsame draft returns the existing group and thread rather than creating a\nparallel workspace. Auth: bearer JWT.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "draft_id" ], "properties": { "draft_id": { "type": "string", "minLength": 1, "description": "Stable DMS draft identifier used as the idempotency identity." }, "title": { "type": [ "string", "null" ] }, "members": { "type": "array", "items": { "type": "object", "required": [ "entity_id" ], "properties": { "entity_id": { "type": "string", "minLength": 1 }, "display_name": { "type": [ "string", "null" ] }, "role": { "type": [ "string", "null" ], "description": "Membership role; defaults to `member` when omitted." } } }, "default": [] } } }, "examples": { "shared-draft": { "value": { "draft_id": "draft-2026-00042", "title": "Acquisition facility", "members": [ { "entity_id": "user:reviewer", "display_name": "Credit reviewer", "role": "member" } ] } } } } } }, "responses": { "200": { "description": "Canonical workspace and shared deal thread.", "content": { "application/json": { "schema": { "type": "object", "required": [ "group", "thread" ], "properties": { "group": { "type": "object", "description": "A working group is the unit of collaboration in the YieldFabric agents\nservice. It scopes membership, threads, knowledge graphs, documents,\nworkflows, intents, and federation policies.\n", "required": [ "id", "name", "category", "status", "settings", "created_by", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "purpose": { "type": [ "string", "null" ] }, "category": { "type": "string", "description": "Marker for the workspace kind. `team` (or absent) is a normal\nmulti-member group; `dm` is a 2-party direct message group.\n" }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "settings": { "type": "object", "description": "Group-level configuration knobs.", "properties": { "max_members": { "type": [ "integer", "null" ], "minimum": 1 }, "lightweight": { "type": "boolean", "default": false, "description": "When true, skip KG extraction, deal analysis, and proactive agent\nreplies for this group. Used by DM groups.\n" }, "kind": { "type": [ "string", "null" ], "description": "Workspace category. `personal` flags a notebook-backing personal\nworkspace (one per user, sole member, not discoverable in group\nlistings, not invite-able). Absent / null for regular team groups.\n" }, "billing_group_only": { "type": "boolean", "default": false, "description": "The bound auth group currently provides billing only, without a shared wallet." }, "ai_minute_usd": { "type": [ "number", "null" ], "minimum": 0, "description": "Optional group-level USD price per agent-minute." }, "agent_ai_rates": { "type": [ "object", "null" ], "additionalProperties": { "type": "number", "minimum": 0 }, "description": "Normalized agent billing id to USD-per-agent-minute override." } } }, "created_by": { "type": "string", "description": "entity_id of the group creator." }, "economy_id": { "type": [ "string", "null" ], "format": "uuid" }, "auth_group_id": { "type": [ "string", "null" ], "description": "Auth-service group bound to this workspace, or null before billing / shared-wallet configuration." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } }, "thread": { "type": "object", "description": "A conversation thread inside a working group.", "required": [ "id", "group_id", "title", "thread_type", "status", "created_by", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "group_id": { "type": "string", "format": "uuid" }, "parent_thread_id": { "type": [ "string", "null" ], "format": "uuid", "description": "When this is a subthread (e.g. a Weaver private chat), the\nparent's id. `null` for top-level threads.\n" }, "private_to_entity_id": { "type": [ "string", "null" ], "description": "When set, this thread is visible only to the named entity.\nCombined with `parent_thread_id` makes a per-user private\nsubthread.\n" }, "title": { "type": "string" }, "thread_type": { "type": "string", "description": "Discriminator for what the thread is used for.\n", "enum": [ "discussion", "reasoning", "pipeline_main", "pipeline_task", "team_chat", "dm", "weaver", "solo_chat", "notebook_entity", "deal_composer", "deal_shared" ] }, "reference_id": { "type": [ "string", "null" ], "description": "Optional pointer to an external entity (workflow id, frame id,\nWeaver root, etc.). Format depends on `thread_type`.\n" }, "status": { "type": "string", "enum": [ "active", "closed" ] }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } } } }, "400": { "description": "The `draft_id` is blank or the JSON body is malformed." }, "401": { "description": "Missing or invalid bearer credential." }, "500": { "description": "Workspace, membership, or thread persistence failed." } }, "x-mcp": { "tool_name": "yieldfabric_agents_ensureDealWorkspace_WorkingGroups", "resource_uri": "yf://agents/working-groups", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST https://agents.yieldfabric.com/working-groups/deal-workspace \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"draft_id\":\"draft-2026-00042\",\"title\":\"Acquisition facility\",\"members\":[]}'\n" } ], "x-related": [ { "operationId": "ensureDealComposerThread_WorkingGroups", "relation": "related" } ] } }, "/working-groups/{id}": { "get": { "operationId": "getGroup_WorkingGroups", "x-method": "GET", "x-path": "/working-groups/{id}", "x-handler": "wg::get_group", "tags": [ "Working Groups" ], "summary": "Fetch a single working group", "description": "Returns the full `WorkingGroup` row — name, description, purpose,\ncategory, status, settings, creator, optional `economy_id`, and\ntimestamps — for one group. Auth: bearer JWT; the caller must be an\nactive member of the group (the `ViewGroup` capability is enforced by\n`authorize`). Returns 404 if the group does not exist or is archived.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "description": "A working group is the unit of collaboration in the YieldFabric agents\nservice. It scopes membership, threads, knowledge graphs, documents,\nworkflows, intents, and federation policies.\n", "required": [ "id", "name", "category", "status", "settings", "created_by", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "purpose": { "type": [ "string", "null" ] }, "category": { "type": "string", "description": "Marker for the workspace kind. `team` (or absent) is a normal\nmulti-member group; `dm` is a 2-party direct message group.\n" }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "settings": { "type": "object", "description": "Group-level configuration knobs.", "properties": { "max_members": { "type": [ "integer", "null" ], "minimum": 1 }, "lightweight": { "type": "boolean", "default": false, "description": "When true, skip KG extraction, deal analysis, and proactive agent\nreplies for this group. Used by DM groups.\n" }, "kind": { "type": [ "string", "null" ], "description": "Workspace category. `personal` flags a notebook-backing personal\nworkspace (one per user, sole member, not discoverable in group\nlistings, not invite-able). Absent / null for regular team groups.\n" }, "billing_group_only": { "type": "boolean", "default": false, "description": "The bound auth group currently provides billing only, without a shared wallet." }, "ai_minute_usd": { "type": [ "number", "null" ], "minimum": 0, "description": "Optional group-level USD price per agent-minute." }, "agent_ai_rates": { "type": [ "object", "null" ], "additionalProperties": { "type": "number", "minimum": 0 }, "description": "Normalized agent billing id to USD-per-agent-minute override." } } }, "created_by": { "type": "string", "description": "entity_id of the group creator." }, "economy_id": { "type": [ "string", "null" ], "format": "uuid" }, "auth_group_id": { "type": [ "string", "null" ], "description": "Auth-service group bound to this workspace, or null before billing / shared-wallet configuration." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getGroup_WorkingGroups", "resource_uri": "yf://agents/working-groups", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/{id}" } ], "x-related": [ { "operationId": "updateGroup_WorkingGroups", "relation": "sibling" }, { "operationId": "archiveGroup_WorkingGroups", "relation": "sibling" }, { "operationId": "listMembers_Members", "relation": "child" }, { "guide": "working-groups", "relation": "concept" } ] }, "patch": { "operationId": "updateGroup_WorkingGroups", "x-method": "PATCH", "x-path": "/working-groups/{id}", "x-handler": "wg::update_group", "tags": [ "Working Groups" ], "summary": "Update mutable working-group metadata", "description": "Patches the metadata of a working group — `name`, `description`,\n`purpose`, and `settings` (max_members, lightweight flag, workspace\nkind). Any omitted field is left untouched. Auth: bearer JWT; caller\nmust hold the `ManageGroup` capability (owner or admin role). Returns\n`{ \"updated\": true }` on success.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "purpose": { "type": [ "string", "null" ] }, "settings": { "type": "object", "description": "Group-level configuration knobs.", "properties": { "max_members": { "type": [ "integer", "null" ], "minimum": 1 }, "lightweight": { "type": "boolean", "default": false, "description": "When true, skip KG extraction, deal analysis, and proactive agent\nreplies for this group. Used by DM groups.\n" }, "kind": { "type": [ "string", "null" ], "description": "Workspace category. `personal` flags a notebook-backing personal\nworkspace (one per user, sole member, not discoverable in group\nlistings, not invite-able). Absent / null for regular team groups.\n" }, "billing_group_only": { "type": "boolean", "default": false, "description": "The bound auth group currently provides billing only, without a shared wallet." }, "ai_minute_usd": { "type": [ "number", "null" ], "minimum": 0, "description": "Optional group-level USD price per agent-minute." }, "agent_ai_rates": { "type": [ "object", "null" ], "additionalProperties": { "type": "number", "minimum": 0 }, "description": "Normalized agent billing id to USD-per-agent-minute override." } } } } }, "examples": { "rename": { "summary": "Rename the group", "value": { "name": "ACME Treasury (Renamed)" } }, "settings": { "summary": "Tighten settings", "value": { "settings": { "max_members": 12, "lightweight": false } } } } } } }, "responses": { "200": { "description": "Group fields updated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "updated" ], "properties": { "updated": { "type": "boolean" } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_updateGroup_WorkingGroups", "resource_uri": "yf://agents/working-groups", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PATCH -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"description\":\"updated team purpose\"}' \\\n https://agents.yieldfabric.com/working-groups/{id}\n" } ], "x-related": [ { "operationId": "getGroup_WorkingGroups", "relation": "sibling" }, { "operationId": "archiveGroup_WorkingGroups", "relation": "sibling" }, { "guide": "working-groups", "relation": "concept" } ] }, "delete": { "operationId": "archiveGroup_WorkingGroups", "x-method": "DELETE", "x-path": "/working-groups/{id}", "x-handler": "wg::archive_group", "tags": [ "Working Groups" ], "summary": "Archive a working group (soft-delete)", "description": "Soft-deletes the working group — sets `status='archived'` on the row.\nThe group disappears from `listGroups` and from listings filtered by\nactive status; documents, threads, KGs, and workflow rows are preserved\nfor audit. Auth: bearer JWT; caller must hold the `ArchiveGroup`\ncapability (owner only). Idempotent — archiving an already-archived\ngroup succeeds with `{ \"archived\": true }`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Group archived.", "content": { "application/json": { "schema": { "type": "object", "required": [ "archived" ], "properties": { "archived": { "type": "boolean" } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_archiveGroup_WorkingGroups", "resource_uri": "yf://agents/working-groups", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X DELETE -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/{id}" } ], "x-related": [ { "operationId": "updateGroup_WorkingGroups", "relation": "sibling" }, { "guide": "working-groups", "relation": "concept" } ] } }, "/working-groups/{id}/agent_memory/{agent_id}": { "get": { "operationId": "listWgAgentMemory_WorkingGroups", "x-method": "GET", "x-path": "/working-groups/{id}/agent_memory/{agent_id}", "x-handler": "handlers::agent_registry::list_wg_agent_memory", "tags": [ "Working Groups" ], "summary": "List an agent's working-group-scoped memory entries", "description": "Requires a caller-visible agent. Reads and writes address only the verified\ncaller's private memory partition, including when the agent spec is shared.\nThe caller must also be authorized for this KG or working group.\nReturns every memory row stored under `(working_group_id, agent_id)`.\nWorking-group-scoped memory is the durable store agents use to retain\nstate that's specific to one team (decisions, preferences, last-seen\ncursors). Personal-agent rows (those keyed to a single user) are not\nreturned here — use the per-user notebook surface instead. Auth: bearer\nJWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "agent_id", "in": "path", "required": true, "description": "Agent id (slug or UUID).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of `MemoryRow` entries.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "One memory entry scoped to a (working_group, agent) pair.", "required": [ "agent_id", "key", "value" ], "properties": { "agent_id": { "type": "string" }, "key": { "type": "string" }, "value": { "description": "Arbitrary JSON value." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listWgAgentMemory_WorkingGroups", "resource_uri": "yf://agents/working-groups", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/{id}/agent_memory/{agent_id}" } ], "x-related": [ { "operationId": "putWgAgentMemory_WorkingGroups", "relation": "sibling" }, { "operationId": "deleteWgAgentMemory_WorkingGroups", "relation": "sibling" }, { "guide": "working-groups", "relation": "concept" } ] }, "post": { "operationId": "putWgAgentMemory_WorkingGroups", "x-method": "POST", "x-path": "/working-groups/{id}/agent_memory/{agent_id}", "x-handler": "handlers::agent_registry::put_wg_agent_memory", "tags": [ "Working Groups" ], "summary": "Write (upsert) a working-group-scoped agent memory entry", "description": "Requires a caller-visible agent. Reads and writes address only the verified\ncaller's private memory partition, including when the agent spec is shared.\nThe caller must also be authorized for this KG or working group.\nWrites a single `MemoryEntry` for `(working_group_id, agent_id)`. Uses\nupsert semantics — the same `key` overwrites the prior `value`,\npreserving the row's creation timestamp. Returns `204 No Content`. The\npayload is the typed `MemoryEntry` from the agents memory layer\n(`crate::agents::memory::MemoryEntry`). Auth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "agent_id", "in": "path", "required": true, "description": "Agent id (slug or UUID).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string" }, "value": { "description": "Arbitrary JSON value." } } }, "examples": { "minimal": { "summary": "Store a key/value note", "value": { "key": "last_seen_message_id", "value": { "message_id": "5d6b...", "ts": "2027-04-30T11:00:00Z" } } } } } } }, "responses": { "204": { "description": "Entry written. No body." }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_putWgAgentMemory_WorkingGroups", "resource_uri": "yf://agents/working-groups", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"key\":\"last_seen\",\"value\":{\"id\":\"abc\"}}' \\\n https://agents.yieldfabric.com/working-groups/{id}/agent_memory/{agent_id}\n" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx\nr = httpx.post(\n f\"https://agents.yieldfabric.com/working-groups/{gid}/agent_memory/{agent_id}\",\n headers={\"Authorization\": f\"Bearer {jwt}\"},\n json={\"key\": \"last_seen\", \"value\": {\"id\": \"abc\"}},\n)\nr.raise_for_status()\n" } ], "x-related": [ { "operationId": "listWgAgentMemory_WorkingGroups", "relation": "sibling" }, { "operationId": "deleteWgAgentMemory_WorkingGroups", "relation": "sibling" }, { "guide": "working-groups", "relation": "concept" } ] } }, "/working-groups/{id}/agent_memory/{agent_id}/{key}": { "delete": { "operationId": "deleteWgAgentMemory_WorkingGroups", "x-method": "DELETE", "x-path": "/working-groups/{id}/agent_memory/{agent_id}/{key}", "x-handler": "handlers::agent_registry::delete_wg_agent_memory", "tags": [ "Working Groups" ], "summary": "Delete one working-group-scoped agent memory entry", "description": "Requires a caller-visible agent. Reads and writes address only the verified\ncaller's private memory partition, including when the agent spec is shared.\nThe caller must also be authorized for this KG or working group.\nRemoves the memory row stored under `(working_group_id, agent_id, key)`.\nReturns `204 No Content` on success, `404` when no row was matched.\nAuth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "agent_id", "in": "path", "required": true, "description": "Agent id (slug or UUID).", "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "description": "Memory key.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Entry deleted. No body." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_deleteWgAgentMemory_WorkingGroups", "resource_uri": "yf://agents/working-groups", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X DELETE -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/{id}/agent_memory/{agent_id}/{key}" } ], "x-related": [ { "operationId": "listWgAgentMemory_WorkingGroups", "relation": "sibling" }, { "operationId": "putWgAgentMemory_WorkingGroups", "relation": "sibling" }, { "guide": "working-groups", "relation": "concept" } ] } }, "/working-groups/{id}/agents": { "get": { "operationId": "listAgents_AgentsInGroup", "x-method": "GET", "x-path": "/working-groups/{id}/agents", "x-handler": "wg::list_agents", "tags": [ "Agents" ], "summary": "List agents available inside a working group", "description": "Returns the agents available to this working group: locally-persisted\n`agents` rows merged with any economy-provided agents the operator\nexposes for the group. Economy agents are deduped against the local\nlist by `agent_key`. Each row carries the agent's role, expertise,\ncapabilities, persona settings, and provenance (`origin`: `user` or\n`economy`). Auth: bearer JWT; caller must hold `ViewMembers`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Merged agent list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "agents" ], "properties": { "agents": { "type": "array", "items": { "type": "object", "description": "A row from `agents` table — persistent agent scoped to a working\ngroup, plus the dynamic catalog entries the group's economy exposes.\n", "required": [ "id", "agent_key", "display_name", "role" ], "properties": { "id": { "type": "string", "format": "uuid" }, "agent_key": { "type": "string" }, "display_name": { "type": "string" }, "role": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "expertise": { "type": "array", "items": { "type": "string" } }, "focus": { "type": [ "string", "null" ] }, "personality": { "type": [ "string", "null" ] }, "capabilities": { "type": "array", "items": { "type": "string" } }, "tools": { "type": "array", "items": { "type": "string" } }, "instructions": { "type": [ "string", "null" ] }, "source": { "type": "string", "description": "e.g. `user`, `seed`, `economy`." }, "group_id": { "type": [ "string", "null" ], "format": "uuid" }, "economy_id": { "type": [ "string", "null" ], "format": "uuid" }, "enabled": { "type": "boolean", "default": true }, "sessions_participated": { "type": "integer", "default": 0 }, "created_by": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listAgents_AgentsInGroup", "resource_uri": "yf://agents/agents-in-group", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/{id}/agents" } ], "x-related": [ { "operationId": "createAgent_AgentsInGroup", "relation": "sibling" }, { "operationId": "getAgent_AgentsInGroup", "relation": "child" }, { "guide": "working-groups", "relation": "concept" } ] }, "post": { "operationId": "createAgent_AgentsInGroup", "x-method": "POST", "x-path": "/working-groups/{id}/agents", "x-handler": "wg::create_agent", "tags": [ "Agents" ], "summary": "Create a persistent agent scoped to this working group", "description": "Creates a `PersistentAgent` row scoped to the working group. The\nagent becomes selectable in `@mentions`, listed by\n`listAgents_AgentsInGroup`, and resolvable to a system prompt via\nthe agent execution layer. Provide an `agent_key` (slug),\n`display_name`, `role`, optional `expertise` array, `focus`,\n`capabilities`, and a list of tool ids. RAG access is enabled by\ndefault. Auth: bearer JWT; caller must hold `ManageMembers`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agent_key", "display_name", "role" ], "properties": { "agent_key": { "type": "string" }, "display_name": { "type": "string" }, "role": { "type": "string" }, "expertise": { "type": "array", "items": { "type": "string" } }, "focus": { "type": [ "string", "null" ] }, "capabilities": { "type": "array", "items": { "type": "string" } }, "tools": { "type": "array", "items": { "type": "string" } } } }, "examples": { "minimal": { "summary": "Minimal agent", "value": { "agent_key": "risk_reviewer", "display_name": "Risk Reviewer", "role": "analyst" } }, "full": { "summary": "Full definition with focus + tools", "value": { "agent_key": "deal_structurer", "display_name": "Deal Structurer", "role": "structurer", "expertise": [ "structured_credit", "securitisation" ], "focus": "Translate term sheets into pipeline drafts", "capabilities": [ "reasoning", "summarisation" ], "tools": [ "read_thread_messages", "rag_query" ] } } } } } }, "responses": { "201": { "description": "Agent created.", "content": { "application/json": { "schema": { "type": "object", "description": "A row from `agents` table — persistent agent scoped to a working\ngroup, plus the dynamic catalog entries the group's economy exposes.\n", "required": [ "id", "agent_key", "display_name", "role" ], "properties": { "id": { "type": "string", "format": "uuid" }, "agent_key": { "type": "string" }, "display_name": { "type": "string" }, "role": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "expertise": { "type": "array", "items": { "type": "string" } }, "focus": { "type": [ "string", "null" ] }, "personality": { "type": [ "string", "null" ] }, "capabilities": { "type": "array", "items": { "type": "string" } }, "tools": { "type": "array", "items": { "type": "string" } }, "instructions": { "type": [ "string", "null" ] }, "source": { "type": "string", "description": "e.g. `user`, `seed`, `economy`." }, "group_id": { "type": [ "string", "null" ], "format": "uuid" }, "economy_id": { "type": [ "string", "null" ], "format": "uuid" }, "enabled": { "type": "boolean", "default": true }, "sessions_participated": { "type": "integer", "default": 0 }, "created_by": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "409": { "description": "Conflicting state (e.g. step already completed, intent already cancelled, duplicate idempotency key with different body).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_createAgent_AgentsInGroup", "resource_uri": "yf://agents/agents-in-group", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"agent_key\":\"risk_reviewer\",\"display_name\":\"Risk Reviewer\",\"role\":\"analyst\"}' \\\n https://agents.yieldfabric.com/working-groups/{id}/agents\n" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx\nr = httpx.post(\n f\"https://agents.yieldfabric.com/working-groups/{gid}/agents\",\n headers={\"Authorization\": f\"Bearer {jwt}\"},\n json={\n \"agent_key\": \"risk_reviewer\",\n \"display_name\": \"Risk Reviewer\",\n \"role\": \"analyst\",\n },\n)\nr.raise_for_status()\n" } ], "x-related": [ { "operationId": "listAgents_AgentsInGroup", "relation": "sibling" }, { "operationId": "getAgent_AgentsInGroup", "relation": "read-after-write" }, { "operationId": "updateAgent_AgentsInGroup", "relation": "sibling" }, { "guide": "working-groups", "relation": "concept" } ] } }, "/working-groups/{id}/agents/{agent_id}/ai-rate": { "put": { "operationId": "setAgentAiRate_AgentsInGroup", "x-method": "PUT", "x-path": "/working-groups/{id}/agents/{agent_id}/ai-rate", "x-handler": "wg::set_agent_ai_rate", "tags": [ "Agents" ], "summary": "Set or clear one agent's group-specific AI rate", "description": "Sets the working-group owner's price for one agent in this group. This is\nthe most specific rate and takes precedence over both the agent definition\nand room rate. A null or omitted value removes the override. Values must be\nbetween 0 and 10 USD per agent-minute, inclusive, and at most 200 distinct\nper-agent overrides may be configured per group.\n\nThe path id is trimmed, a leading `agent:` prefix is removed, and the\nsentinel `__general__` normalizes to `general`; the normalized id is\nreturned. Auth: the group creator or an active owner/admin.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "agent_id", "in": "path", "required": true, "description": "Agent billing id; 1..200 characters after normalization.", "schema": { "type": "string", "minLength": 1, "maxLength": 206 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ai_minute_usd": { "type": [ "number", "null" ], "minimum": 0, "maximum": 10, "description": "USD per agent-minute. `null` selects the next fallback rate." } }, "description": "Omitting `ai_minute_usd` has the same clearing effect as `null`." }, "examples": { "set": { "value": { "ai_minute_usd": 0.8 } }, "clear": { "value": { "ai_minute_usd": null } } } } } }, "responses": { "200": { "description": "Persisted normalized agent override, or null after clearing.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "working_group_id", "agent_id", "ai_minute_usd" ], "properties": { "working_group_id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string" }, "ai_minute_usd": { "type": [ "number", "null" ], "minimum": 0, "maximum": 10, "description": "USD per agent-minute. `null` selects the next fallback rate." } } } } } }, "400": { "description": "Malformed working-group id or JSON body.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing or invalid bearer credential.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } }, "403": { "description": "Caller is not the creator or an active owner/admin.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Working group not found.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "422": { "description": "Agent id is empty/too long, rate is outside 0..10, or the group already has 200 other overrides.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Membership lookup or settings update failed.", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_setAgentAiRate_AgentsInGroup", "resource_uri": "yf://agents/working-groups/{id}/agents/{agent_id}/ai-rate", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PUT -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" -d '{\"ai_minute_usd\":0.8}' \\\n https://agents.yieldfabric.com/working-groups/$GROUP_ID/agents/$AGENT_ID/ai-rate\n" } ], "x-related": [ { "operationId": "getAiRate_WorkingGroups", "relation": "pricing-view" }, { "operationId": "setAiRate_WorkingGroups", "relation": "fallback" } ] } }, "/working-groups/{id}/agents/{aid}": { "get": { "operationId": "getAgent_AgentsInGroup", "x-method": "GET", "x-path": "/working-groups/{id}/agents/{aid}", "x-handler": "wg::get_agent", "tags": [ "Agents" ], "summary": "Fetch a single persistent agent", "description": "Returns the full `PersistentAgent` row by id — display name, role,\nexpertise, capabilities, tool grants, persona settings, and origin.\nOnly locally-persisted agents are addressable here; economy agents\nsurface only via `listAgents_AgentsInGroup`. Auth: bearer JWT;\ncaller must hold `ViewMembers`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "aid", "in": "path", "required": true, "description": "Agent id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Agent row.", "content": { "application/json": { "schema": { "type": "object", "description": "A row from `agents` table — persistent agent scoped to a working\ngroup, plus the dynamic catalog entries the group's economy exposes.\n", "required": [ "id", "agent_key", "display_name", "role" ], "properties": { "id": { "type": "string", "format": "uuid" }, "agent_key": { "type": "string" }, "display_name": { "type": "string" }, "role": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "expertise": { "type": "array", "items": { "type": "string" } }, "focus": { "type": [ "string", "null" ] }, "personality": { "type": [ "string", "null" ] }, "capabilities": { "type": "array", "items": { "type": "string" } }, "tools": { "type": "array", "items": { "type": "string" } }, "instructions": { "type": [ "string", "null" ] }, "source": { "type": "string", "description": "e.g. `user`, `seed`, `economy`." }, "group_id": { "type": [ "string", "null" ], "format": "uuid" }, "economy_id": { "type": [ "string", "null" ], "format": "uuid" }, "enabled": { "type": "boolean", "default": true }, "sessions_participated": { "type": "integer", "default": 0 }, "created_by": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getAgent_AgentsInGroup", "resource_uri": "yf://agents/agents-in-group", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/{id}/agents/{aid}" } ], "x-related": [ { "operationId": "updateAgent_AgentsInGroup", "relation": "sibling" }, { "operationId": "listAgents_AgentsInGroup", "relation": "sibling" }, { "guide": "working-groups", "relation": "concept" } ] }, "patch": { "operationId": "updateAgent_AgentsInGroup", "x-method": "PATCH", "x-path": "/working-groups/{id}/agents/{aid}", "x-handler": "wg::update_agent", "tags": [ "Agents" ], "summary": "Update an existing persistent agent", "description": "Patches mutable fields on a `PersistentAgent` row — display name,\nrole, persona settings, expertise, capabilities, tools, persona /\nmodel preferences. The body shape is `agents::store::AgentUpdate`,\nevery field optional. Returns `{ \"updated\": true|false }`. Auth:\nbearer JWT; caller must hold `ManageMembers`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "aid", "in": "path", "required": true, "description": "Agent id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Partial update — mirrors `agents::store::AgentUpdate`. All fields\noptional; the store uses a COALESCE pattern, so absent fields\npreserve prior values.\n", "properties": { "display_name": { "type": [ "string", "null" ] }, "role": { "type": [ "string", "null" ] }, "personality": { "type": [ "string", "null" ] }, "expertise": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "focus": { "type": [ "string", "null" ] }, "anti_focus": { "type": [ "string", "null" ] }, "reasoning_style": { "type": [ "string", "null" ] }, "topics": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "capabilities": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "tools": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "rag_access": { "type": [ "boolean", "null" ] }, "model_preference": { "type": [ "string", "null" ] }, "max_tokens": { "type": [ "integer", "null" ] }, "temperature": { "type": [ "number", "null" ] }, "system_prompt": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } } }, "examples": { "rename": { "summary": "Rename agent", "value": { "display_name": "Risk Reviewer (FX)" } }, "retune": { "summary": "Adjust persona tunables", "value": { "temperature": 0.4, "max_tokens": 1200 } } } } } }, "responses": { "200": { "description": "Update result.", "content": { "application/json": { "schema": { "type": "object", "required": [ "updated" ], "properties": { "updated": { "type": "boolean" } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_updateAgent_AgentsInGroup", "resource_uri": "yf://agents/agents-in-group", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PATCH -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"display_name\":\"Risk Reviewer (FX)\"}' \\\n https://agents.yieldfabric.com/working-groups/{id}/agents/{aid}\n" } ], "x-related": [ { "operationId": "getAgent_AgentsInGroup", "relation": "sibling" }, { "operationId": "createAgent_AgentsInGroup", "relation": "sibling" }, { "guide": "working-groups", "relation": "concept" } ] } }, "/working-groups/{id}/ai-rate": { "get": { "operationId": "getAiRate_WorkingGroups", "x-method": "GET", "x-path": "/working-groups/{id}/ai-rate", "x-handler": "wg::get_ai_rate", "tags": [ "Working Groups" ], "summary": "Read a working group's effective AI prices", "description": "Returns the room-level USD-per-agent-minute rate, a billing-relevant agent\nroster with effective-rate provenance, and up to 100 KGs owned by the room\nwith their access rates. The precedence shown for each agent is owner-set\nroom/agent override, agent-definition rate, room rate, then the platform\ndefault (represented by a null effective value).\n\nRead access is available to the working-group creator and active members so\nprospective users of member-paid rooms can see prices before invoking an\nagent. `can_edit` is true only for the creator or an active owner/admin.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current display-clamped group, agent, and KG pricing view.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "working_group_id", "ai_minute_usd", "agents", "kgs", "can_edit" ], "properties": { "working_group_id": { "type": "string", "format": "uuid" }, "ai_minute_usd": { "type": [ "number", "null" ], "minimum": 0, "maximum": 10, "description": "USD per agent-minute. `null` selects the next fallback rate." }, "agents": { "type": "array", "maxItems": 300, "description": "Up to 100 roster/usage agents plus configured overrides not in that roster.", "items": { "type": "object", "additionalProperties": false, "required": [ "agent_id", "display_name", "spec_usd_per_minute", "room_agent_usd_per_minute", "effective_usd_per_minute", "rate_source" ], "properties": { "agent_id": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "spec_usd_per_minute": { "type": [ "number", "null" ], "minimum": 0, "maximum": 10, "description": "USD per agent-minute. `null` selects the next fallback rate." }, "room_agent_usd_per_minute": { "type": [ "number", "null" ], "minimum": 0, "maximum": 10, "description": "USD per agent-minute. `null` selects the next fallback rate." }, "effective_usd_per_minute": { "type": [ "number", "null" ], "minimum": 0, "maximum": 10, "description": "USD per agent-minute. `null` selects the next fallback rate." }, "rate_source": { "type": [ "string", "null" ], "enum": [ "room_agent", "agent", "room", null ] } } } }, "kgs": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "kg_id", "name", "access_usd_per_page" ], "properties": { "kg_id": { "type": [ "string", "null" ], "format": "uuid" }, "name": { "type": "string" }, "access_usd_per_page": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1, "description": "USD per page of KG context consumed. `null` makes access free." } } } }, "can_edit": { "type": "boolean" } } } } } }, "400": { "description": "The working-group path id is not a UUID.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing or invalid bearer credential.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } }, "403": { "description": "Caller is neither the creator nor an active group member.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Working group not found.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Group, roster, or KG pricing read failed.", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getAiRate_WorkingGroups", "resource_uri": "yf://agents/working-groups/{id}/ai-rate", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/$GROUP_ID/ai-rate" } ], "x-related": [ { "operationId": "setAiRate_WorkingGroups", "relation": "update" }, { "operationId": "getAccessRate_Kgs", "relation": "kg-pricing" } ] }, "put": { "operationId": "setAiRate_WorkingGroups", "x-method": "PUT", "x-path": "/working-groups/{id}/ai-rate", "x-handler": "wg::set_ai_rate", "tags": [ "Working Groups" ], "summary": "Set or clear a working group's AI rate", "description": "Sets the room-level price in USD per agent-minute for future usage. A null\nor omitted value clears the override and restores the platform fallback.\nThe allowed band is 0 through 10 USD per minute, inclusive. Per-agent owner\noverrides and agent-definition rates continue to take precedence.\n\nAuth: the working-group creator or an active owner/admin. Existing metered\nline items are immutable; this affects only later usage.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ai_minute_usd": { "type": [ "number", "null" ], "minimum": 0, "maximum": 10, "description": "USD per agent-minute. `null` selects the next fallback rate." } }, "description": "Omitting `ai_minute_usd` has the same clearing effect as `null`." }, "examples": { "set": { "value": { "ai_minute_usd": 0.25 } }, "clear": { "value": { "ai_minute_usd": null } } } } } }, "responses": { "200": { "description": "Persisted room rate, or null after clearing.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "working_group_id", "ai_minute_usd" ], "properties": { "working_group_id": { "type": "string", "format": "uuid" }, "ai_minute_usd": { "type": [ "number", "null" ], "minimum": 0, "maximum": 10, "description": "USD per agent-minute. `null` selects the next fallback rate." } } } } } }, "400": { "description": "Malformed working-group id or JSON body.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing or invalid bearer credential.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } }, "403": { "description": "Caller is not the creator or an active owner/admin.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Working group not found.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "422": { "description": "Rate is non-finite or outside 0..10 USD per agent-minute.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Membership lookup or settings update failed.", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_setAiRate_WorkingGroups", "resource_uri": "yf://agents/working-groups/{id}/ai-rate", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PUT -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" -d '{\"ai_minute_usd\":0.25}' \\\n https://agents.yieldfabric.com/working-groups/$GROUP_ID/ai-rate\n" } ], "x-related": [ { "operationId": "getAiRate_WorkingGroups", "relation": "read-after-write" }, { "operationId": "setAgentAiRate_AgentsInGroup", "relation": "more-specific" } ] } }, "/working-groups/{id}/audit-events": { "get": { "operationId": "listGroupAuditEvents_Audit", "x-method": "GET", "x-path": "/working-groups/{id}/audit-events", "x-handler": "wg::list_group_audit_events", "tags": [ "Audit" ], "summary": "List audit events for a working group", "description": "Returns rows from `working_group_audit_events` in reverse-chronological\norder — every mutation that the group handlers record (member add /\nremove / role change, step approve / reject / reassign / complete /\nfail, federation policy changes, etc.). Each row carries the actor's\nentity id, an `action_type` string, and a JSON `payload` with\nper-action detail. Supports `limit` (1-500, default 100) and `offset`\npagination. Auth: bearer JWT; caller must hold `ViewAuditEvents`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (default 100, max 500).", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Offset into the result set.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "events", "limit", "offset" ], "properties": { "events": { "type": "array", "items": { "type": "object", "description": "One row from `working_group_audit_events`.", "required": [ "id", "group_id", "actor_entity_id", "action_type", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "group_id": { "type": "string", "format": "uuid" }, "actor_entity_id": { "type": "string", "description": "entity_id of the user/system that produced the event." }, "action_type": { "type": "string", "description": "Discriminator (e.g. `member_added`, `member_role_updated`,\n`member_removed`, `step_completed`, `step_rejected`,\n`step_reassigned`, `child_pipeline_signed`).\n" }, "payload": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ], "description": "Action-specific JSON payload." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } }, "limit": { "type": "integer", "minimum": 1, "maximum": 500 }, "offset": { "type": "integer", "minimum": 0 } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listGroupAuditEvents_Audit", "resource_uri": "yf://agents/audit", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/working-groups/{id}/audit-events?limit=50\"" } ], "x-related": [ { "operationId": "getIntentAudit_Intents", "relation": "sibling" }, { "guide": "working-groups", "relation": "concept" } ] } }, "/working-groups/{id}/billing-group": { "post": { "operationId": "enableBillingGroup_WorkingGroups", "x-method": "POST", "x-path": "/working-groups/{id}/billing-group", "x-handler": "wg::enable_billing_group", "tags": [ "Working Groups" ], "summary": "Bind a billing-only auth group to a working group", "description": "Creates an auth-service group with `deploy: false`, binds its id to this\nworking group, and marks the binding as billing-only. This enables group\nbilling without deploying a shared on-chain wallet. A later room-wallet\ndeployment upgrades the same auth group rather than creating another.\n\nThe auth group inherits the working group's human-typed name (with a\n\" platform billing group\" / \" deal room billing group\"\ndescription). Auth group names are globally unique, so if the name is\nalready taken — or the working group's name is blank — the group falls\nback to the legacy uuid-derived label (\"Workspace \" /\n\"Deal Room \"); the human name is kept in the description.\n\nThe operation is serialized against wallet deployment and idempotent. If a\nbinding already exists, it returns that id with `created: false`. Auth: the\nworking-group creator or an active owner/admin, with a bearer token that can\nbe forwarded to the auth service.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Existing or newly bound auth group.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "auth_group_id", "created" ], "properties": { "auth_group_id": { "type": "string", "minLength": 1, "description": "Auth-service group id bound to the working group." }, "created": { "type": "boolean", "description": "False when the binding already existed." } } } } } }, "400": { "description": "The working-group path id is not a UUID.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing or invalid bearer credential.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } }, "403": { "description": "Caller is not the creator or an active owner/admin.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Working group not found.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Local binding or settings update failed.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "502": { "description": "The auth service could not create the billing group.", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_enableBillingGroup_WorkingGroups", "resource_uri": "yf://agents/working-groups/{id}/billing-group", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/$GROUP_ID/billing-group" } ], "x-related": [ { "operationId": "getGroup_WorkingGroups", "relation": "resource" }, { "operationId": "getAiRate_WorkingGroups", "relation": "pricing" } ] } }, "/working-groups/{id}/chat": { "post": { "operationId": "getOrCreateTeamChat_Chat", "x-method": "POST", "x-path": "/working-groups/{id}/chat", "x-handler": "wg::get_or_create_team_chat", "tags": [ "Chat" ], "summary": "Get (or create) the group's team-chat thread", "description": "Returns (creating if absent) the canonical team-chat thread for the\ngroup. Idempotent — repeated calls return the same row. No request\nbody is required; this is the \"open the team chat\" entrypoint the UI\nuses on group load. Auth: bearer JWT; caller must hold `ViewThreads`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Team-chat thread row.", "content": { "application/json": { "schema": { "type": "object", "required": [ "thread" ], "properties": { "thread": { "type": "object", "description": "A conversation thread inside a working group.", "required": [ "id", "group_id", "title", "thread_type", "status", "created_by", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "group_id": { "type": "string", "format": "uuid" }, "parent_thread_id": { "type": [ "string", "null" ], "format": "uuid", "description": "When this is a subthread (e.g. a Weaver private chat), the\nparent's id. `null` for top-level threads.\n" }, "private_to_entity_id": { "type": [ "string", "null" ], "description": "When set, this thread is visible only to the named entity.\nCombined with `parent_thread_id` makes a per-user private\nsubthread.\n" }, "title": { "type": "string" }, "thread_type": { "type": "string", "description": "Discriminator for what the thread is used for.\n", "enum": [ "discussion", "reasoning", "pipeline_main", "pipeline_task", "team_chat", "dm", "weaver", "solo_chat", "notebook_entity", "deal_composer", "deal_shared" ] }, "reference_id": { "type": [ "string", "null" ], "description": "Optional pointer to an external entity (workflow id, frame id,\nWeaver root, etc.). Format depends on `thread_type`.\n" }, "status": { "type": "string", "enum": [ "active", "closed" ] }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getOrCreateTeamChat_Chat", "resource_uri": "yf://agents/chat", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/{id}/chat" } ], "x-related": [ { "operationId": "streamChat_Chat", "relation": "watch" }, { "operationId": "postMessage_Threads", "relation": "next-step" }, { "guide": "threads", "relation": "concept" } ] } }, "/working-groups/{id}/chat/stream": { "get": { "operationId": "streamChat_Chat", "x-method": "GET", "x-path": "/working-groups/{id}/chat/stream", "x-handler": "wg::stream_chat", "tags": [ "Chat" ], "summary": "SSE stream of group chat events", "description": "Opens a Server-Sent Events stream of the group's chat broadcaster.\nThe first frame is a `Snapshot` containing the team-chat thread,\nrecent messages, active pipeline drafts, active workflows, and the\ncurrent presence list. Subsequent frames are typed `ChatEvent`\nvariants (see `x-event-types`) — new messages, typing indicators,\npresence updates, intent lifecycle events, deal lifecycle events,\nworkflow event mirrors, document processing progress. Private\nenvelopes (recipient-scoped events from the Weaver) are filtered to\nthe matching subscriber. The handler also registers the user's\npresence on connect and de-registers on disconnect. Browser clients\npass the JWT as `?access_token=`. There is no resume cursor —\non reconnect, the client receives a fresh `Snapshot` and continues\nlive; events that fired during the disconnect are not replayed.\nAuth: bearer JWT (header) OR `access_token` query (for EventSource).\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "access_token", "in": "query", "required": false, "description": "JWT — used by browser EventSource clients that cannot send `Authorization`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Server-Sent Events stream. Each event is framed as `event: \\ndata: \\n\\n`\n(chat + workflow streams) or `data: {\"type\":\"\", ...}\\n\\n` (pipeline stream\nwhere the typed enum is serialized directly per `#[serde(tag = \"type\")]`).\nSee the operation's `x-event-types` array for the full enumeration of event\nvariants and their data schemas. There is no `?last_message_ts=` resume\ncursor on chat/workflow streams today; the pipeline stream replays its in-memory\nlog on every (re)subscribe.\n", "content": { "text/event-stream": { "schema": { "type": "object", "description": "Each SSE event has an `event` name (the wire-level `event:` line) and a\n`data` JSON payload (the wire-level `data:` line, JSON-decoded). The exact\nschemas for each event variant are documented in the operation's\n`x-event-types` extension.\n", "required": [ "event", "data" ], "properties": { "event": { "type": "string", "description": "Event name from the operation's `x-event-types` enumeration." }, "data": { "description": "JSON payload. Shape depends on `event` — see `x-event-types`." }, "id": { "type": [ "string", "null" ], "description": "Optional SSE event id (used for resume cursors)." } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-event-types": [ { "name": "Snapshot", "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "Snapshot" ] }, "thread": { "description": "Team-chat thread row" }, "messages": { "type": "array", "items": { "description": "ThreadMessage" } }, "active_drafts": { "type": "array", "items": { "description": "Pipeline draft summary" } }, "active_workflows": { "type": "array", "items": { "description": "GroupWorkflow rows in running/pending" } }, "presence": { "type": "array", "items": { "description": "Presence row" } } } } }, { "name": "NewMessage", "schema": { "type": "object", "required": [ "type", "thread_id", "message" ], "properties": { "type": { "type": "string", "enum": [ "NewMessage" ] }, "thread_id": { "type": "string", "format": "uuid" }, "message": { "description": "ThreadMessage" } } } }, { "name": "AgentTyping", "schema": { "type": "object", "required": [ "type", "thread_id", "agent_id" ], "properties": { "type": { "type": "string", "enum": [ "AgentTyping" ] }, "thread_id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string" } } } }, { "name": "AgentToken", "schema": { "type": "object", "required": [ "type", "thread_id", "agent_id", "token" ], "properties": { "type": { "type": "string", "enum": [ "AgentToken" ] }, "thread_id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string" }, "token": { "type": "string" } } } }, { "name": "AgentDone", "schema": { "type": "object", "required": [ "type", "thread_id", "agent_id" ], "properties": { "type": { "type": "string", "enum": [ "AgentDone" ] }, "thread_id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string" } } } }, { "name": "HumanTyping", "schema": { "type": "object", "required": [ "type", "thread_id", "entity_id", "display_name" ], "properties": { "type": { "type": "string", "enum": [ "HumanTyping" ] }, "thread_id": { "type": "string", "format": "uuid" }, "entity_id": { "type": "string" }, "display_name": { "type": "string" } } } }, { "name": "PresenceUpdate", "schema": { "type": "object", "required": [ "type", "entity_id", "status", "last_seen_at", "group_ids" ], "properties": { "type": { "type": "string", "enum": [ "PresenceUpdate" ] }, "entity_id": { "type": "string" }, "status": { "type": "string", "enum": [ "online", "away", "dnd", "offline" ] }, "last_seen_at": { "type": "string", "format": "date-time" }, "group_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } }, { "name": "ReadReceipt", "schema": { "type": "object", "required": [ "type", "thread_id", "entity_id", "last_read_message_id" ], "properties": { "type": { "type": "string", "enum": [ "ReadReceipt" ] }, "thread_id": { "type": "string", "format": "uuid" }, "entity_id": { "type": "string" }, "last_read_message_id": { "type": "string", "format": "uuid" } } } }, { "name": "WorkflowUpdate", "schema": { "type": "object", "required": [ "type", "thread_id", "workflow_id", "event" ], "properties": { "type": { "type": "string", "enum": [ "WorkflowUpdate" ] }, "thread_id": { "type": "string", "format": "uuid" }, "workflow_id": { "type": "string", "format": "uuid" }, "event": { "description": "Mirror of WorkflowEvent — see streamWorkflow_Workflows x-event-types" } } } }, { "name": "DocumentProcessing", "schema": { "type": "object", "required": [ "type", "document_id", "step" ], "properties": { "type": { "type": "string", "enum": [ "DocumentProcessing" ] }, "document_id": { "type": "string", "format": "uuid" }, "step": { "type": "string" }, "progress": { "type": [ "number", "null" ] }, "detail": {} } } }, { "name": "IntentProposed", "schema": { "type": "object", "required": [ "type", "thread_id", "intent_id", "intent_type", "title", "proposed_by" ], "properties": { "type": { "type": "string", "enum": [ "IntentProposed" ] }, "thread_id": { "type": "string", "format": "uuid" }, "intent_id": { "type": "string", "format": "uuid" }, "intent_type": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "tool_name": { "type": [ "string", "null" ] }, "arguments": {}, "pipeline_steps": {}, "operations": {}, "validation": {}, "proposed_by": { "type": "string" } } } }, { "name": "IntentConfirmed", "schema": { "type": "object", "required": [ "type", "thread_id", "intent_id" ], "properties": { "type": { "type": "string", "enum": [ "IntentConfirmed" ] }, "thread_id": { "type": "string", "format": "uuid" }, "intent_id": { "type": "string", "format": "uuid" } } } }, { "name": "IntentExecuting", "schema": { "type": "object", "required": [ "type", "thread_id", "intent_id" ], "properties": { "type": { "type": "string", "enum": [ "IntentExecuting" ] }, "thread_id": { "type": "string", "format": "uuid" }, "intent_id": { "type": "string", "format": "uuid" }, "workflow_id": { "type": [ "string", "null" ] }, "message_id": { "type": [ "string", "null" ] } } } }, { "name": "IntentCompleted", "schema": { "type": "object", "required": [ "type", "thread_id", "intent_id", "result" ], "properties": { "type": { "type": "string", "enum": [ "IntentCompleted" ] }, "thread_id": { "type": "string", "format": "uuid" }, "intent_id": { "type": "string", "format": "uuid" }, "result": {} } } }, { "name": "IntentFailed", "schema": { "type": "object", "required": [ "type", "thread_id", "intent_id", "error" ], "properties": { "type": { "type": "string", "enum": [ "IntentFailed" ] }, "thread_id": { "type": "string", "format": "uuid" }, "intent_id": { "type": "string", "format": "uuid" }, "error": { "type": "string" } } } }, { "name": "DealCommitted", "schema": { "type": "object", "required": [ "type", "thread_id", "deal_id", "deal_kg_id" ], "properties": { "type": { "type": "string", "enum": [ "DealCommitted" ] }, "thread_id": { "type": "string", "format": "uuid" }, "deal_id": { "type": "string", "format": "uuid" }, "deal_kg_id": { "type": "string", "format": "uuid" }, "label": { "type": [ "string", "null" ] }, "pattern_id": { "type": [ "string", "null" ] }, "committed_by": { "type": [ "string", "null" ] }, "tool_call_reasoning": { "type": [ "string", "null" ] }, "tool_call_evidence_count": { "type": "integer" } } } }, { "name": "DealPipelined", "schema": { "type": "object", "required": [ "type", "thread_id", "deal_id", "intent_id" ], "properties": { "type": { "type": "string", "enum": [ "DealPipelined" ] }, "thread_id": { "type": "string", "format": "uuid" }, "deal_id": { "type": "string", "format": "uuid" }, "intent_id": { "type": "string", "format": "uuid" } } } }, { "name": "DealCompleted", "schema": { "type": "object", "required": [ "type", "thread_id", "deal_id" ], "properties": { "type": { "type": "string", "enum": [ "DealCompleted" ] }, "thread_id": { "type": "string", "format": "uuid" }, "deal_id": { "type": "string", "format": "uuid" } } } }, { "name": "DealCancelled", "schema": { "type": "object", "required": [ "type", "thread_id", "deal_id" ], "properties": { "type": { "type": "string", "enum": [ "DealCancelled" ] }, "thread_id": { "type": "string", "format": "uuid" }, "deal_id": { "type": "string", "format": "uuid" }, "reason": { "type": [ "string", "null" ] } } } }, { "name": "DealFailed", "schema": { "type": "object", "required": [ "type", "thread_id", "deal_id" ], "properties": { "type": { "type": "string", "enum": [ "DealFailed" ] }, "thread_id": { "type": "string", "format": "uuid" }, "deal_id": { "type": "string", "format": "uuid" }, "reason": { "type": [ "string", "null" ] } } } }, { "name": "Lagged", "description": "Stream-control notice (synthetic): the subscriber fell behind and the broker dropped `skipped` events. Not a ChatEvent variant.", "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "Lagged" ] }, "skipped": { "type": "integer" } } } }, { "name": "StreamEnded", "description": "Stream-control notice (synthetic): the broadcast channel closed. Not a ChatEvent variant — the wire connection will close after this.", "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "StreamEnded" ] } } } } ], "x-mcp": { "tool_name": "yieldfabric_agents_streamChat_Chat", "resource_uri": "yf://agents/chat", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -N -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/{id}/chat/stream" } ], "x-related": [ { "operationId": "getOrCreateTeamChat_Chat", "relation": "prerequisite" }, { "operationId": "postMessage_Threads", "relation": "sibling" }, { "guide": "streaming", "relation": "concept" }, { "guide": "threads", "relation": "concept" } ] } }, "/working-groups/{id}/classify-deal": { "post": { "operationId": "classifyDeal_WorkingGroups", "x-method": "POST", "x-path": "/working-groups/{id}/classify-deal", "x-handler": "wg::classify_deal", "tags": [ "Working Groups" ], "summary": "Deterministically classify grounded deal facets", "description": "Projects the submitted structural deal facets into the economy schema's\nclosed feature vector, runs the catalog decision tree, and resolves the\nmatching deal type's pricing hints and required identity fields. No LLM is\ncalled and no state is written: identical facet inputs produce identical\nresults. Missing arrays default to empty; render-only brief fields are\naccepted and ignored.\n\nThe caller needs the group's `ViewDocuments` action, matching the RAG surface\nthat produced the grounded facets. Auth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Structural `ExtractedDealFacets` fields. Render-only fields are accepted and ignored; absent facet arrays default to empty.", "properties": { "terms": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] }, "value": { "type": [ "string", "null" ] } } }, "default": [] }, "tranches": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "sizeLabel": { "type": [ "string", "null" ] } } }, "default": [] }, "poolFacts": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] }, "value": { "type": [ "string", "null" ] } } }, "default": [] }, "keyDates": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": [ "string", "null" ] }, "whenLabel": { "type": [ "string", "null" ] } } }, "default": [] }, "financialActions": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": [ "string", "null" ] }, "whatLabel": { "type": [ "string", "null" ] }, "amountLabel": { "type": [ "string", "null" ] }, "timingLabel": { "type": [ "string", "null" ] } } }, "default": [] }, "dealParties": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "roleLabel": { "type": [ "string", "null" ] } } }, "default": [] } } }, "examples": { "tranched-pool": { "value": { "tranches": [ { "name": "Class A", "sizeLabel": "AUD 80m" } ], "poolFacts": [ { "key": "asset_class", "label": "Asset class", "value": "auto loans" } ] } } } } } }, "responses": { "200": { "description": "Catalog-aligned deterministic classification.", "content": { "application/json": { "schema": { "type": "object", "required": [ "deal_type", "label", "matched", "confidence", "pricing", "below_confirm_threshold", "expects" ], "properties": { "deal_type": { "type": "string" }, "label": { "type": "string" }, "matched": { "type": "boolean", "description": "True only when a non-`other` catalog rule matched." }, "confidence": { "type": "number", "description": "Deterministic confidence declared by the matched catalog rule." }, "pricing": { "type": "object", "required": [ "model", "template", "indicative_only", "default_pool_wac", "default_debt_yield" ], "properties": { "model": { "type": "string" }, "template": { "type": [ "string", "null" ] }, "indicative_only": { "type": "boolean" }, "default_pool_wac": { "type": [ "number", "null" ] }, "default_debt_yield": { "type": [ "number", "null" ] } } }, "below_confirm_threshold": { "type": "boolean" }, "expects": { "type": "array", "description": "Catalog-required identity fields the classified type is expected to state.", "items": { "type": "object", "required": [ "id", "facet", "key" ], "properties": { "id": { "type": "string" }, "facet": { "type": "string" }, "key": { "type": [ "string", "null" ] } } } } } } } } }, "400": { "description": "Malformed JSON or path identifier." }, "401": { "description": "Missing or invalid bearer credential." }, "403": { "description": "Caller lacks document-view access to the group." }, "404": { "description": "Working group or membership does not exist." } }, "x-mcp": { "tool_name": "yieldfabric_agents_classifyDeal_WorkingGroups", "resource_uri": "yf://agents/working-groups", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST https://agents.yieldfabric.com/working-groups/{id}/classify-deal \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"tranches\":[{\"name\":\"Class A\",\"sizeLabel\":\"AUD 80m\"}],\"poolFacts\":[{\"key\":\"asset_class\",\"value\":\"auto loans\"}]}'\n" } ], "x-related": [ { "guide": "working-groups", "relation": "concept" } ] } }, "/working-groups/{id}/deal-extract": { "get": { "operationId": "getRoomDealExtract_WorkingGroups", "x-method": "GET", "x-path": "/working-groups/{id}/deal-extract", "x-handler": "crate::working_group::deal_room::extract::get_room_deal_extract", "tags": [ "Working Groups" ], "summary": "The room's shared deal brief, as a validated read", "description": "Serves the room-shared row (`deal_room_doc_extracts`) for the room's\nCURRENT indexed document set — one row lookup: never an extraction, never\na bill, and therefore safe on every room open and every return to the tab.\nThe producer is `POST` on the same path.\n\nThe response carries the row's identity as an `ETag` — the document-set\nfingerprint (salted with the extraction contract version) and the moment\nthe row was written, so an owner's forced re-read and a server-side\nchange are new tags while the documents are unchanged. A client that\nholds a copy sends it back as `If-None-Match` and receives `304` with no\nbody when the copy IS the room's brief. This is what keeps every browser\non the same brief: a copy keyed on the documents alone outlived a\nreplaced row for days.\n\n`Cache-Control: no-store` on every response — the client keeps its own\ncopy under the tag and revalidates here; the browser's HTTP cache must\nnot hold a second one.\n\nGate: `ViewDocuments` with the room's terms accepted, service tokens\nrefused — the producer's floor — but NOT an LLM route: a member under a\nbilling gate can still read the brief the room already has. Auth: bearer\nJWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "If-None-Match", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The `etag` a previous `200` (or a producing `POST`) carried. When it names the current row, the answer is `304` and the caller's copy stands." } ], "responses": { "200": { "description": "The stored grounded row — `status: grounded`, `cached: true`,\n`stored: false`, the brief in `extract`, its `metrics`, and the\nrow's identity as `etag` (the same value as the `ETag` header) and\n`stored_at`.\n", "headers": { "ETag": { "schema": { "type": "string" }, "description": "The row's identity; send it back as `If-None-Match`." }, "Cache-Control": { "schema": { "type": "string" }, "description": "Always `no-store`." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "cached", "stored", "fingerprint", "extract", "metrics" ], "properties": { "status": { "type": "string", "enum": [ "grounded", "no-docs" ] }, "cached": { "type": "boolean", "description": "True when the stored row for this document set was served instead of read." }, "stored": { "type": "boolean", "description": "True when THIS call wrote the room-shared row." }, "fingerprint": { "type": [ "string", "null" ], "description": "The stored row's key — the indexed document set's content fingerprint, salted with the extraction contract version. Null when no document is indexed." }, "extract": { "type": [ "object", "null" ], "additionalProperties": true, "description": "The brief's `ExtractedDeal` (camelCase; `yieldfabric-app/src/types/dealBrief.ts`): `summary`, `terms`, `financialActions`, `tranches`, `poolFacts`, `keyDates`, `dealParties` (each row stamped `provenance: extracted`, `source: document`, `unconfirmed: true`), the `*Truncated` flags, `chunksRetrieved` (max across facets), `dealType` (the classify verdict as a `BriefDealType`, or null for the `other` fallback) and `citations` (every facet's retrieved citations, concatenated). Null when no document is indexed." }, "metrics": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Extraction-quality signal stored with the row and logged under `yieldfabric.deal_room.extract_quality`: `tranches_total`, `tranches_parsed` (rows whose structured notional resolved), `slot_fill_rate`, `grounded` (per facet), `classify` (`classified` | `other`), `duration_ms`, `chunks_retrieved`." }, "etag": { "type": [ "string", "null" ], "description": "The shared row's identity — the fingerprint and the moment the row was written, quoted as an HTTP entity tag. Present whenever the `extract` IS the shared row (served from it, or written by this call); null for a reading that was not stored (a non-owner's forced re-read while a row exists) and for `no-docs`. Send it as `If-None-Match` to the `GET` on this path to learn whether a held copy is still the room's brief." }, "stored_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the shared row was written; null when `etag` is null." }, "facets": { "type": "object", "description": "Live reads only — each facet's own `ok`, `status`, `chunks_retrieved`, `error`.", "additionalProperties": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "type": "integer" }, "chunks_retrieved": { "type": "integer" }, "error": { "type": [ "string", "null" ] } } } } } }, "examples": { "the-shared-row": { "value": { "status": "grounded", "cached": true, "stored": false, "fingerprint": "extract-v1:9f1c2b3a", "etag": "\"extract-v1:9f1c2b3a:1757686639000001\"", "stored_at": "2026-09-12T14:37:19.000001Z", "extract": { "summary": "A securitisation master trust issuing Class A and Class B notes.", "terms": [], "tranches": [], "poolFacts": [], "keyDates": [], "dealParties": [], "financialActions": [], "chunksRetrieved": 6, "dealType": null, "citations": [] }, "metrics": { "tranches_total": 8, "tranches_parsed": 8, "slot_fill_rate": 0.95, "grounded": { "f1_facts": true, "f2_capital_structure": true, "f3_pool": true, "f4_dates": true, "f5_parties": true }, "classify": "classified", "duration_ms": 33098, "chunks_retrieved": 5 } } } } } } }, "304": { "description": "`If-None-Match` names the current row: the caller's copy is the room's brief. No body; `ETag` and `Cache-Control` are repeated.", "headers": { "ETag": { "schema": { "type": "string" } } } }, "401": { "description": "Missing or invalid bearer credential." }, "403": { "description": "Caller is not a room member with the terms accepted, or presented a service token." }, "404": { "description": "Three distinct absences, told apart by the body: `status: none` —\ndocuments are indexed but no shared row exists for this set yet (a\n`POST` produces it; Reprocess forgets rows); `status: no-docs` —\nnothing is indexed (`fingerprint: null`); or the working group /\nmembership does not exist (the plain-text error the membership gate\nanswers with).\n", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "fingerprint" ], "properties": { "status": { "type": "string", "enum": [ "none", "no-docs" ] }, "fingerprint": { "type": [ "string", "null" ] } } }, "examples": { "no-row-yet": { "value": { "status": "none", "fingerprint": "extract-v1:9f1c2b3a" } }, "nothing-indexed": { "value": { "status": "no-docs", "fingerprint": null } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getRoomDealExtract_WorkingGroups", "resource_uri": "yf://agents/working-groups", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl \"https://agents.yieldfabric.com/working-groups/{id}/deal-extract\" \\\n -H \"Authorization: Bearer $JWT\" \\\n -H 'If-None-Match: \"extract-v1:9f1c2b3a:1757686639000001\"'\n" } ], "x-related": [ { "guide": "working-groups", "relation": "concept" } ] }, "post": { "operationId": "extractRoomDeal_WorkingGroups", "x-method": "POST", "x-path": "/working-groups/{id}/deal-extract", "x-handler": "crate::working_group::deal_room::extract::extract_room_deal", "tags": [ "Working Groups" ], "summary": "Read a room's documents into the deal brief", "description": "Reads the room's INDEXED documents into the brief's `ExtractedDeal` — the\ncamelCase shape the app renders — classifies it, stores the room-shared row\n(`deal_room_doc_extracts`) and returns it. This is the whole pass the app\nused to orchestrate in the browser over `/query/batch`, `/classify-deal`\nand the `saveDocExtract` mutation, moved server-side.\n\nFive parked questions (deal terms and cash-flow actions; capital structure;\ncollateral pool; key dates; parties) are each retrieved through the room's\nown RAG path and then asked under a STRICT JSON schema, so the answer's\nshape is enforced rather than requested: closed enums for the coupon kind,\nthe size unit and the action verb; every cell nullable. Every string cell\nmust carry a `[N]` marker that resolves to a citation the retriever\nreturned — an ungrounded or sentinel cell (\"Not stated in provided\nevidence\") is dropped, never surfaced. Rows are stamped\n`provenance: extracted`, `source: document`, `unconfirmed: true` here; the\nmodel never sets them.\n\nThe row key is a fingerprint of the indexed document set (sorted content\nhashes), salted with the extraction contract version. Same documents ⇒ the\nstored row is served (`cached: true`) without any AI call; a document\nchange re-keys. `?force=true` reads again regardless; the fresh reading\nreplaces the shared row only for the room OWNER (anyone else still receives\nit, and the shared row keeps its first writer).\n\nAll five facets run inside this ONE request under one admission permit,\nbounded to 3 in flight. Billing and admission are those of any LLM route.\nGate: `ViewDocuments` with the room's terms accepted — the same floor as the\nfile routes, because the answer is the documents' content. Service tokens\nare refused. Auth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "force", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Read the documents again even when a row for this document set is stored." } ], "responses": { "200": { "description": "`status: grounded` — at least one facet retrieved evidence; `extract`\ncarries the merged brief, `metrics` its quality signal, `fingerprint`\nthe row key, `cached` whether the stored row was served, `stored`\nwhether THIS call wrote the shared row. `status: no-docs` — no indexed\ndocument (`fingerprint: null`, nothing billed) or every facet answered\nand retrieved nothing. `facets` (live reads only) carries each facet's\nown outcome.\n", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "cached", "stored", "fingerprint", "extract", "metrics" ], "properties": { "status": { "type": "string", "enum": [ "grounded", "no-docs" ] }, "cached": { "type": "boolean", "description": "True when the stored row for this document set was served instead of read." }, "stored": { "type": "boolean", "description": "True when THIS call wrote the room-shared row." }, "fingerprint": { "type": [ "string", "null" ], "description": "The stored row's key — the indexed document set's content fingerprint, salted with the extraction contract version. Null when no document is indexed." }, "extract": { "type": [ "object", "null" ], "additionalProperties": true, "description": "The brief's `ExtractedDeal` (camelCase; `yieldfabric-app/src/types/dealBrief.ts`): `summary`, `terms`, `financialActions`, `tranches`, `poolFacts`, `keyDates`, `dealParties` (each row stamped `provenance: extracted`, `source: document`, `unconfirmed: true`), the `*Truncated` flags, `chunksRetrieved` (max across facets), `dealType` (the classify verdict as a `BriefDealType`, or null for the `other` fallback) and `citations` (every facet's retrieved citations, concatenated). Null when no document is indexed." }, "metrics": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Extraction-quality signal stored with the row and logged under `yieldfabric.deal_room.extract_quality`: `tranches_total`, `tranches_parsed` (rows whose structured notional resolved), `slot_fill_rate`, `grounded` (per facet), `classify` (`classified` | `other`), `duration_ms`, `chunks_retrieved`." }, "etag": { "type": [ "string", "null" ], "description": "The shared row's identity — the fingerprint and the moment the row was written, quoted as an HTTP entity tag. Present whenever the `extract` IS the shared row (served from it, or written by this call); null for a reading that was not stored (a non-owner's forced re-read while a row exists) and for `no-docs`. Send it as `If-None-Match` to the `GET` on this path to learn whether a held copy is still the room's brief." }, "stored_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the shared row was written; null when `etag` is null." }, "facets": { "type": "object", "description": "Live reads only — each facet's own `ok`, `status`, `chunks_retrieved`, `error`.", "additionalProperties": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "type": "integer" }, "chunks_retrieved": { "type": "integer" }, "error": { "type": [ "string", "null" ] } } } } } }, "examples": { "served-from-the-shared-row": { "value": { "status": "grounded", "cached": true, "stored": false, "fingerprint": "extract-v1:9f1c2b3a", "extract": { "summary": "A securitisation master trust issuing Class A and Class B notes.", "terms": [ { "key": "notional", "label": "Notional", "value": "AUD 180,000,000", "provenance": "extracted", "source": "document", "unconfirmed": true } ], "tranches": [ { "name": "Class A Notes", "sizeLabel": "AUD 166.50 million", "sizeValue": 166500000, "sizeCurrency": "AUD", "rateLabel": "1M BBSW + 1.20%", "couponKind": "floating", "couponSpread": 0.012, "couponIndex": "BBSW", "ratingLabel": "AAA (S&P)", "subordinationLabel": "26%", "provenance": "extracted", "source": "document", "unconfirmed": true } ], "poolFacts": [], "keyDates": [], "dealParties": [], "financialActions": [], "chunksRetrieved": 6, "dealType": { "id": "abs_consumer", "label": "Consumer ABS", "model": "waterfall", "provenance": "derived", "unconfirmed": true, "indicativeOnly": false, "belowConfirmThreshold": false, "expects": [] }, "citations": [] }, "metrics": { "tranches_total": 1, "tranches_parsed": 1, "slot_fill_rate": 1, "grounded": { "f1_facts": true, "f2_capital_structure": true, "f3_pool": false, "f4_dates": true, "f5_parties": true }, "classify": "classified", "duration_ms": 18342, "chunks_retrieved": 6 } } }, "no-indexed-documents": { "value": { "status": "no-docs", "cached": false, "stored": false, "fingerprint": null, "extract": null, "metrics": null } } } } } }, "401": { "description": "Missing or invalid bearer credential." }, "402": { "description": "Billing refusal (`card_required` / `credit_exhausted`), as on every LLM route." }, "403": { "description": "Caller is not a room member with the terms accepted, or presented a service token." }, "404": { "description": "Working group or membership does not exist." }, "429": { "description": "Too much AI in flight for this person (`inference_limit`), with `Retry-After`." }, "502": { "description": "Every facet failed (retrieval or the model); the message is the first facet's own." } }, "x-mcp": { "tool_name": "yieldfabric_agents_extractRoomDeal_WorkingGroups", "resource_uri": "yf://agents/working-groups", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST \"https://agents.yieldfabric.com/working-groups/{id}/deal-extract?force=false\" \\\n -H \"Authorization: Bearer $JWT\"\n" } ], "x-related": [ { "guide": "working-groups", "relation": "concept" } ] } }, "/working-groups/{id}/deal-composer-thread": { "post": { "operationId": "ensureDealComposerThread_WorkingGroups", "x-method": "POST", "x-path": "/working-groups/{id}/deal-composer-thread", "x-handler": "wg::ensure_deal_composer_thread", "tags": [ "Working Groups" ], "summary": "Get or create a private deal-composer thread", "description": "Returns (creating if absent) the caller's private, draft-scoped deal\ncomposer thread inside an economy-backed workspace. The thread is used by\nDMS deal authoring to post the user's natural-language brief and then run\n`/api/conversation/analyze` over the same thread substrate. Repeated calls\nwith the same `draft_id` return the same private thread. Auth: bearer JWT;\ncaller must hold `ViewThreads`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "draft_id" ], "properties": { "draft_id": { "type": "string", "minLength": 1, "description": "DMS draft identifier used to scope the private composer thread." }, "title": { "type": [ "string", "null" ], "description": "Optional thread title. Defaults to \"Deal composer\"." } } } } } }, "responses": { "200": { "description": "Deal-composer thread row (existing or newly created).", "content": { "application/json": { "schema": { "type": "object", "required": [ "thread" ], "properties": { "thread": { "type": "object", "description": "A conversation thread inside a working group.", "required": [ "id", "group_id", "title", "thread_type", "status", "created_by", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "group_id": { "type": "string", "format": "uuid" }, "parent_thread_id": { "type": [ "string", "null" ], "format": "uuid", "description": "When this is a subthread (e.g. a Weaver private chat), the\nparent's id. `null` for top-level threads.\n" }, "private_to_entity_id": { "type": [ "string", "null" ], "description": "When set, this thread is visible only to the named entity.\nCombined with `parent_thread_id` makes a per-user private\nsubthread.\n" }, "title": { "type": "string" }, "thread_type": { "type": "string", "description": "Discriminator for what the thread is used for.\n", "enum": [ "discussion", "reasoning", "pipeline_main", "pipeline_task", "team_chat", "dm", "weaver", "solo_chat", "notebook_entity", "deal_composer", "deal_shared" ] }, "reference_id": { "type": [ "string", "null" ], "description": "Optional pointer to an external entity (workflow id, frame id,\nWeaver root, etc.). Format depends on `thread_type`.\n" }, "status": { "type": "string", "enum": [ "active", "closed" ] }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_ensureDealComposerThread_WorkingGroups", "resource_uri": "yf://agents/working-groups", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"draft_id\":\"draft_123\",\"title\":\"Agreement draft\"}' \\\n https://agents.yieldfabric.com/working-groups/{id}/deal-composer-thread\n" } ], "x-related": [ { "operationId": "postMessage_Threads", "relation": "next-step" }, { "operationId": "analyzeConversation_Conversation", "relation": "next-step" }, { "operationId": "ensureSoloThread_WorkingGroups", "relation": "sibling" } ] } }, "/working-groups/{id}/deal-templates": { "get": { "operationId": "listRoomDealTemplates_DealTemplates", "x-method": "GET", "x-path": "/working-groups/{id}/deal-templates", "x-handler": "wg_templates::list_room_deal_templates", "tags": [ "Deal Templates" ], "summary": "List approved templates available to a working group", "description": "Returns up to 50 approved templates owned by active members of the target\nworking group. The optional `deal_type` filter is applied only when it is a\nlowercase `[a-z0-9_]` token of at most 48 characters; malformed values are\ntreated as if the filter were omitted. Auth: an active member with the\ngroup's `ViewDocuments` action.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "deal_type", "in": "query", "required": false, "description": "Optional platform deal-type id such as `abs`; malformed tokens are ignored.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Approved templates available in the room.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "templates" ], "properties": { "templates": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "owner_entity_id", "name", "extends", "version", "status", "spec", "created_at", "approved_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "owner_entity_id": { "type": "string" }, "name": { "type": "string" }, "extends": { "type": "string" }, "version": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "draft", "approved", "retired" ] }, "spec": { "type": "object", "additionalProperties": false, "required": [ "name", "extends" ], "description": "Canonical template definition. At least one `panel` group or `cps` item\nis required, field and CP ids must be unique, and there may be no more\nthan 120 fields across all panel groups. `extends` must resolve to a\nplatform deal-type id; the token pattern alone is not sufficient.\n", "anyOf": [ { "required": [ "panel" ], "properties": { "panel": { "type": "array", "minItems": 1 } } }, { "required": [ "cps" ], "properties": { "cps": { "type": "array", "minItems": 1 } } } ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "extends": { "type": "string", "pattern": "^[a-z0-9_]{1,48}$", "description": "Existing platform deal-type id, for example `abs` or `repo`." }, "description": { "type": [ "string", "null" ], "maxLength": 300 }, "panel": { "type": "array", "maxItems": 12, "default": [], "items": { "type": "object", "additionalProperties": false, "required": [ "category", "title", "fields" ], "properties": { "category": { "type": "string", "pattern": "^[a-z0-9_]{1,48}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "fields": { "type": "array", "minItems": 1, "maxItems": 24, "default": [], "items": { "type": "object", "additionalProperties": false, "required": [ "id", "label" ], "properties": { "id": { "type": "string", "pattern": "^[a-z0-9_]{1,48}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "facet": { "type": [ "string", "null" ], "enum": [ "terms", "financialActions", "tranches", "poolFacts", "keyDates", "dealParties", null ] }, "key": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$" }, "role": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$" }, "hint": { "type": [ "string", "null" ], "maxLength": 300 }, "required": { "type": "boolean", "default": false }, "confirm_role": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$" }, "confirmRole": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$", "description": "Input alias for `confirm_role`; responses use snake_case." } } } } } } }, "cps": { "type": "array", "maxItems": 64, "default": [], "items": { "type": "object", "additionalProperties": false, "required": [ "id", "title" ], "properties": { "id": { "type": "string", "pattern": "^[a-z0-9_]{1,48}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "source_hint": { "type": [ "string", "null" ], "maxLength": 120 }, "sourceHint": { "type": [ "string", "null" ], "maxLength": 120, "description": "Input alias for `source_hint`; responses use snake_case." }, "responsible_role": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$" }, "responsibleRole": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$", "description": "Input alias for `responsible_role`; responses use snake_case." }, "confirm_role": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$" }, "confirmRole": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_]{1,48}$", "description": "Input alias for `confirm_role`; responses use snake_case." }, "closing_dependency": { "type": "boolean", "default": false }, "closingDependency": { "type": "boolean", "description": "Input alias for `closing_dependency`; responses use snake_case." } } } } } }, "created_at": { "type": "string", "format": "date-time" }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } } } } }, "400": { "description": "The working-group path id is not a UUID.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing or invalid bearer credential.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } }, "403": { "description": "Caller is not an active member with the required group role.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Membership or catalog read failed.", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listRoomDealTemplates_DealTemplates", "resource_uri": "yf://agents/working-groups/{id}/deal-templates", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/working-groups/$GROUP_ID/deal-templates?deal_type=abs\"" } ], "x-related": [ { "operationId": "listMyDealTemplates_DealTemplates", "relation": "owner-catalog" }, { "operationId": "classifyDeal_WorkingGroups", "relation": "deal-type-source" } ] } }, "/working-groups/{id}/documents": { "get": { "operationId": "listGroupDocuments_GroupDocuments", "x-method": "GET", "x-path": "/working-groups/{id}/documents", "x-handler": "wg::list_group_documents", "tags": [ "Group Documents" ], "summary": "List documents owned by the working group", "description": "Returns a bounded page of the group's economy catalog and local-only\ninventory, deduplicated by document id. Search and sorting apply to the\nentire merged inventory before SQL pagination, including files beyond\noffset 100000. Omitted pagination parameters return the first 100 rows.\n\n`sort` defaults to `created_desc` (date added, newest first); it also accepts\n`created_asc`, `name_asc`, `name_desc`, `size_asc`, and `size_desc`. Date added\nmeans `created_at`, not publication or last update time. Names compare\ncase-insensitively with a deterministic C collation. Unknown dates and\nsizes sort last in either direction; document id and frame KG break ties.\nSize is the latest stored original's byte count under the frame's own KG,\nwith economy metadata as a fallback when no stored original is available.\n\nUse `pagination=cursor` for the first page, then pass `next_cursor` as\n`cursor` with the same `q` and `sort`. Cursor requests seek a workspace-scoped\nindex over stored inventory metadata, including size; they do not scan an\noffset-sized prefix or join originals across the whole inventory. Each arm\ncontributes at most limit + 1 candidates to the local/economy merge.\n`total` is exact on the first page and null on continuations: retain the\nfirst count while paging. `has_more` comes from one-row lookahead.\n\nCursors are opaque positions bound to the workspace, search, and sort.\nChanging any of those requires a fresh first page. Malformed or mismatched\ncursors return 400. Inserts/deletes before a cursor do not shift its next\npage; changing an existing row's sort key can move it across the cursor.\nThis is live traversal, not a snapshot. Identity tie-breakers follow the\nselected direction. Unknown sizes/dates remain last in both directions.\n\nOffset pagination remains available for existing callers, with an exact\ncount on each request; deep offsets still cost more database work. Name\nsearches can inspect matching rows and sort smaller filtered sets even in\ncursor mode. The remote economy's existing catalog contract is unchanged.\nOnly scalar metadata leaves the database; bodies and embeddings are never\nloaded for this listing.\n\nRows are enriched with the most recent content `kg_id`. Readiness is derived\nfrom the current admitted document generation rather than mere KG existence:\nfor generic lifecycle rows, vector `ready` projects to `active`,\n`failed`/`superseded` to `error`, `not_requested` to `stored`, and\n`queued`/`processing` to `processing`. Workflow-specific interactive statuses\nare preserved. A generation-less legacy content KG promotes only a\n`queued`/`processing` row to `active`.\n\nRows with a current generation additionally carry the raw two-axis tier\nstatuses `vector_status` and `graph_status` (additive; omitted for\ngeneration-less legacy docs), so clients can render \"vector done, KG\npending\" and offer graph promotion\n(`POST /pipelines/kgs/{kg_id}/documents/{document_id}/promote-graph`)\noutside deal rooms.\n\nAuth: bearer JWT; caller must hold `ViewDocuments`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size; defaults to 100 and is clamped to 1..500.\n", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "pagination", "in": "query", "required": false, "description": "Use cursor for indexed sequential traversal; offset preserves the existing API.", "schema": { "type": "string", "enum": [ "offset", "cursor" ], "default": "offset" } }, { "name": "cursor", "in": "query", "required": false, "description": "Pass the previous next_cursor unchanged. Implies cursor pagination; cannot be combined with a nonzero offset.", "schema": { "type": "string", "maxLength": 16384 } }, { "name": "offset", "in": "query", "required": false, "description": "Rows to skip; defaults to 0. Offset plus the clamped limit and one lookahead row must fit a signed 64-bit integer.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "q", "in": "query", "required": false, "description": "Only documents whose title contains every word of this, in any order,\ncase-insensitively (`%` and `_` are literal) — `asset register` finds\n`Qord-Legacy-Asset-Register.xlsx`. Applied to the merged listing, so the\npage and `pagination.total` agree; blank is no filter.\n", "schema": { "type": "string", "maxLength": 200 } }, { "name": "sort", "in": "query", "required": false, "description": "Order of the entire matching inventory. Start a fresh first page when changing sort or search.", "schema": { "type": "string", "enum": [ "created_desc", "created_asc", "name_asc", "name_desc", "size_asc", "size_desc" ], "default": "created_desc" } } ], "responses": { "200": { "description": "Merged document page plus additive pagination metadata.", "content": { "application/json": { "schema": { "type": "object", "description": "The historical `documents` array is unchanged. `pagination` is additive,\nso existing response consumers that ignore unknown fields remain valid.\n", "required": [ "documents", "pagination" ], "properties": { "documents": { "type": "array", "items": { "type": "object", "description": "Runtime `economy::protocol::DocumentInfo` projection returned by the\nworking-group inventory. Readiness is normalized from the current document\ngeneration when one exists; `kg_id` is the content KG produced from the\ndocument when one exists, else the KG the document lives in (a workspace\nnotebook for a dropped file), and is omitted only for a row with neither.\n", "required": [ "id", "title", "document_type", "status", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "document_type": { "type": "string" }, "kg_id": { "type": "string", "format": "uuid", "description": "Most recent per-document content KG id, else the KG the document\nframe lives in (a file dropped into a workspace is written into its\nnotebook KG and produces no KG of its own). Omitted when neither\nis known.\n" }, "status": { "type": "string", "description": "For generic lifecycle rows (`queued`, `processing`, `stored`, `active`,\n`error`, or `unpublished`), the current admitted generation projects\nvector `ready` to `active`, `failed`/`superseded` to `error`,\n`not_requested` to `stored`, and `queued`/`processing` to `processing`.\nWorkflow-specific interactive statuses (for example `vocab_review`)\npass through unchanged. A legacy generation-less content KG promotes\nonly `queued`/`processing` rows to `active`.\n", "examples": [ "active", "processing", "stored", "error", "vocab_review" ] }, "vector_status": { "type": "string", "enum": [ "not_requested", "queued", "processing", "ready", "failed", "superseded" ], "description": "Additive. Vector-tier status of the current admitted document\ngeneration, looked up under the row's `kg_id` (the content KG, or\nthe KG the frame lives in). Omitted when no generation exists\n(legacy docs).\n" }, "graph_status": { "type": "string", "enum": [ "not_requested", "queued", "processing", "ready", "failed", "stale", "superseded" ], "description": "Additive. Graph-tier status of the current admitted document\ngeneration. `not_requested` alongside vector `ready` means the\ndocument is eligible for graph promotion via\n`POST /pipelines/kgs/{kg_id}/documents/{document_id}/promote-graph`.\nOmitted when no generation exists (legacy docs).\n" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Set for local rows; an economy implementation may omit it." }, "source_type": { "type": "string", "description": "Additive. Where the file came in from, as the ingest recorded it —\n`upload`, a feed name, an email mirror. Omitted when the row does not\nsay or an economy implementation does not know.\n", "examples": [ "upload", "drive-feed" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Additive. The inventory row's last write — a stage change, a\nreprocess. Omitted when unknown.\n" }, "size_bytes": { "type": "integer", "minimum": 1, "description": "Additive. The stored original's size, when the ingest kept the\noriginal (`kgf.document_sources`), else the economy-reported size.\nOmitted when neither is known. Not the extracted text's length.\nThe same value is used for size sorting; unknown sizes sort last.\n" }, "media_type": { "type": "string", "description": "Additive. The stored original's media type (`application/pdf`,\n`image/png`, `text/plain; charset=utf-8`…), same conditions as\n`size_bytes`. What `GET …/documents/{docid}/download` serves.\n", "examples": [ "application/pdf", "image/png" ] } } } }, "pagination": { "type": "object", "description": "Cursor or legacy offset metadata for the merged operator/local inventory. Traversal is\navailable across the entire matching inventory.\n", "required": [ "limit", "offset", "has_more", "next_offset", "next_cursor", "truncated", "total" ], "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 500 }, "offset": { "type": "integer", "minimum": 0 }, "has_more": { "type": "boolean", "description": "True when more matching rows exist after this page.\n" }, "next_offset": { "type": [ "integer", "null" ], "minimum": 0, "description": "Next accepted offset in offset mode when another page exists; null in cursor mode or at the end." }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque position for the next cursor page, bound to the workspace, search, and sort; null at the end. Also returned to offset callers so they can switch to cursor traversal." }, "truncated": { "type": "boolean", "description": "Retained for compatibility. Always false; there is no fixed traversal window.\n" }, "total": { "type": [ "integer", "null" ], "minimum": 0, "description": "Exact whole-inventory match count on the first cursor page and all\noffset pages; null on cursor continuations, which do not recount.\nClients retain the first-page count until restarting the listing.\n" } } } } }, "examples": { "vector-ready-page": { "summary": "First page with another page available", "value": { "documents": [ { "id": "8b6b31b8-3a7d-4d98-a759-e2160f1e1f28", "title": "Credit package", "document_type": "pdf", "status": "active", "created_at": "2027-05-17T13:00:00Z", "kg_id": "4f1c7a8e-2b6f-4f01-9a2d-3a5d2c1e7b81", "vector_status": "ready", "graph_status": "not_requested" } ], "pagination": { "limit": 100, "offset": 0, "has_more": true, "next_offset": 100, "next_cursor": "opaque-continuation-position", "total": 1304, "truncated": false } } } } } } }, "400": { "description": "Invalid pagination mode or sort, malformed/mismatched cursor, cursor with nonzero offset, or offset plus limit and lookahead exceeds the signed 64-bit range.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listGroupDocuments_GroupDocuments", "resource_uri": "yf://agents/group-documents", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/working-groups/{id}/documents?limit=100&pagination=cursor&sort=size_desc\"" } ], "x-related": [ { "operationId": "downloadGroupDocument_GroupDocuments", "relation": "sibling" }, { "operationId": "updateGroupDocument_GroupDocuments", "relation": "sibling" }, { "operationId": "deleteGroupDocument_GroupDocuments", "relation": "sibling" }, { "guide": "working-groups", "relation": "concept" } ] } }, "/working-groups/{id}/documents/{docid}": { "patch": { "operationId": "updateGroupDocument_GroupDocuments", "x-method": "PATCH", "x-path": "/working-groups/{id}/documents/{docid}", "x-handler": "wg::update_group_document", "tags": [ "Group Documents" ], "summary": "Update a document's title or content (re-chunk if content changed)", "description": "Patches a document's `title`, `content` (raw text) or `content_base64`\n(PDF binary), and `document_type`. The document frame is updated in\nplace. When the resolved content's hash differs from the stored hash,\nthe document is re-chunked and re-embedded atomically so RAG retrieval\nnever serves a partial replacement generation. The document must resolve to\nexactly one KG inside the requested working group; an ambiguous legacy UUID\nreturns 409 instead of updating several graphs. PDFs go through a layout-aware\npdfium→Markdown extractor before chunking. Auth: bearer JWT; caller\nmust hold `UploadDocuments`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "docid", "in": "path", "required": true, "description": "Document id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Patch — supply at least one of `title`, `content`, or `content_base64`.\nContent changes trigger re-chunking + re-embedding.\n", "properties": { "title": { "type": [ "string", "null" ] }, "content": { "type": [ "string", "null" ] }, "content_base64": { "type": [ "string", "null" ], "description": "Base64 PDF; decoded server-side when `document_type` is `pdf`." }, "document_type": { "type": [ "string", "null" ] } } }, "examples": { "rename": { "summary": "Rename only", "value": { "title": "Counterparty memo — v2" } }, "replace-text": { "summary": "Replace content with new raw text", "value": { "title": "Counterparty memo — v2", "content": "Updated body text here." } }, "replace-pdf": { "summary": "Replace content with a PDF (base64)", "value": { "title": "Counterparty memo — v2.pdf", "document_type": "pdf", "content_base64": "JVBERi0xLjQK..." } } } } } }, "responses": { "200": { "description": "Update result. `chunks_recreated` is set when content changed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "document_id", "content_changed" ], "properties": { "document_id": { "type": "string", "format": "uuid" }, "content_changed": { "type": "boolean" }, "chunks_recreated": { "type": [ "integer", "null" ], "minimum": 0 } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "409": { "description": "Conflicting state (e.g. step already completed, intent already cancelled, duplicate idempotency key with different body).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_updateGroupDocument_GroupDocuments", "resource_uri": "yf://agents/group-documents", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PATCH -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"title\":\"renamed.txt\"}' \\\n https://agents.yieldfabric.com/working-groups/{id}/documents/{docid}\n" } ], "x-related": [ { "operationId": "deleteGroupDocument_GroupDocuments", "relation": "sibling" }, { "operationId": "downloadGroupDocument_GroupDocuments", "relation": "sibling" }, { "guide": "working-groups", "relation": "concept" } ] }, "delete": { "operationId": "deleteGroupDocument_GroupDocuments", "x-method": "DELETE", "x-path": "/working-groups/{id}/documents/{docid}", "x-handler": "wg::delete_group_document", "tags": [ "Group Documents" ], "summary": "Delete a document and its derived substrate", "description": "Atomically removes the working group's owned document substrate. The\nservice resolves and locks the document through the `(group id, document\nid)` pair; a document UUID that exists only in another group is not a\nmatch. A dedicated per-document KG is deleted in full. A shared notebook\nKG survives while only the selected document, its chunks, structural\nrelations, and extraction frames left without provenance are removed.\nResponse carries deletion counts for visibility. The operation remains\nidempotent: a missing document and a document UUID owned only by another\ngroup both return the normal success shape with zero counts, avoiding an\nexistence oracle. Auth: bearer JWT; caller must hold `DeleteDocuments`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "docid", "in": "path", "required": true, "description": "Document id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deletion result.", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted", "document_id" ], "properties": { "deleted": { "type": "boolean" }, "document_id": { "type": "string", "format": "uuid" }, "kgs_deleted": { "type": [ "integer", "null" ], "minimum": 0, "description": "Dedicated per-document knowledge graphs removed." }, "chunks_deleted": { "type": [ "integer", "null" ], "minimum": 0, "description": "Chunk frames removed directly or with a dedicated KG." }, "frames_deleted": { "type": [ "integer", "null" ], "minimum": 0, "description": "Structural and now-unprovenanced extraction frames removed." } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_deleteGroupDocument_GroupDocuments", "resource_uri": "yf://agents/group-documents", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X DELETE -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/{id}/documents/{docid}" } ], "x-related": [ { "operationId": "listGroupDocuments_GroupDocuments", "relation": "sibling" }, { "guide": "working-groups", "relation": "concept" } ] } }, "/working-groups/{id}/documents/{docid}/download": { "get": { "operationId": "downloadGroupDocument_GroupDocuments", "x-method": "GET", "x-path": "/working-groups/{id}/documents/{docid}/download", "x-handler": "wg::download_group_document", "tags": [ "Group Documents" ], "summary": "Stream the document's bytes back to the caller", "description": "Returns the retained replay payload when the working-group-owned document\nhas an encrypted `document_sources` record. Uploaded file/PDF bytes are\nexact; URL-ingested HTML is the normalized text used by extraction. The\nstored media type and sanitized filename drive the response. The source UUID\nitself is never\naccepted as authorization; lookup is scoped by the path working group and\ndocument id.\n\nOlder rows without a retained encrypted source preserve compatibility:\nlegacy PDF metadata is decoded when present, otherwise the handler streams\nextracted text. An expired source follows the same fallback; source\nretention does not delete extracted KG content. The handler always sets a\n`Content-Disposition: attachment; filename=\"...\"` header so browsers\nprompt to save. Auth: bearer JWT; caller must hold `DownloadDocuments`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "docid", "in": "path", "required": true, "description": "Document id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Retained replay bytes when present, otherwise the compatible extracted-text representation.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_downloadGroupDocument_GroupDocuments", "resource_uri": "yf://agents/group-documents", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -OJ -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/{id}/documents/{docid}/download" } ], "x-related": [ { "operationId": "listGroupDocuments_GroupDocuments", "relation": "sibling" }, { "operationId": "updateGroupDocument_GroupDocuments", "relation": "sibling" }, { "guide": "working-groups", "relation": "concept" } ] } }, "/working-groups/{id}/federation": { "post": { "operationId": "createFederationPolicy_Federation", "x-method": "POST", "x-path": "/working-groups/{id}/federation", "x-handler": "wg::create_federation_policy", "tags": [ "Federation" ], "summary": "Grant another group read access to this group's knowledge", "description": "Inserts (or upserts on the `(source_group_id, target_group_id)` unique\nconstraint) a `knowledge_federation_policies` row that grants the\n`target_group_id` read access to this group's documents via\n`federatedRagQuery`. `policy_type` controls the breadth of access\n(`full`, `selective`, `summary_only`). With `policy_type='selective'`,\nthe `allowed_document_types` and `allowed_tags` arrays narrow what the\ntarget group can retrieve. Idempotent (upsert). Auth: bearer JWT;\ncaller must hold `ManageGroup` on the SOURCE group.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target_group_id", "policy_type" ], "properties": { "target_group_id": { "type": "string", "format": "uuid" }, "policy_type": { "type": "string", "enum": [ "full", "selective", "summary_only" ] }, "allowed_document_types": { "type": "array", "items": { "type": "string" } }, "allowed_tags": { "type": "array", "items": { "type": "string" } }, "require_approval": { "type": "boolean", "default": false } } }, "examples": { "full-share": { "summary": "Full federation grant", "value": { "target_group_id": "8c7e1a32-1111-4e44-b9d1-aaaaaaaaaaaa", "policy_type": "full", "require_approval": false } }, "selective": { "summary": "Share only docs tagged \"public\"", "value": { "target_group_id": "8c7e1a32-2222-4e44-b9d1-bbbbbbbbbbbb", "policy_type": "selective", "allowed_tags": [ "public" ], "allowed_document_types": [ "memo", "report" ], "require_approval": true } } } } } }, "responses": { "201": { "description": "Policy created (or upserted).", "content": { "application/json": { "schema": { "type": "object", "required": [ "policy_id", "source_group_id", "target_group_id", "policy_type" ], "properties": { "policy_id": { "type": "string", "format": "uuid" }, "source_group_id": { "type": "string", "format": "uuid" }, "target_group_id": { "type": "string", "format": "uuid" }, "policy_type": { "type": "string", "enum": [ "full", "selective", "summary_only" ] } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "409": { "description": "Conflicting state (e.g. step already completed, intent already cancelled, duplicate idempotency key with different body).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_createFederationPolicy_Federation", "resource_uri": "yf://agents/federation", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"target_group_id\":\"\",\"policy_type\":\"full\"}' \\\n https://agents.yieldfabric.com/working-groups/{id}/federation\n" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx\nr = httpx.post(\n f\"https://agents.yieldfabric.com/working-groups/{gid}/federation\",\n headers={\"Authorization\": f\"Bearer {jwt}\"},\n json={\"target_group_id\": str(target), \"policy_type\": \"full\"},\n)\nr.raise_for_status()\n" } ], "x-related": [ { "operationId": "listFederationPolicies_Federation", "relation": "sibling" }, { "operationId": "revokeFederationPolicy_Federation", "relation": "sibling" }, { "operationId": "federatedRagQuery_WorkingGroups", "relation": "next-step" }, { "guide": "working-groups", "relation": "concept" } ] }, "get": { "operationId": "listFederationPolicies_Federation", "x-method": "GET", "x-path": "/working-groups/{id}/federation", "x-handler": "wg::list_federation_policies", "tags": [ "Federation" ], "summary": "List federation policies for this group", "description": "Returns every active federation policy where this group is either the\nsource (outbound — \"we grant X access to us\") or the target (inbound\n— \"X granted us access to them\"). Each row carries\n`direction: 'outbound' | 'inbound'`, the policy type, and the optional\ndocument-type / tag filters. Auth: bearer JWT; caller must hold\n`ViewGroup`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "policies" ], "properties": { "policies": { "type": "array", "items": { "type": "object", "description": "A row from `knowledge_federation_policies` — one group grants another\nread access to its KG with specific scope/filters.\n", "required": [ "id", "source_group_id", "target_group_id", "policy_type", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "source_group_id": { "type": "string", "format": "uuid" }, "target_group_id": { "type": "string", "format": "uuid" }, "policy_type": { "type": "string", "enum": [ "full", "selective", "summary_only" ] }, "allowed_document_types": { "type": "array", "items": { "type": "string" } }, "allowed_tags": { "type": "array", "items": { "type": "string" } }, "require_approval": { "type": "boolean", "default": false }, "granted_by": { "type": "string", "description": "entity_id of the actor who granted federation." }, "status": { "type": "string", "enum": [ "active", "revoked" ] }, "direction": { "type": "string", "description": "Returned on list — `outbound` when the calling group is the source,\n`inbound` when the calling group is the target.\n", "enum": [ "outbound", "inbound" ] } } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listFederationPolicies_Federation", "resource_uri": "yf://agents/federation", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/{id}/federation" } ], "x-related": [ { "operationId": "createFederationPolicy_Federation", "relation": "sibling" }, { "operationId": "revokeFederationPolicy_Federation", "relation": "sibling" }, { "guide": "working-groups", "relation": "concept" } ] } }, "/working-groups/{id}/federation/{pid}": { "delete": { "operationId": "revokeFederationPolicy_Federation", "x-method": "DELETE", "x-path": "/working-groups/{id}/federation/{pid}", "x-handler": "wg::revoke_federation_policy", "tags": [ "Federation" ], "summary": "Revoke a federation policy this group granted", "description": "Marks an outbound federation policy as `revoked`. Only the source\ngroup can revoke (the policy id must belong to a row where\n`source_group_id = {id}`); attempts to revoke an inbound policy\nreturn 404. Auth: bearer JWT; caller must hold `ManageGroup`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "pid", "in": "path", "required": true, "description": "Federation policy id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Policy revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "revoked", "policy_id" ], "properties": { "revoked": { "type": "boolean" }, "policy_id": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_revokeFederationPolicy_Federation", "resource_uri": "yf://agents/federation", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X DELETE -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/{id}/federation/{pid}" } ], "x-related": [ { "operationId": "createFederationPolicy_Federation", "relation": "sibling" }, { "operationId": "listFederationPolicies_Federation", "relation": "sibling" }, { "guide": "working-groups", "relation": "concept" } ] } }, "/working-groups/{id}/feedback": { "post": { "operationId": "submitFeedback_Feedback", "x-method": "POST", "x-path": "/working-groups/{id}/feedback", "x-handler": "wg::submit_feedback", "tags": [ "Feedback" ], "summary": "Submit feedback on a knowledge artifact", "description": "Records user feedback against any feedback-bearing target — currently\nKG chunks and extracted entities. The handler validates `target_type`\nand `feedback_type` against the enums in\n`knowledge_graph::feedback::FeedbackTargetType` and `FeedbackType`,\nthen persists a `FeedbackStore` row in `pending` state. Optional fields\ncarry a `rating`, a free-text `comment`, and a `suggested_value` JSON\nblob (e.g. a corrected entity label). Auth: bearer JWT; caller must\nhold `PostMessages` on the group.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target_type", "target_id", "feedback_type" ], "properties": { "target_type": { "type": "string" }, "target_id": { "type": "string" }, "feedback_type": { "type": "string" }, "rating": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 5 }, "comment": { "type": [ "string", "null" ] }, "suggested_value": { "description": "Arbitrary JSON value." } } }, "examples": { "thumbs-down-on-chunk": { "summary": "Flag a retrieval chunk as unhelpful", "value": { "target_type": "chunk", "target_id": "5c1f...", "feedback_type": "thumbs_down", "comment": "chunk text was outdated" } }, "correct-entity": { "summary": "Suggest a corrected entity label", "value": { "target_type": "entity", "target_id": "ent:acme", "feedback_type": "correction", "suggested_value": { "label": "ACME Holdings Ltd." } } } } } } }, "responses": { "201": { "description": "Feedback recorded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "feedback_id", "status" ], "properties": { "feedback_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "applied", "dismissed" ] } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_submitFeedback_Feedback", "resource_uri": "yf://agents/feedback", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"target_type\":\"chunk\",\"target_id\":\"\",\"feedback_type\":\"thumbs_down\"}' \\\n https://agents.yieldfabric.com/working-groups/{id}/feedback\n" } ], "x-related": [ { "operationId": "listFeedback_Feedback", "relation": "sibling" }, { "operationId": "resolveFeedback_Feedback", "relation": "sibling" }, { "guide": "working-groups", "relation": "concept" } ] }, "get": { "operationId": "listFeedback_Feedback", "x-method": "GET", "x-path": "/working-groups/{id}/feedback", "x-handler": "wg::list_feedback", "tags": [ "Feedback" ], "summary": "List pending feedback for the group", "description": "Returns up to 100 `FeedbackStore` rows still in `pending` state for\nthis group, ordered by submission time. Used to power a moderator\ninbox UI. Auth: bearer JWT; caller must hold `ViewDocuments`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Pending feedback items.", "content": { "application/json": { "schema": { "type": "object", "required": [ "feedback" ], "properties": { "feedback": { "type": "array", "items": { "type": "object", "description": "A user-submitted correction or rating against a KG artefact.", "required": [ "id", "target_type", "target_id", "feedback_type", "status", "submitted_by", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "group_id": { "type": [ "string", "null" ], "format": "uuid" }, "submitted_by": { "type": "string", "description": "entity_id of the submitter." }, "target_type": { "type": "string", "description": "What the feedback is about (e.g. `chunk`, `frame`, `kg`)." }, "target_id": { "type": "string", "description": "Identifier of the target artefact." }, "feedback_type": { "type": "string", "description": "Kind of feedback (e.g. `correction`, `rating`, `flag`)." }, "rating": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 5 }, "comment": { "type": [ "string", "null" ] }, "suggested_value": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "applied", "dismissed" ] }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listFeedback_Feedback", "resource_uri": "yf://agents/feedback", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/{id}/feedback" } ], "x-related": [ { "operationId": "submitFeedback_Feedback", "relation": "sibling" }, { "operationId": "resolveFeedback_Feedback", "relation": "sibling" }, { "guide": "working-groups", "relation": "concept" } ] } }, "/working-groups/{id}/feedback/{fid}": { "post": { "operationId": "resolveFeedback_Feedback", "x-method": "POST", "x-path": "/working-groups/{id}/feedback/{fid}", "x-handler": "wg::resolve_feedback", "tags": [ "Feedback" ], "summary": "Resolve a pending feedback item", "description": "Transitions a `FeedbackStore` row out of `pending`. `action='apply'`\nmarks it `applied` (the moderator accepted the suggestion);\n`action='dismiss'` marks it `dismissed`. The handler does NOT\nautomatically apply the suggested change to the target — that's a\ndownstream consumer's responsibility (the UI re-runs the underlying\npipeline or hands the suggestion to a human). Auth: bearer JWT;\ncaller must hold `ManageGroup`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "fid", "in": "path", "required": true, "description": "Feedback id.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "apply", "dismiss" ] } } }, "examples": { "apply": { "summary": "Accept the suggestion", "value": { "action": "apply" } }, "dismiss": { "summary": "Dismiss the item", "value": { "action": "dismiss" } } } } } }, "responses": { "200": { "description": "Resolution recorded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "feedback_id", "status" ], "properties": { "feedback_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "applied", "dismissed" ] } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_resolveFeedback_Feedback", "resource_uri": "yf://agents/feedback", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"action\":\"apply\"}' \\\n https://agents.yieldfabric.com/working-groups/{id}/feedback/{fid}\n" } ], "x-related": [ { "operationId": "submitFeedback_Feedback", "relation": "sibling" }, { "operationId": "listFeedback_Feedback", "relation": "sibling" }, { "guide": "working-groups", "relation": "concept" } ] } }, "/working-groups/{id}/files": { "post": { "operationId": "uploadRoomFiles_WorkingGroups", "x-method": "POST", "x-path": "/working-groups/{id}/files", "x-handler": "crate::working_group::deal_room::handlers::upload_room_files", "tags": [ "Working Groups" ], "summary": "Store encrypted files in a deal room", "description": "Accepts one or more multipart file parts, validates filenames, MIME hints and\naggregate size, then seals each file at rest before persisting it. Storage is\nimmediate and does not mint or wait on an on-chain operation. For `text/*`\nand `application/pdf`, the encrypted file and a durable `vector`-admission\nintent commit in the same transaction. The complete multipart bundle is one\nall-or-nothing database transaction: validation, room quota, encryption,\nadmission, or persistence failure rolls back every file and intent in the\nrequest. Fixed boot workers later process that room-fair, leased, retryable\nqueue, so a successful bundle commit cannot lose an intent merely because\nthe process restarts. The response still does not wait for parsing, a\npipeline run, or Vector publication. PostgreSQL also rejects an admission\nwhose requester, active-file state, or manual-versus-email provenance\ndisagrees with the stored file, so internal tooling cannot relabel an email\nattachment as a trusted manual upload.\n\nAutomatic work stops after low-cost Vector/keyword discovery and never\nextracts a semantic graph. Unsupported MIME types (including the XLSX example\nbelow) remain stored and downloadable but report `not_indexed`. Promote a\nselected supported document explicitly through\n`POST /working-groups/{id}/files/{file_id}/promote-graph` when its semantic\ngraph is worth the additional extraction cost. The service resolves the\ninternal KG, document, and current generation; room clients need only retain\nthe returned file id. Automatic `text/*` discovery requires valid UTF-8;\ninvalid text terminally fails Vector admission but leaves the stored file\ndownloadable.\n\nThe caller must be an active Member, must have accepted the room terms, and\nmust use a user credential; service tokens cannot upload. The default bundle\ncap is 100 files and 20 MiB total plaintext; deployments may lower the byte\ncap and configure the file cap within 1..1000. The route transport ceiling is\n21 MiB. Separate per-room byte/file quotas also apply. Auth: bearer JWT.\n\nAn optional UUID `Idempotency-Key` makes ambiguous/lost-response retries\nsafe. The key is scoped to this room and the exact ordered manifest, including\nauthenticated uploader, response title, file order, filename, MIME type,\nsize, SHA-256 and Vector-trust provenance. Replaying the same key and manifest\nreturns the original rows in their original order without another quota\nreservation or Vector-admission insert. Reusing that room/key with a\ndifferent manifest returns `409`. Omitting the header retains the historical\nnon-idempotent behavior. The first-party app sends one UUID per sequential\natomic bundle and retains it while a response remains ambiguous.\n\nA per-replica semaphore admits at most\n`ROOM_FILES_MAX_CONCURRENT_UPLOADS` handlers (default 4, valid 1..64).\nEach may retain approximately the plaintext and encrypted bundle together\nuntil commit; at the 20 MiB byte cap, four full slots are roughly 160 MiB plus\nmultipart, encryption and SQL overhead. A request receives `503` before its\nmultipart body is read when all slots are occupied.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Caller-generated UUID scoped to one room and exact ordered upload manifest.\nReplaying the same manifest returns the original 200 response rows without\nduplicate storage, quota, or Vector work. Reuse with a different manifest\nreturns 409.\n", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "additionalProperties": true, "description": "Multipart form. Send one or more `files` parts (the singular `file` name is also accepted) plus an optional text `title`. Unknown form fields are ignored. The complete bundle commits atomically. The default limits are 100 file parts and 20 MiB aggregate plaintext (the byte cap can only be lowered; the configurable file cap is 1..1000), with a fixed 21 MiB route transport ceiling. Per-room byte/file storage quotas are checked against the whole bundle before any row becomes visible. Supply the operation's optional UUID `Idempotency-Key` header to replay an unacknowledged exact ordered bundle without duplicating its rows, quota, or Vector work.", "properties": { "title": { "type": "string" }, "files": { "type": "array", "minItems": 1, "items": { "type": "string", "format": "binary" } }, "file": { "type": "string", "format": "binary" } }, "anyOf": [ { "required": [ "files" ] }, { "required": [ "file" ] } ] } } } }, "responses": { "200": { "description": "The entire file bundle was sealed and persisted; metadata contains no\nplaintext bytes and no file from the request was partially committed.\nSupported files also have a transactionally durable Vector-admission\nintent, but may still report queued/indexing after this response.\n", "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "files" ], "properties": { "title": { "type": "string" }, "files": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "id", "filename", "mime_type", "size_bytes", "sha256", "source_message_id", "uploaded_by", "uploaded_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "filename": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer", "format": "int64", "minimum": 0 }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "source_message_id": { "type": [ "string", "null" ], "format": "uuid" }, "uploaded_by": { "type": "string" }, "uploaded_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } } } } }, "400": { "description": "Missing file parts, malformed multipart or Idempotency-Key, or blocked filename/MIME." }, "401": { "description": "Missing or invalid bearer credential." }, "403": { "description": "Caller is not an eligible terms-accepted Member, or used a service token." }, "409": { "description": "The room-scoped Idempotency-Key was already committed for a different\nordered upload manifest. No new file, quota, or Vector-admission row is\ncreated.\n", "content": { "text/plain": { "schema": { "type": "string" } } } }, "413": { "description": "Bundle exceeds the configured byte/file or route body limit, or admitting\nthe complete bundle would exceed the room's byte/file storage quota. No\nfile from the request is committed.\n" }, "500": { "description": "Encrypted file or transactional Vector-admission persistence failed." }, "503": { "description": "This replica's bounded upload slots are all occupied. The request is\nrejected before multipart parsing and may be retried shortly.\n", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_uploadRoomFiles_WorkingGroups", "resource_uri": "yf://agents/working-groups", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST https://agents.yieldfabric.com/working-groups/{id}/files \\\n -H \"Authorization: Bearer $JWT\" \\\n -H \"Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000\" \\\n -F 'title=Credit package' \\\n -F 'files=@term-sheet.pdf;type=application/pdf' \\\n -F 'files=@model.xlsx;type=application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'\n" } ], "x-related": [ { "operationId": "downloadRoomFile_WorkingGroups", "relation": "sibling" }, { "operationId": "promoteRoomFileGraph_WorkingGroups", "relation": "next-step" } ] } }, "/working-groups/{id}/files/{file_id}/download": { "get": { "operationId": "downloadRoomFile_WorkingGroups", "x-method": "GET", "x-path": "/working-groups/{id}/files/{file_id}/download", "x-handler": "crate::working_group::deal_room::handlers::download_room_file", "tags": [ "Working Groups" ], "summary": "Download a decrypted deal-room file", "description": "Returns the file's decrypted bytes only after checking Viewer access and the\nroom's accepted-terms gate. Lookup is scoped by both room id and file id, so\na valid id from another room cannot be used to bypass tenant isolation.\nThe response uses the stored MIME type, a sanitized attachment filename,\n`Content-Length`, and `X-Content-Type-Options: nosniff`. Auth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Decrypted file bytes with the stored media type.", "headers": { "Content-Disposition": { "schema": { "type": "string" }, "description": "Sanitized attachment filename." }, "Content-Length": { "schema": { "type": "integer", "format": "int64" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } } }, "content": { "*/*": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Missing or invalid bearer credential." }, "403": { "description": "Caller lacks terms-accepted Viewer access to the room." }, "404": { "description": "File does not exist in this room." }, "500": { "description": "File lookup, decryption, or response construction failed." } }, "x-mcp": { "tool_name": "yieldfabric_agents_downloadRoomFile_WorkingGroups", "resource_uri": "yf://agents/working-groups", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -OJ -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/{id}/files/{file_id}/download" } ], "x-related": [ { "operationId": "uploadRoomFiles_WorkingGroups", "relation": "sibling" }, { "operationId": "promoteRoomFileGraph_WorkingGroups", "relation": "sibling" } ] } }, "/working-groups/{id}/files/{file_id}/promote-graph": { "post": { "operationId": "promoteRoomFileGraph_WorkingGroups", "x-method": "POST", "x-path": "/working-groups/{id}/files/{file_id}/promote-graph", "x-handler": "crate::working_group::deal_room::handlers::promote_room_file_graph", "tags": [ "Working Groups" ], "summary": "Promote a vector-indexed room file into a semantic graph", "description": "Request the optional semantic-graph stage for a deal-room file. The caller\nsupplies only the room and file ids. The service scopes the file lookup by\n`(room_id, file_id)`, resolves its current linked document, KG, and immutable\ngeneration server-side, then delegates to the same exact-generation\npromotion path used by the pipeline API. Clients must not discover or submit\ninternal `kg_id` or `document_id` values.\n\nA successful call returns the normal pipeline start envelope. Poll\n`GET /pipelines/{run_id}` or subscribe to its SSE stream. Repeated calls for\nthe same current generation converge on its existing queued, running,\npaused, or completed promotion instead of scheduling duplicate extraction.\nA request after a failed or cancelled run is an intentional retry and may\nstart a new billable graph-extraction attempt; automated clients must not\nblindly retry this POST.\n\nVector retrieval remains available while graph extraction runs and after a\ngraph failure; staging frames are not readable before atomic publication.\n\nThe caller must use a user credential and be an active, terms-accepted\nMember of the room. A file id from another room is not distinguishable from\na missing file. This is an additive convenience endpoint: it does not change\nroom-file upload/download responses, the GraphQL `RoomFile` shape, pipeline\nstatus/SSE contracts, or the lower-level KG/document promotion endpoint.\nAuth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "file_id", "in": "path", "required": true, "description": "Deal-room file to promote; resolved only within the working group.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Existing or newly accepted graph-promotion pipeline run.", "content": { "application/json": { "schema": { "type": "object", "required": [ "run_id", "kg_id" ], "properties": { "run_id": { "type": "string", "format": "uuid" }, "kg_id": { "type": "string", "format": "uuid" }, "thread_id": { "type": [ "string", "null" ] } } }, "examples": { "accepted-or-existing": { "summary": "Promotion run for the resolved room file", "value": { "run_id": "9d3b1a2c-5e6f-4d7a-8b9c-0d1e2f3a4b5c", "kg_id": "4f1c7a8e-2b6f-4f01-9a2d-3a5d2c1e7b81", "thread_id": null } } } } } }, "400": { "description": "A path id is malformed.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "The bearer credential is missing or invalid.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } }, "403": { "description": "Caller is not an eligible terms-accepted Member, or used a service token.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "File is absent or not active in this room.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "No content KG/vector index exists yet, the vector generation is not\nready, or the retained source is unavailable.\n", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "File resolution or promotion persistence failed.", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_promoteRoomFileGraph_WorkingGroups", "resource_uri": "yf://agents/working-groups", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n \"https://agents.yieldfabric.com/working-groups/$GROUP_ID/files/$FILE_ID/promote-graph\"\n" } ], "x-related": [ { "operationId": "uploadRoomFiles_WorkingGroups", "relation": "sibling" }, { "operationId": "downloadRoomFile_WorkingGroups", "relation": "sibling" }, { "operationId": "promoteDocumentGraph_Pipelines", "relation": "delegates-to" }, { "operationId": "getPipelineRun_Pipelines", "relation": "next-step" }, { "operationId": "pipelineEvents_Pipelines", "relation": "next-step" } ] } }, "/working-groups/{id}/intents": { "get": { "operationId": "listIntents_Intents", "x-method": "GET", "x-path": "/working-groups/{id}/intents", "x-handler": "wg::list_intents", "tags": [ "Intents" ], "summary": "List financial intents proposed in the group", "description": "Lists `financial_intents` rows for the group with optional filters.\nAn intent is an agent-proposed action that the user reviews, modifies,\nconfirms, and (on confirm) the service dispatches. Three flavours\nexist: `action` (single payments operation), `pipeline` (multi-step\nworkflow draft), and `composed` (atomic batch routed to\n`composedFlow.executeComposedOperations`). Optional query filters:\n`thread_id`, `status`, `intent_type`. Auth: bearer JWT; caller must\nhold `ViewWorkflows`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "thread_id", "in": "query", "required": false, "description": "Filter intents to those proposed in a specific thread.", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by lifecycle status (`proposed`, `confirmed`, `executing`, `completed`, `failed`, `cancelled`).", "schema": { "type": "string" } }, { "name": "intent_type", "in": "query", "required": false, "description": "Filter by intent_type (`action`, `pipeline`, `composed`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Intents.", "content": { "application/json": { "schema": { "type": "object", "required": [ "intents", "count" ], "properties": { "intents": { "type": "array", "items": { "type": "object", "description": "Agent-proposed financial operation. Two families share the row: legacy\nin-app intents flow proposed → confirmed → executing → completed/failed;\nR2 pinned proposals (`identity_hash` set, filed by `createIntent_Intents`)\nflow proposed → approved (parked) | submitting (leased) → submitted\n→ completed/failed, and only `proposed` may become cancelled/expired.\nAppend-only `intent_audit` log for both. Reads (`getIntent_Intents`,\n`confirmIntent_Intents`) return the row plus the connector wire fields\n`intent_id`, `result`, `error`, `confirm_url`, `recovery`.\n", "required": [ "id", "thread_id", "intent_type", "status", "title", "proposed_by", "arguments", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "intent_id": { "type": "string", "format": "uuid", "description": "The same id under the connector wire contract's name (present on reads)." }, "group_id": { "type": [ "string", "null" ], "format": "uuid" }, "thread_id": { "type": "string" }, "deal_id": { "type": [ "string", "null" ], "format": "uuid" }, "intent_type": { "type": "string", "enum": [ "action", "pipeline", "composed" ] }, "status": { "type": "string", "enum": [ "proposed", "confirmed", "executing", "approved", "submitting", "submitted", "completed", "failed", "cancelled", "expired" ] }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "proposed_by": { "type": "string" }, "tool_name": { "type": [ "string", "null" ], "description": "For `action` intents — MCP tool name to invoke." }, "arguments": { "description": "Arbitrary JSON value." }, "pipeline_steps": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "operations": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "builder_metadata": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "validation_result": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "execution_result": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "workflow_id": { "type": [ "string", "null" ], "format": "uuid" }, "confirmed_by": { "type": [ "string", "null" ] }, "modified_arguments": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ], "description": "User edits to `arguments`. Effective args = arguments + modified." }, "schema_version": { "type": [ "string", "null" ] }, "pattern_id": { "type": [ "string", "null" ] }, "composite_action_id": { "type": [ "string", "null" ] }, "source_analysis_id": { "type": [ "string", "null" ], "format": "uuid" }, "audit_lineage": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "bindings_snapshot": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "chain_id": { "type": [ "string", "null" ], "description": "The chain the proposal executes on; dispatch routes by it, never by the confirmer's session." }, "wallet_id": { "type": [ "string", "null" ], "description": "The wallet the proposal was made for (the proposing session's default wallet on `chain_id`)." }, "actor_entity_id": { "type": [ "string", "null" ], "description": "The account holder the proposal is for — the only entity that may confirm it." }, "request_id": { "type": [ "string", "null" ], "description": "Caller-supplied disambiguator folded into the identity hash." }, "identity_hash": { "type": [ "string", "null" ], "description": "`sha256` of the canonical identity tuple; set ⇒ an R2 pinned proposal." }, "proposal_version": { "type": "integer" }, "proposer_kind": { "type": [ "string", "null" ], "description": "`connector` | `personal` — the session kind that filed it." }, "proposer_agent": { "type": [ "string", "null" ], "description": "`agent_id` / `mcp_agent_id` of the filing credential, when any." }, "approved_by": { "type": [ "string", "null" ] }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" }, "lease_owner": { "type": [ "string", "null" ] }, "lease_until": { "type": [ "string", "null" ], "format": "date-time" }, "submit_attempts": { "type": "integer" }, "recovery_attempts": { "type": "integer" }, "submission_key": { "type": [ "string", "null" ], "description": "The persisted MQ idempotency key (= the intent id)." }, "message_id": { "type": [ "string", "null" ], "description": "The canonical payments message id once submitted — poll it with the message-status endpoint or `wait_for_settlement`." }, "submitted_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_error": { "type": [ "string", "null" ], "description": "The last dispatch / recovery failure text." }, "approval_credential_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the sealed confirmer credential (never returned) stops being usable for an unattended re-drive." }, "result": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ], "description": "`execution_result` under the wire contract's name." }, "error": { "type": [ "string", "null" ], "description": "`last_error` under the wire contract's name." }, "confirm_url": { "type": [ "string", "null" ], "description": "The in-app confirmation page (`/private?reader=intent//`) while the intent is not terminal." }, "recovery": { "type": "string", "enum": [ "none", "in_progress" ], "description": "`in_progress` while a dispatch lease is held (a confirm or the recovery worker owns the row)." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } } }, "count": { "type": "integer", "minimum": 0 } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listIntents_Intents", "resource_uri": "yf://agents/intents", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/working-groups/{id}/intents?status=proposed\"" } ], "x-related": [ { "operationId": "getIntent_Intents", "relation": "child" }, { "operationId": "confirmIntent_Intents", "relation": "next-step" }, { "guide": "intents-and-drafts", "relation": "concept" } ] }, "post": { "operationId": "createIntent_Intents", "x-method": "POST", "x-path": "/working-groups/{id}/intents", "x-handler": "wg::create_intent", "tags": [ "Intents" ], "summary": "File a pinned financial proposal", "description": "Files ONE of the four financial proposals — `yieldfabric_instant`,\n`yieldfabric_accept`, `yieldfabric_swapObligorPayment`,\n`yieldfabric_completeSwap` — as a `financial_intents` row pinned to the\nchain, wallet and actor it was proposed for (spec\n`docs/plans/mcp-agent-surface-scope.md` §5.5). Nothing executes: the\naccount holder confirms in the app (`confirm_url`), agents dispatches\non the pinned chain under a lease (`confirmIntent_Intents`), and\n`getIntent_Intents` / payments' `wait_for_settlement` report the rest.\n\n**Who may call.** A connector session — an RFC 8693 on-behalf-of token\nminted for this service's public URL (what payments' `propose_*` tools\nsend), or a connector `yf_api_…` key — or a direct personal session.\nDelegation, signer-bearing MCP and service credentials are `403\nsession_kind_not_allowed`. The caller must be an active member of the\nworkspace (`ProposeWork`; the owner of a personal workspace passes).\n\n**Pins are asserted against the VERIFIED claims, never trusted:**\n`actor_entity_id` must equal the session's subject (`403\nactor_mismatch`); `chain_id` must be the session's chain (`403\nchain_mismatch`) and inside its `allowed_chains` (`403\nchain_not_allowed`) and routable on this deployment (`400\nchain_unmapped`); `wallet_id` must be the session's default wallet on\nthat chain (`403 wallet_mismatch`).\n\n**Proposals are personal — the actor rule, decided once.** The actor is\nthe session's `sub`, never an `acting_as` group: a delegated session\ncannot file a proposal (auth stamps it `delegated` ⇒ `403\nsession_kind_not_allowed`; a claim carrying `acting_as` under any other\nkind is `403 actor_mismatch`). Payments' `propose_*` tools pin the same\n`sub`; a delegated caller is refused by whichever side sees it first.\n\n**Identity and dedupe.** The proposal identity is\n`sha256(canonical JSON of {actor, wallet, chain, workspace, tool,\narguments (sorted keys, amounts as strings), request_id?})`, enforced by\na partial unique index over the OPEN statuses (`proposed`, `approved`,\n`submitting`, `submitted`). The insert is insert-or-select in one\ntransaction: `201 … created: true` for a new row, `200 … created:\nfalse` with the open intent that already carries the identity — N\nparallel identical proposals yield ONE row. After a terminal status an\nidentical request creates a new proposal; two intentionally identical\npayments while one is open pass a distinct `request_id`.\n\nAmounts stay human-readable (the dispatch scales them by the asset's\ndecimals) and are CANONICALISED before hashing and storing: every\namount-like field (`amount`, `notional`, `*_amount`; numbers or\nstrings) becomes its plain decimal form — `10`, `\"10.0\"`, `\"010.00\"`\nand `\"1,0\"` are all `\"10\"`, `\"12.50\"` is `\"12.5\"` — so the spelling a\nretry uses never mints a second identity. A value that is not a plain\nnon-negative decimal (a sign, an exponent, text) is refused `400\ninvalid_amount` (body `fields`: the offending JSON paths) rather than\nhashed. `thread_id` defaults to the caller's solo thread in the\nworkspace. `expires_at` = now + 15 min (`AGENTS_INTENT_TTL_SECS`). The\nfiling emits `IntentProposed` on the workspace chat stream and reports\na `decision` push item to the actor (`intent:`, retracted on\nconfirm / cancel / expiry).\n\n**A pinned proposal is immutable.** Its `arguments` ARE its identity\nand the only value the confirmation executes: `modifyIntent_Intents`\nrefuses it (`409 intent_pinned`), the store never sets\n`modified_arguments` on it, and the dispatcher refuses a row that\ncarries one. A change is a new proposal.\n\n**Stale open twin.** An identical proposal filed after the open twin's\n`expires_at` but before the 30 s sweep reached it does not receive the\ndead row as \"the open one\": the twin is expired inline (push retracted,\naudit written) and a fresh proposal is created (`201`).\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "The W4 wire contract between payments' `propose_*` tools and agents.", "required": [ "tool_name", "arguments", "chain_id", "wallet_id", "actor_entity_id", "title" ], "properties": { "tool_name": { "type": "string", "enum": [ "yieldfabric_instant", "yieldfabric_accept", "yieldfabric_swapObligorPayment", "yieldfabric_completeSwap" ], "description": "The direct payments tool the proposal executes on confirmation (the bespoke slash aliases are accepted and canonicalised)." }, "arguments": { "description": "Arbitrary JSON value." }, "chain_id": { "type": "string", "description": "Must equal the session's chain (and be inside `allowed_chains`)." }, "wallet_id": { "type": "string", "description": "Must equal the session's default wallet on `chain_id`." }, "actor_entity_id": { "type": "string", "description": "Must equal the session's subject." }, "request_id": { "type": "string", "description": "Optional disambiguator — two intentionally identical proposals while one is open." }, "title": { "type": "string" }, "rationale": { "type": "string" }, "thread_id": { "type": "string", "format": "uuid", "description": "A thread of the workspace; defaults to the caller's solo thread." } } } } } }, "responses": { "200": { "description": "An open proposal with the same identity already existed and is returned (`created: false`).", "content": { "application/json": { "schema": { "type": "object", "required": [ "intent_id", "status", "expires_at", "confirm_url", "created" ], "properties": { "intent_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "description": "`proposed` on creation; the open row's current status when it already existed." }, "expires_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "identity_hash": { "type": [ "string", "null" ] }, "confirm_url": { "type": "string" }, "created": { "type": "boolean", "description": "`true` — this call created the row (201); `false` — an open intent with the same identity already existed (200)." } } } } } }, "201": { "description": "A new pinned proposal was filed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "intent_id", "status", "expires_at", "confirm_url", "created" ], "properties": { "intent_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "description": "`proposed` on creation; the open row's current status when it already existed." }, "expires_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "identity_hash": { "type": [ "string", "null" ] }, "confirm_url": { "type": "string" }, "created": { "type": "boolean", "description": "`true` — this call created the row (201); `false` — an open intent with the same identity already existed (200)." } } } } } }, "400": { "description": "`tool_not_proposable`, `invalid_arguments`, `invalid_amount` (body also carries `fields`), `invalid_title`, `invalid_pins`, `chain_unmapped` (body `{ error, code }`).", "content": { "application/json": { "schema": { "type": "object", "description": "A structured refusal from an intent route. Clients branch on `code`\n(`intent_chain_mismatch`, `intent_expired`, `intent_actor_mismatch`,\n`intent_wallet_mismatch`, `intent_identity_mismatch`,\n`intent_terminal`, `intent_not_proposed`, `intent_pinned`,\n`intent_not_modifiable`, `intent_not_retryable`,\n`intent_dispatch_failed`, `intent_not_found`, `intent_internal`,\n`unauthorized`, `direct_user_session_required`,\n`session_kind_not_allowed`, `actor_mismatch`, `chain_mismatch`,\n`chain_not_allowed`, `chain_unmapped`, `wallet_mismatch`,\n`invalid_amount`, `tool_not_proposable`, …), never on the prose.\nEVERY refusal on the intent routes — 401, 403, 404, 409, 500 — is this\nJSON shape, never text/plain: payments' `intent_status` reader and\nthe app both key on the body. Some codes carry extra keys\n(`pinned_chain_id`, `session_chain_id`, `pinned_wallet_id`,\n`identity_hash`, `status`, `intent`, `fields`, `agent_bound`).\n", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": true } } } }, "401": { "description": "Missing or unreadable credential — JSON `{ error, code: \"unauthorized\" }` like every other refusal on the intent routes.", "content": { "application/json": { "schema": { "type": "object", "description": "A structured refusal from an intent route. Clients branch on `code`\n(`intent_chain_mismatch`, `intent_expired`, `intent_actor_mismatch`,\n`intent_wallet_mismatch`, `intent_identity_mismatch`,\n`intent_terminal`, `intent_not_proposed`, `intent_pinned`,\n`intent_not_modifiable`, `intent_not_retryable`,\n`intent_dispatch_failed`, `intent_not_found`, `intent_internal`,\n`unauthorized`, `direct_user_session_required`,\n`session_kind_not_allowed`, `actor_mismatch`, `chain_mismatch`,\n`chain_not_allowed`, `chain_unmapped`, `wallet_mismatch`,\n`invalid_amount`, `tool_not_proposable`, …), never on the prose.\nEVERY refusal on the intent routes — 401, 403, 404, 409, 500 — is this\nJSON shape, never text/plain: payments' `intent_status` reader and\nthe app both key on the body. Some codes carry extra keys\n(`pinned_chain_id`, `session_chain_id`, `pinned_wallet_id`,\n`identity_hash`, `status`, `intent`, `fields`, `agent_bound`).\n", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "`session_kind_not_allowed`, `actor_mismatch` (also for a claim carrying `acting_as`), `chain_mismatch`, `chain_not_allowed`, `wallet_mismatch`, `workspace_forbidden` (body `{ error, code }`).", "content": { "application/json": { "schema": { "type": "object", "description": "A structured refusal from an intent route. Clients branch on `code`\n(`intent_chain_mismatch`, `intent_expired`, `intent_actor_mismatch`,\n`intent_wallet_mismatch`, `intent_identity_mismatch`,\n`intent_terminal`, `intent_not_proposed`, `intent_pinned`,\n`intent_not_modifiable`, `intent_not_retryable`,\n`intent_dispatch_failed`, `intent_not_found`, `intent_internal`,\n`unauthorized`, `direct_user_session_required`,\n`session_kind_not_allowed`, `actor_mismatch`, `chain_mismatch`,\n`chain_not_allowed`, `chain_unmapped`, `wallet_mismatch`,\n`invalid_amount`, `tool_not_proposable`, …), never on the prose.\nEVERY refusal on the intent routes — 401, 403, 404, 409, 500 — is this\nJSON shape, never text/plain: payments' `intent_status` reader and\nthe app both key on the body. Some codes carry extra keys\n(`pinned_chain_id`, `session_chain_id`, `pinned_wallet_id`,\n`identity_hash`, `status`, `intent`, `fields`, `agent_bound`).\n", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": true } } } }, "404": { "description": "`thread_not_found` — the supplied `thread_id` is not a thread of this workspace.", "content": { "application/json": { "schema": { "type": "object", "description": "A structured refusal from an intent route. Clients branch on `code`\n(`intent_chain_mismatch`, `intent_expired`, `intent_actor_mismatch`,\n`intent_wallet_mismatch`, `intent_identity_mismatch`,\n`intent_terminal`, `intent_not_proposed`, `intent_pinned`,\n`intent_not_modifiable`, `intent_not_retryable`,\n`intent_dispatch_failed`, `intent_not_found`, `intent_internal`,\n`unauthorized`, `direct_user_session_required`,\n`session_kind_not_allowed`, `actor_mismatch`, `chain_mismatch`,\n`chain_not_allowed`, `chain_unmapped`, `wallet_mismatch`,\n`invalid_amount`, `tool_not_proposable`, …), never on the prose.\nEVERY refusal on the intent routes — 401, 403, 404, 409, 500 — is this\nJSON shape, never text/plain: payments' `intent_status` reader and\nthe app both key on the body. Some codes carry extra keys\n(`pinned_chain_id`, `session_chain_id`, `pinned_wallet_id`,\n`identity_hash`, `status`, `intent`, `fields`, `agent_bound`).\n", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": true } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_createIntent_Intents", "resource_uri": "yf://agents/intents", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" \\\n https://agents.yieldfabric.com/working-groups/{id}/intents \\\n -d '{\"tool_name\":\"yieldfabric_instant\",\"arguments\":{\"asset_id\":\"ASSET-1\",\"amount\":\"12.50\",\"destination_wallet_id\":\"\"},\"chain_id\":\"153\",\"wallet_id\":\"\",\"actor_entity_id\":\"\",\"title\":\"Send 12.50 ASSET-1\"}'\n" } ], "x-related": [ { "operationId": "getIntent_Intents", "relation": "read-after-write" }, { "operationId": "confirmIntent_Intents", "relation": "next-step" }, { "operationId": "cancelIntent_Intents", "relation": "alternative" }, { "guide": "intents-and-drafts", "relation": "concept" } ] } }, "/working-groups/{id}/intents/{intent_id}": { "get": { "operationId": "getIntent_Intents", "x-method": "GET", "x-path": "/working-groups/{id}/intents/{intent_id}", "x-handler": "wg::get_intent", "tags": [ "Intents" ], "summary": "Fetch a single financial intent", "description": "Returns the full `FinancialIntent` row — type, status, title,\ndescription, proposed-by, the type-specific payload\n(`arguments` for action intents, `pipeline_steps` for pipeline\nintents, `operations` for composed intents), validation result,\nexecution result, and timestamps — plus, since R2, the pinned-proposal\ncolumns and the connector wire fields (`intent_id`, `result`, `error`,\n`confirm_url`, `recovery`; spec §5.6). Auth: bearer JWT.\n\nAn AUTHORISED read: the proposer, the pinned actor, or an\nactive member of the intent's workspace sees it; anyone else — and a\ncaller naming another workspace in the path — gets `404`, existence\nundisclosed. Payments' `intent_status` MCP tool reads through this\nroute with an on-behalf-of token.\n\nEvery refusal on this route is JSON (`{ error, code }`: `404\nintent_not_found`, `401 unauthorized`, `500 intent_internal`) — never\ntext/plain — because payments' reader maps the status to `not_found`\nonly when the body parses; a text/plain 404 would surface to the\nconnector as `downstream_failed`.\n\nFor a pinned proposal, `arguments` IS what executes: the row is\nimmutable after filing (`modified_arguments` is never set on one), so\nwhat this read shows is what the confirmation submits.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "intent_id", "in": "path", "required": true, "description": "Intent id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Intent row.", "content": { "application/json": { "schema": { "type": "object", "description": "Agent-proposed financial operation. Two families share the row: legacy\nin-app intents flow proposed → confirmed → executing → completed/failed;\nR2 pinned proposals (`identity_hash` set, filed by `createIntent_Intents`)\nflow proposed → approved (parked) | submitting (leased) → submitted\n→ completed/failed, and only `proposed` may become cancelled/expired.\nAppend-only `intent_audit` log for both. Reads (`getIntent_Intents`,\n`confirmIntent_Intents`) return the row plus the connector wire fields\n`intent_id`, `result`, `error`, `confirm_url`, `recovery`.\n", "required": [ "id", "thread_id", "intent_type", "status", "title", "proposed_by", "arguments", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "intent_id": { "type": "string", "format": "uuid", "description": "The same id under the connector wire contract's name (present on reads)." }, "group_id": { "type": [ "string", "null" ], "format": "uuid" }, "thread_id": { "type": "string" }, "deal_id": { "type": [ "string", "null" ], "format": "uuid" }, "intent_type": { "type": "string", "enum": [ "action", "pipeline", "composed" ] }, "status": { "type": "string", "enum": [ "proposed", "confirmed", "executing", "approved", "submitting", "submitted", "completed", "failed", "cancelled", "expired" ] }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "proposed_by": { "type": "string" }, "tool_name": { "type": [ "string", "null" ], "description": "For `action` intents — MCP tool name to invoke." }, "arguments": { "description": "Arbitrary JSON value." }, "pipeline_steps": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "operations": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "builder_metadata": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "validation_result": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "execution_result": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "workflow_id": { "type": [ "string", "null" ], "format": "uuid" }, "confirmed_by": { "type": [ "string", "null" ] }, "modified_arguments": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ], "description": "User edits to `arguments`. Effective args = arguments + modified." }, "schema_version": { "type": [ "string", "null" ] }, "pattern_id": { "type": [ "string", "null" ] }, "composite_action_id": { "type": [ "string", "null" ] }, "source_analysis_id": { "type": [ "string", "null" ], "format": "uuid" }, "audit_lineage": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "bindings_snapshot": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "chain_id": { "type": [ "string", "null" ], "description": "The chain the proposal executes on; dispatch routes by it, never by the confirmer's session." }, "wallet_id": { "type": [ "string", "null" ], "description": "The wallet the proposal was made for (the proposing session's default wallet on `chain_id`)." }, "actor_entity_id": { "type": [ "string", "null" ], "description": "The account holder the proposal is for — the only entity that may confirm it." }, "request_id": { "type": [ "string", "null" ], "description": "Caller-supplied disambiguator folded into the identity hash." }, "identity_hash": { "type": [ "string", "null" ], "description": "`sha256` of the canonical identity tuple; set ⇒ an R2 pinned proposal." }, "proposal_version": { "type": "integer" }, "proposer_kind": { "type": [ "string", "null" ], "description": "`connector` | `personal` — the session kind that filed it." }, "proposer_agent": { "type": [ "string", "null" ], "description": "`agent_id` / `mcp_agent_id` of the filing credential, when any." }, "approved_by": { "type": [ "string", "null" ] }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" }, "lease_owner": { "type": [ "string", "null" ] }, "lease_until": { "type": [ "string", "null" ], "format": "date-time" }, "submit_attempts": { "type": "integer" }, "recovery_attempts": { "type": "integer" }, "submission_key": { "type": [ "string", "null" ], "description": "The persisted MQ idempotency key (= the intent id)." }, "message_id": { "type": [ "string", "null" ], "description": "The canonical payments message id once submitted — poll it with the message-status endpoint or `wait_for_settlement`." }, "submitted_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_error": { "type": [ "string", "null" ], "description": "The last dispatch / recovery failure text." }, "approval_credential_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the sealed confirmer credential (never returned) stops being usable for an unattended re-drive." }, "result": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ], "description": "`execution_result` under the wire contract's name." }, "error": { "type": [ "string", "null" ], "description": "`last_error` under the wire contract's name." }, "confirm_url": { "type": [ "string", "null" ], "description": "The in-app confirmation page (`/private?reader=intent//`) while the intent is not terminal." }, "recovery": { "type": "string", "enum": [ "none", "in_progress" ], "description": "`in_progress` while a dispatch lease is held (a confirm or the recovery worker owns the row)." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "401": { "description": "Missing or unreadable credential — JSON `{ error, code: \"unauthorized\" }`.", "content": { "application/json": { "schema": { "type": "object", "description": "A structured refusal from an intent route. Clients branch on `code`\n(`intent_chain_mismatch`, `intent_expired`, `intent_actor_mismatch`,\n`intent_wallet_mismatch`, `intent_identity_mismatch`,\n`intent_terminal`, `intent_not_proposed`, `intent_pinned`,\n`intent_not_modifiable`, `intent_not_retryable`,\n`intent_dispatch_failed`, `intent_not_found`, `intent_internal`,\n`unauthorized`, `direct_user_session_required`,\n`session_kind_not_allowed`, `actor_mismatch`, `chain_mismatch`,\n`chain_not_allowed`, `chain_unmapped`, `wallet_mismatch`,\n`invalid_amount`, `tool_not_proposable`, …), never on the prose.\nEVERY refusal on the intent routes — 401, 403, 404, 409, 500 — is this\nJSON shape, never text/plain: payments' `intent_status` reader and\nthe app both key on the body. Some codes carry extra keys\n(`pinned_chain_id`, `session_chain_id`, `pinned_wallet_id`,\n`identity_hash`, `status`, `intent`, `fields`, `agent_bound`).\n", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": true } } } }, "404": { "description": "`intent_not_found` — not the caller's to see, or another workspace in the path (existence undisclosed; JSON body).", "content": { "application/json": { "schema": { "type": "object", "description": "A structured refusal from an intent route. Clients branch on `code`\n(`intent_chain_mismatch`, `intent_expired`, `intent_actor_mismatch`,\n`intent_wallet_mismatch`, `intent_identity_mismatch`,\n`intent_terminal`, `intent_not_proposed`, `intent_pinned`,\n`intent_not_modifiable`, `intent_not_retryable`,\n`intent_dispatch_failed`, `intent_not_found`, `intent_internal`,\n`unauthorized`, `direct_user_session_required`,\n`session_kind_not_allowed`, `actor_mismatch`, `chain_mismatch`,\n`chain_not_allowed`, `chain_unmapped`, `wallet_mismatch`,\n`invalid_amount`, `tool_not_proposable`, …), never on the prose.\nEVERY refusal on the intent routes — 401, 403, 404, 409, 500 — is this\nJSON shape, never text/plain: payments' `intent_status` reader and\nthe app both key on the body. Some codes carry extra keys\n(`pinned_chain_id`, `session_chain_id`, `pinned_wallet_id`,\n`identity_hash`, `status`, `intent`, `fields`, `agent_bound`).\n", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": true } } } }, "500": { "description": "`intent_internal` (JSON body).", "content": { "application/json": { "schema": { "type": "object", "description": "A structured refusal from an intent route. Clients branch on `code`\n(`intent_chain_mismatch`, `intent_expired`, `intent_actor_mismatch`,\n`intent_wallet_mismatch`, `intent_identity_mismatch`,\n`intent_terminal`, `intent_not_proposed`, `intent_pinned`,\n`intent_not_modifiable`, `intent_not_retryable`,\n`intent_dispatch_failed`, `intent_not_found`, `intent_internal`,\n`unauthorized`, `direct_user_session_required`,\n`session_kind_not_allowed`, `actor_mismatch`, `chain_mismatch`,\n`chain_not_allowed`, `chain_unmapped`, `wallet_mismatch`,\n`invalid_amount`, `tool_not_proposable`, …), never on the prose.\nEVERY refusal on the intent routes — 401, 403, 404, 409, 500 — is this\nJSON shape, never text/plain: payments' `intent_status` reader and\nthe app both key on the body. Some codes carry extra keys\n(`pinned_chain_id`, `session_chain_id`, `pinned_wallet_id`,\n`identity_hash`, `status`, `intent`, `fields`, `agent_bound`).\n", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": true } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getIntent_Intents", "resource_uri": "yf://agents/intents", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/{id}/intents/{intent_id}" } ], "x-related": [ { "operationId": "getIntentAudit_Intents", "relation": "sibling" }, { "operationId": "modifyIntent_Intents", "relation": "sibling" }, { "operationId": "confirmIntent_Intents", "relation": "next-step" }, { "guide": "intents-and-drafts", "relation": "concept" } ] }, "patch": { "operationId": "modifyIntent_Intents", "x-method": "PATCH", "x-path": "/working-groups/{id}/intents/{intent_id}", "x-handler": "wg::modify_intent", "tags": [ "Intents" ], "summary": "Update an intent's arguments before confirmation", "description": "Modifies a proposed LEGACY intent's per-field overrides\n(`modified_arguments`) in place. Routes through the Box 3 state\nmachine (`crate::intent::modify_intent`) which validates the\ntransition (ONE conditional UPDATE: `proposed` and unpinned, else\n`409 intent_not_modifiable`) and writes an `intent_audit` row\nalongside the update. Returns the refreshed intent so the frontend\ndoesn't need to re-fetch. Use this when the user has tweaked an\namount, recipient, or memo before clicking \"confirm\". Auth: bearer\nJWT; caller must hold `ManageWorkflows`.\n\n**Authorised read first.** The row is loaded through the\nsame `get_for_caller` read as `getIntent_Intents`: not the caller's to\nsee, or another workspace in the path ⇒ `404 intent_not_found` — a\ncaller can never reach an intent by id through a workspace they happen\nto own.\n\n**Pinned proposals are immutable.** A row filed by\n`createIntent_Intents` (`identity_hash` set) is `409 intent_pinned`\nfor EVERY session — the connector that filed it, the pinned actor, a\nroom admin: its `arguments` are its identity and the only value the\nconfirmation executes, so what the person sees in the reader is what\ndispatches. The store refuses the column on pinned rows as well, and\nthe dispatcher refuses a pinned row that carries `modified_arguments`\nhowever it got there. A change is a new proposal.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "intent_id", "in": "path", "required": true, "description": "Intent id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Patch shape. The handler currently honours `arguments`; other fields\nare reserved for future extension and ignored.\n", "properties": { "arguments": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] } } }, "examples": { "update-amount": { "summary": "Bump the proposed amount", "value": { "arguments": { "amount": 250, "token": "USDC", "recipient": "0xbob..." } } } } } } }, "responses": { "200": { "description": "Intent modified; full intent row returned.", "content": { "application/json": { "schema": { "type": "object", "required": [ "intent" ], "properties": { "intent": { "type": "object", "description": "Agent-proposed financial operation. Two families share the row: legacy\nin-app intents flow proposed → confirmed → executing → completed/failed;\nR2 pinned proposals (`identity_hash` set, filed by `createIntent_Intents`)\nflow proposed → approved (parked) | submitting (leased) → submitted\n→ completed/failed, and only `proposed` may become cancelled/expired.\nAppend-only `intent_audit` log for both. Reads (`getIntent_Intents`,\n`confirmIntent_Intents`) return the row plus the connector wire fields\n`intent_id`, `result`, `error`, `confirm_url`, `recovery`.\n", "required": [ "id", "thread_id", "intent_type", "status", "title", "proposed_by", "arguments", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "intent_id": { "type": "string", "format": "uuid", "description": "The same id under the connector wire contract's name (present on reads)." }, "group_id": { "type": [ "string", "null" ], "format": "uuid" }, "thread_id": { "type": "string" }, "deal_id": { "type": [ "string", "null" ], "format": "uuid" }, "intent_type": { "type": "string", "enum": [ "action", "pipeline", "composed" ] }, "status": { "type": "string", "enum": [ "proposed", "confirmed", "executing", "approved", "submitting", "submitted", "completed", "failed", "cancelled", "expired" ] }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "proposed_by": { "type": "string" }, "tool_name": { "type": [ "string", "null" ], "description": "For `action` intents — MCP tool name to invoke." }, "arguments": { "description": "Arbitrary JSON value." }, "pipeline_steps": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "operations": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "builder_metadata": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "validation_result": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "execution_result": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "workflow_id": { "type": [ "string", "null" ], "format": "uuid" }, "confirmed_by": { "type": [ "string", "null" ] }, "modified_arguments": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ], "description": "User edits to `arguments`. Effective args = arguments + modified." }, "schema_version": { "type": [ "string", "null" ] }, "pattern_id": { "type": [ "string", "null" ] }, "composite_action_id": { "type": [ "string", "null" ] }, "source_analysis_id": { "type": [ "string", "null" ], "format": "uuid" }, "audit_lineage": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "bindings_snapshot": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "chain_id": { "type": [ "string", "null" ], "description": "The chain the proposal executes on; dispatch routes by it, never by the confirmer's session." }, "wallet_id": { "type": [ "string", "null" ], "description": "The wallet the proposal was made for (the proposing session's default wallet on `chain_id`)." }, "actor_entity_id": { "type": [ "string", "null" ], "description": "The account holder the proposal is for — the only entity that may confirm it." }, "request_id": { "type": [ "string", "null" ], "description": "Caller-supplied disambiguator folded into the identity hash." }, "identity_hash": { "type": [ "string", "null" ], "description": "`sha256` of the canonical identity tuple; set ⇒ an R2 pinned proposal." }, "proposal_version": { "type": "integer" }, "proposer_kind": { "type": [ "string", "null" ], "description": "`connector` | `personal` — the session kind that filed it." }, "proposer_agent": { "type": [ "string", "null" ], "description": "`agent_id` / `mcp_agent_id` of the filing credential, when any." }, "approved_by": { "type": [ "string", "null" ] }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" }, "lease_owner": { "type": [ "string", "null" ] }, "lease_until": { "type": [ "string", "null" ], "format": "date-time" }, "submit_attempts": { "type": "integer" }, "recovery_attempts": { "type": "integer" }, "submission_key": { "type": [ "string", "null" ], "description": "The persisted MQ idempotency key (= the intent id)." }, "message_id": { "type": [ "string", "null" ], "description": "The canonical payments message id once submitted — poll it with the message-status endpoint or `wait_for_settlement`." }, "submitted_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_error": { "type": [ "string", "null" ], "description": "The last dispatch / recovery failure text." }, "approval_credential_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the sealed confirmer credential (never returned) stops being usable for an unattended re-drive." }, "result": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ], "description": "`execution_result` under the wire contract's name." }, "error": { "type": [ "string", "null" ], "description": "`last_error` under the wire contract's name." }, "confirm_url": { "type": [ "string", "null" ], "description": "The in-app confirmation page (`/private?reader=intent//`) while the intent is not terminal." }, "recovery": { "type": "string", "enum": [ "none", "in_progress" ], "description": "`in_progress` while a dispatch lease is held (a confirm or the recovery worker owns the row)." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing or unreadable credential — JSON `{ error, code: \"unauthorized\" }`.", "content": { "application/json": { "schema": { "type": "object", "description": "A structured refusal from an intent route. Clients branch on `code`\n(`intent_chain_mismatch`, `intent_expired`, `intent_actor_mismatch`,\n`intent_wallet_mismatch`, `intent_identity_mismatch`,\n`intent_terminal`, `intent_not_proposed`, `intent_pinned`,\n`intent_not_modifiable`, `intent_not_retryable`,\n`intent_dispatch_failed`, `intent_not_found`, `intent_internal`,\n`unauthorized`, `direct_user_session_required`,\n`session_kind_not_allowed`, `actor_mismatch`, `chain_mismatch`,\n`chain_not_allowed`, `chain_unmapped`, `wallet_mismatch`,\n`invalid_amount`, `tool_not_proposable`, …), never on the prose.\nEVERY refusal on the intent routes — 401, 403, 404, 409, 500 — is this\nJSON shape, never text/plain: payments' `intent_status` reader and\nthe app both key on the body. Some codes carry extra keys\n(`pinned_chain_id`, `session_chain_id`, `pinned_wallet_id`,\n`identity_hash`, `status`, `intent`, `fields`, `agent_bound`).\n", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "`workspace_forbidden` — below `ManageWorkflows` on a legacy row (body `{ error, code }`).", "content": { "application/json": { "schema": { "type": "object", "description": "A structured refusal from an intent route. Clients branch on `code`\n(`intent_chain_mismatch`, `intent_expired`, `intent_actor_mismatch`,\n`intent_wallet_mismatch`, `intent_identity_mismatch`,\n`intent_terminal`, `intent_not_proposed`, `intent_pinned`,\n`intent_not_modifiable`, `intent_not_retryable`,\n`intent_dispatch_failed`, `intent_not_found`, `intent_internal`,\n`unauthorized`, `direct_user_session_required`,\n`session_kind_not_allowed`, `actor_mismatch`, `chain_mismatch`,\n`chain_not_allowed`, `chain_unmapped`, `wallet_mismatch`,\n`invalid_amount`, `tool_not_proposable`, …), never on the prose.\nEVERY refusal on the intent routes — 401, 403, 404, 409, 500 — is this\nJSON shape, never text/plain: payments' `intent_status` reader and\nthe app both key on the body. Some codes carry extra keys\n(`pinned_chain_id`, `session_chain_id`, `pinned_wallet_id`,\n`identity_hash`, `status`, `intent`, `fields`, `agent_bound`).\n", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": true } } } }, "404": { "description": "`intent_not_found` — not the caller's to see, or another workspace in the path (existence undisclosed).", "content": { "application/json": { "schema": { "type": "object", "description": "A structured refusal from an intent route. Clients branch on `code`\n(`intent_chain_mismatch`, `intent_expired`, `intent_actor_mismatch`,\n`intent_wallet_mismatch`, `intent_identity_mismatch`,\n`intent_terminal`, `intent_not_proposed`, `intent_pinned`,\n`intent_not_modifiable`, `intent_not_retryable`,\n`intent_dispatch_failed`, `intent_not_found`, `intent_internal`,\n`unauthorized`, `direct_user_session_required`,\n`session_kind_not_allowed`, `actor_mismatch`, `chain_mismatch`,\n`chain_not_allowed`, `chain_unmapped`, `wallet_mismatch`,\n`invalid_amount`, `tool_not_proposable`, …), never on the prose.\nEVERY refusal on the intent routes — 401, 403, 404, 409, 500 — is this\nJSON shape, never text/plain: payments' `intent_status` reader and\nthe app both key on the body. Some codes carry extra keys\n(`pinned_chain_id`, `session_chain_id`, `pinned_wallet_id`,\n`identity_hash`, `status`, `intent`, `fields`, `agent_bound`).\n", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": true } } } }, "409": { "description": "`intent_pinned` (a pinned proposal is immutable; body carries `status`), `intent_not_modifiable` (a legacy row past `proposed`).", "content": { "application/json": { "schema": { "type": "object", "description": "A structured refusal from an intent route. Clients branch on `code`\n(`intent_chain_mismatch`, `intent_expired`, `intent_actor_mismatch`,\n`intent_wallet_mismatch`, `intent_identity_mismatch`,\n`intent_terminal`, `intent_not_proposed`, `intent_pinned`,\n`intent_not_modifiable`, `intent_not_retryable`,\n`intent_dispatch_failed`, `intent_not_found`, `intent_internal`,\n`unauthorized`, `direct_user_session_required`,\n`session_kind_not_allowed`, `actor_mismatch`, `chain_mismatch`,\n`chain_not_allowed`, `chain_unmapped`, `wallet_mismatch`,\n`invalid_amount`, `tool_not_proposable`, …), never on the prose.\nEVERY refusal on the intent routes — 401, 403, 404, 409, 500 — is this\nJSON shape, never text/plain: payments' `intent_status` reader and\nthe app both key on the body. Some codes carry extra keys\n(`pinned_chain_id`, `session_chain_id`, `pinned_wallet_id`,\n`identity_hash`, `status`, `intent`, `fields`, `agent_bound`).\n", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": true } } } }, "500": { "description": "`intent_internal` (JSON body).", "content": { "application/json": { "schema": { "type": "object", "description": "A structured refusal from an intent route. Clients branch on `code`\n(`intent_chain_mismatch`, `intent_expired`, `intent_actor_mismatch`,\n`intent_wallet_mismatch`, `intent_identity_mismatch`,\n`intent_terminal`, `intent_not_proposed`, `intent_pinned`,\n`intent_not_modifiable`, `intent_not_retryable`,\n`intent_dispatch_failed`, `intent_not_found`, `intent_internal`,\n`unauthorized`, `direct_user_session_required`,\n`session_kind_not_allowed`, `actor_mismatch`, `chain_mismatch`,\n`chain_not_allowed`, `chain_unmapped`, `wallet_mismatch`,\n`invalid_amount`, `tool_not_proposable`, …), never on the prose.\nEVERY refusal on the intent routes — 401, 403, 404, 409, 500 — is this\nJSON shape, never text/plain: payments' `intent_status` reader and\nthe app both key on the body. Some codes carry extra keys\n(`pinned_chain_id`, `session_chain_id`, `pinned_wallet_id`,\n`identity_hash`, `status`, `intent`, `fields`, `agent_bound`).\n", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": true } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_modifyIntent_Intents", "resource_uri": "yf://agents/intents", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PATCH -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"arguments\":{\"amount\":250}}' \\\n https://agents.yieldfabric.com/working-groups/{id}/intents/{intent_id}\n" } ], "x-related": [ { "operationId": "confirmIntent_Intents", "relation": "next-step" }, { "operationId": "cancelIntent_Intents", "relation": "sibling" }, { "guide": "intents-and-drafts", "relation": "concept" } ] } }, "/working-groups/{id}/intents/{intent_id}/audit": { "get": { "operationId": "getIntentAudit_Intents", "x-method": "GET", "x-path": "/working-groups/{id}/intents/{intent_id}/audit", "x-handler": "wg::get_intent_audit", "tags": [ "Intents" ], "summary": "Full lifecycle audit trail for an intent", "description": "Returns every recorded lifecycle transition for the intent — propose,\nmodify, confirm, execute, complete, fail, cancel, retry — oldest\nfirst. The same AUTHORISED read as `getIntent_Intents`:\nthe row must be visible to the caller AND live in the workspace named\nin the path, else `404 intent_not_found` — the trail (identity hash,\npins, proposer, edits) is never disclosed across workspaces by id.\nAuth: bearer JWT; caller must also hold `ViewWorkflows`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "intent_id", "in": "path", "required": true, "description": "Intent id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Audit timeline.", "content": { "application/json": { "schema": { "type": "object", "required": [ "audit" ], "properties": { "audit": { "type": "array", "items": { "type": "object", "description": "One row of the `intent_audit` append-only log.", "required": [ "id", "intent_id", "event_time", "event_type" ], "properties": { "id": { "type": "string", "format": "uuid" }, "intent_id": { "type": "string", "format": "uuid" }, "event_time": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "event_type": { "type": "string" }, "actor": { "type": [ "string", "null" ], "description": "Serialised from `actor_entity_id`." }, "before_state": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "after_state": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "reason": { "type": [ "string", "null" ] }, "schema_version": { "type": [ "string", "null" ] }, "audit_lineage": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ], "description": "Serialised from the `metadata` field — carries `StepLineage` JSON\nfor `proposed`/`confirmed` events, arbitrary diagnostic metadata\nfor others.\n" } } } } } } } } }, "401": { "description": "Missing or unreadable credential — JSON `{ error, code: \"unauthorized\" }`.", "content": { "application/json": { "schema": { "type": "object", "description": "A structured refusal from an intent route. Clients branch on `code`\n(`intent_chain_mismatch`, `intent_expired`, `intent_actor_mismatch`,\n`intent_wallet_mismatch`, `intent_identity_mismatch`,\n`intent_terminal`, `intent_not_proposed`, `intent_pinned`,\n`intent_not_modifiable`, `intent_not_retryable`,\n`intent_dispatch_failed`, `intent_not_found`, `intent_internal`,\n`unauthorized`, `direct_user_session_required`,\n`session_kind_not_allowed`, `actor_mismatch`, `chain_mismatch`,\n`chain_not_allowed`, `chain_unmapped`, `wallet_mismatch`,\n`invalid_amount`, `tool_not_proposable`, …), never on the prose.\nEVERY refusal on the intent routes — 401, 403, 404, 409, 500 — is this\nJSON shape, never text/plain: payments' `intent_status` reader and\nthe app both key on the body. Some codes carry extra keys\n(`pinned_chain_id`, `session_chain_id`, `pinned_wallet_id`,\n`identity_hash`, `status`, `intent`, `fields`, `agent_bound`).\n", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "`workspace_forbidden` (body `{ error, code }`).", "content": { "application/json": { "schema": { "type": "object", "description": "A structured refusal from an intent route. Clients branch on `code`\n(`intent_chain_mismatch`, `intent_expired`, `intent_actor_mismatch`,\n`intent_wallet_mismatch`, `intent_identity_mismatch`,\n`intent_terminal`, `intent_not_proposed`, `intent_pinned`,\n`intent_not_modifiable`, `intent_not_retryable`,\n`intent_dispatch_failed`, `intent_not_found`, `intent_internal`,\n`unauthorized`, `direct_user_session_required`,\n`session_kind_not_allowed`, `actor_mismatch`, `chain_mismatch`,\n`chain_not_allowed`, `chain_unmapped`, `wallet_mismatch`,\n`invalid_amount`, `tool_not_proposable`, …), never on the prose.\nEVERY refusal on the intent routes — 401, 403, 404, 409, 500 — is this\nJSON shape, never text/plain: payments' `intent_status` reader and\nthe app both key on the body. Some codes carry extra keys\n(`pinned_chain_id`, `session_chain_id`, `pinned_wallet_id`,\n`identity_hash`, `status`, `intent`, `fields`, `agent_bound`).\n", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": true } } } }, "404": { "description": "`intent_not_found` — not the caller's to see, or another workspace in the path (existence undisclosed).", "content": { "application/json": { "schema": { "type": "object", "description": "A structured refusal from an intent route. Clients branch on `code`\n(`intent_chain_mismatch`, `intent_expired`, `intent_actor_mismatch`,\n`intent_wallet_mismatch`, `intent_identity_mismatch`,\n`intent_terminal`, `intent_not_proposed`, `intent_pinned`,\n`intent_not_modifiable`, `intent_not_retryable`,\n`intent_dispatch_failed`, `intent_not_found`, `intent_internal`,\n`unauthorized`, `direct_user_session_required`,\n`session_kind_not_allowed`, `actor_mismatch`, `chain_mismatch`,\n`chain_not_allowed`, `chain_unmapped`, `wallet_mismatch`,\n`invalid_amount`, `tool_not_proposable`, …), never on the prose.\nEVERY refusal on the intent routes — 401, 403, 404, 409, 500 — is this\nJSON shape, never text/plain: payments' `intent_status` reader and\nthe app both key on the body. Some codes carry extra keys\n(`pinned_chain_id`, `session_chain_id`, `pinned_wallet_id`,\n`identity_hash`, `status`, `intent`, `fields`, `agent_bound`).\n", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": true } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getIntentAudit_Intents", "resource_uri": "yf://agents/intents", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/{id}/intents/{intent_id}/audit" } ], "x-related": [ { "operationId": "getIntent_Intents", "relation": "sibling" }, { "guide": "intents-and-drafts", "relation": "concept" } ] } }, "/working-groups/{id}/intents/{intent_id}/cancel": { "post": { "operationId": "cancelIntent_Intents", "x-method": "POST", "x-path": "/working-groups/{id}/intents/{intent_id}/cancel", "x-handler": "wg::cancel_intent", "tags": [ "Intents" ], "summary": "Cancel a proposed intent", "description": "Transitions a `proposed` intent to `cancelled` via the Box 3 state\nmachine (ONE conditional UPDATE, `WHERE status = 'proposed'`) and\nwrites an `intent_audit` row. Since R2 an intent that has been\napproved, is being dispatched, was submitted, or already reached a\nterminal status is left alone and answered `409 { error, code:\n\"intent_not_proposed\", status }` — an in-flight submission can never be\nmade to look cancelled while payments may still execute it. Auth:\nbearer JWT; the row must be readable by the caller (spec §5.9, else\n`404`); a pinned proposal is cancellable by its actor (any active\nmember role), a legacy row needs `ManageWorkflows`. Cancelling a\npinned proposal retracts its push item.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "intent_id", "in": "path", "required": true, "description": "Intent id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Intent cancelled.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "cancelled" ] } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "`intent_not_found` — not the caller's to see, or another workspace in the path (existence undisclosed; JSON body).", "content": { "application/json": { "schema": { "type": "object", "description": "A structured refusal from an intent route. Clients branch on `code`\n(`intent_chain_mismatch`, `intent_expired`, `intent_actor_mismatch`,\n`intent_wallet_mismatch`, `intent_identity_mismatch`,\n`intent_terminal`, `intent_not_proposed`, `intent_pinned`,\n`intent_not_modifiable`, `intent_not_retryable`,\n`intent_dispatch_failed`, `intent_not_found`, `intent_internal`,\n`unauthorized`, `direct_user_session_required`,\n`session_kind_not_allowed`, `actor_mismatch`, `chain_mismatch`,\n`chain_not_allowed`, `chain_unmapped`, `wallet_mismatch`,\n`invalid_amount`, `tool_not_proposable`, …), never on the prose.\nEVERY refusal on the intent routes — 401, 403, 404, 409, 500 — is this\nJSON shape, never text/plain: payments' `intent_status` reader and\nthe app both key on the body. Some codes carry extra keys\n(`pinned_chain_id`, `session_chain_id`, `pinned_wallet_id`,\n`identity_hash`, `status`, `intent`, `fields`, `agent_bound`).\n", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": true } } } }, "409": { "description": "`intent_not_proposed` — the row is no longer `proposed` (body carries its `status`).", "content": { "application/json": { "schema": { "type": "object", "description": "A structured refusal from an intent route. Clients branch on `code`\n(`intent_chain_mismatch`, `intent_expired`, `intent_actor_mismatch`,\n`intent_wallet_mismatch`, `intent_identity_mismatch`,\n`intent_terminal`, `intent_not_proposed`, `intent_pinned`,\n`intent_not_modifiable`, `intent_not_retryable`,\n`intent_dispatch_failed`, `intent_not_found`, `intent_internal`,\n`unauthorized`, `direct_user_session_required`,\n`session_kind_not_allowed`, `actor_mismatch`, `chain_mismatch`,\n`chain_not_allowed`, `chain_unmapped`, `wallet_mismatch`,\n`invalid_amount`, `tool_not_proposable`, …), never on the prose.\nEVERY refusal on the intent routes — 401, 403, 404, 409, 500 — is this\nJSON shape, never text/plain: payments' `intent_status` reader and\nthe app both key on the body. Some codes carry extra keys\n(`pinned_chain_id`, `session_chain_id`, `pinned_wallet_id`,\n`identity_hash`, `status`, `intent`, `fields`, `agent_bound`).\n", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": true } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_cancelIntent_Intents", "resource_uri": "yf://agents/intents", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/{id}/intents/{intent_id}/cancel" } ], "x-related": [ { "operationId": "confirmIntent_Intents", "relation": "alternative" }, { "operationId": "retryIntent_Intents", "relation": "sibling" }, { "guide": "intents-and-drafts", "relation": "concept" } ] } }, "/working-groups/{id}/intents/{intent_id}/confirm": { "post": { "operationId": "confirmIntent_Intents", "x-method": "POST", "x-path": "/working-groups/{id}/intents/{intent_id}/confirm", "x-handler": "wg::confirm_intent", "tags": [ "Intents" ], "summary": "Confirm an intent and dispatch its execution", "description": "Transitions a `proposed` (or `staged` after a retry) intent into\n`confirmed`, emits an `IntentConfirmed` event on the chat stream,\nthen synchronously dispatches the execution:\n\n - `action` intents → submit a single `signStep`+payment via the\n payments service and return the message id.\n - `pipeline` intents → save the embedded steps as a template,\n instantiate a workflow, start it, and return its workflow_id.\n - `composed` intents → invoke\n `composedFlow.executeComposedOperations` on payments-graphql\n and return the composed_id + message id.\n\nOn success the intent is moved to `executing` and an\n`IntentExecuting` event is broadcast; on dispatch failure the row\nis marked `failed` and an `IntentFailed` event is emitted. The body\nis empty. Auth: bearer JWT (REQUIRED); the above applies to LEGACY\nin-app intents, whose caller must hold `ManageWorkflows`.\n\n**Gate (every intent, R2 / spec §5.1):** a DIRECT personal session —\na connector, delegation, signer-bearing MCP or service credential is\n`403 { error, code: \"direct_user_session_required\" }` (the app sends\nthe confirm with its direct session). Same shape as auth's own\n`direct_user_session_required`: an agent-bound personal API-key\nsession (`agent_id`, the automation credential a program holds) is\nstamped `personal` but is NOT a direct session and is refused too\n(body `agent_bound: true`) — a connector may propose and an automation\nmay propose, only a person confirms.\n\n**Authorised read first.** The row is loaded through the\nsame `get_for_caller` read as `getIntent_Intents` BEFORE any other\ncheck: a caller who may not see the row — or who names another\nworkspace in the path — gets `404 intent_not_found`, existence\nundisclosed; the confirm discloses no more than the read does. A\nmember of the workspace who is not the pinned actor sees it and is\nrefused `403 intent_actor_mismatch`.\n\n**Pinned proposals (`identity_hash` set, filed by\n`createIntent_Intents`; spec §5.6).** The caller must be the pinned\nactor (`403 intent_actor_mismatch`) and an active member of the\nworkspace; when the body names the `identity_hash` the reader rendered\nand it differs from the row's, `409 intent_identity_mismatch` (body\ncarries the row's `identity_hash`; the app re-reads); the session's\nchain must equal the pinned chain (`409 intent_chain_mismatch`, body\ncarries `pinned_chain_id` / `session_chain_id` — the app switches chain\nand retries) and its default wallet the pinned wallet (`409\nintent_wallet_mismatch`); a proposal past `expires_at` is moved to\n`expired` and answered `409 intent_expired` (decided on the database\nclock — the same predicate the approval uses, so the boundary never\nanswers a bare `proposed`). Then ONE conditional UPDATE persists the\napproval (`approved_by`, `approved_at`) together with the first\ndispatch lease (`proposed → submitting`) and the sealed confirmer\ncredential, and the dispatch runs on the PINNED chain's payments host\nwith `idempotencyKey = ` and the row's ORIGINAL `arguments`\n(a pinned row is immutable; a `modified_arguments` value on one fails\nthe pin re-assertion and payments is never asked): the row lands\n`submitted` (`message_id`; `IntentExecuting`), or `completed` when\npayments reports the operation already satisfied, or `failed` (`409\nintent_dispatch_failed`, body carries `status` and `intent`;\n`IntentFailed`) on a DEFINITE refusal — a client-class outcome about\nthe proposal, never a 5xx — or is parked `approved` (`202`, `retry:\ntrue`) when no decision could be reached: a transport failure, a 5xx,\nor a `SUBMISSION_OUTCOME_UNKNOWN` answer (the id payments named rides\nalong as `result.submission_outcome_unknown_message_id`, never as\n`message_id`) — the recovery worker re-drives it with the SAME key and\nadopts the canonical message payments' idempotency then names.\n\n**Repeated confirmation** on a pinned row that is no longer\n`proposed`: a parked approval or a lapsed lease is resumed here (the\nsame dispatch path, a fresh credential, the unattended recovery budget\nreset — a row the worker had exhausted resumes exactly like any other);\na live lease answers the current row with `recovery: \"in_progress\"`;\na `submitted` row is NOT a bare read — the fresh session polls\npayments' `messageOutcome` and settles the row through the same fence\nthe pipeline consumer uses (a settled row answers `completed` /\n`failed` at once), and re-seals its bearer on the row so the worker's\nunattended poll gets another window; a terminal row is `409\nintent_terminal` (body carries `status` and `intent`). It never\ncreates a second submission.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "intent_id", "in": "path", "required": true, "description": "Intent id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "description": "Optional. `{}` (what the app sends) or `{ \"identity_hash\": \"\" }` — binds the confirmation to the exact\nproposal the person saw.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "identity_hash": { "type": "string", "description": "The `identity_hash` the confirmer's reader rendered (64 hex chars); refused with `409 intent_identity_mismatch` when it is not the row's." } } } } } }, "responses": { "200": { "description": "Confirmation accepted; execution dispatched (`submitted`), or the current state of a row already past `proposed`. Body is the refreshed intent.", "content": { "application/json": { "schema": { "type": "object", "required": [ "intent" ], "properties": { "intent": { "type": "object", "description": "Agent-proposed financial operation. Two families share the row: legacy\nin-app intents flow proposed → confirmed → executing → completed/failed;\nR2 pinned proposals (`identity_hash` set, filed by `createIntent_Intents`)\nflow proposed → approved (parked) | submitting (leased) → submitted\n→ completed/failed, and only `proposed` may become cancelled/expired.\nAppend-only `intent_audit` log for both. Reads (`getIntent_Intents`,\n`confirmIntent_Intents`) return the row plus the connector wire fields\n`intent_id`, `result`, `error`, `confirm_url`, `recovery`.\n", "required": [ "id", "thread_id", "intent_type", "status", "title", "proposed_by", "arguments", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "intent_id": { "type": "string", "format": "uuid", "description": "The same id under the connector wire contract's name (present on reads)." }, "group_id": { "type": [ "string", "null" ], "format": "uuid" }, "thread_id": { "type": "string" }, "deal_id": { "type": [ "string", "null" ], "format": "uuid" }, "intent_type": { "type": "string", "enum": [ "action", "pipeline", "composed" ] }, "status": { "type": "string", "enum": [ "proposed", "confirmed", "executing", "approved", "submitting", "submitted", "completed", "failed", "cancelled", "expired" ] }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "proposed_by": { "type": "string" }, "tool_name": { "type": [ "string", "null" ], "description": "For `action` intents — MCP tool name to invoke." }, "arguments": { "description": "Arbitrary JSON value." }, "pipeline_steps": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "operations": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "builder_metadata": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "validation_result": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "execution_result": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "workflow_id": { "type": [ "string", "null" ], "format": "uuid" }, "confirmed_by": { "type": [ "string", "null" ] }, "modified_arguments": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ], "description": "User edits to `arguments`. Effective args = arguments + modified." }, "schema_version": { "type": [ "string", "null" ] }, "pattern_id": { "type": [ "string", "null" ] }, "composite_action_id": { "type": [ "string", "null" ] }, "source_analysis_id": { "type": [ "string", "null" ], "format": "uuid" }, "audit_lineage": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "bindings_snapshot": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "chain_id": { "type": [ "string", "null" ], "description": "The chain the proposal executes on; dispatch routes by it, never by the confirmer's session." }, "wallet_id": { "type": [ "string", "null" ], "description": "The wallet the proposal was made for (the proposing session's default wallet on `chain_id`)." }, "actor_entity_id": { "type": [ "string", "null" ], "description": "The account holder the proposal is for — the only entity that may confirm it." }, "request_id": { "type": [ "string", "null" ], "description": "Caller-supplied disambiguator folded into the identity hash." }, "identity_hash": { "type": [ "string", "null" ], "description": "`sha256` of the canonical identity tuple; set ⇒ an R2 pinned proposal." }, "proposal_version": { "type": "integer" }, "proposer_kind": { "type": [ "string", "null" ], "description": "`connector` | `personal` — the session kind that filed it." }, "proposer_agent": { "type": [ "string", "null" ], "description": "`agent_id` / `mcp_agent_id` of the filing credential, when any." }, "approved_by": { "type": [ "string", "null" ] }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" }, "lease_owner": { "type": [ "string", "null" ] }, "lease_until": { "type": [ "string", "null" ], "format": "date-time" }, "submit_attempts": { "type": "integer" }, "recovery_attempts": { "type": "integer" }, "submission_key": { "type": [ "string", "null" ], "description": "The persisted MQ idempotency key (= the intent id)." }, "message_id": { "type": [ "string", "null" ], "description": "The canonical payments message id once submitted — poll it with the message-status endpoint or `wait_for_settlement`." }, "submitted_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_error": { "type": [ "string", "null" ], "description": "The last dispatch / recovery failure text." }, "approval_credential_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the sealed confirmer credential (never returned) stops being usable for an unattended re-drive." }, "result": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ], "description": "`execution_result` under the wire contract's name." }, "error": { "type": [ "string", "null" ], "description": "`last_error` under the wire contract's name." }, "confirm_url": { "type": [ "string", "null" ], "description": "The in-app confirmation page (`/private?reader=intent//`) while the intent is not terminal." }, "recovery": { "type": "string", "enum": [ "none", "in_progress" ], "description": "`in_progress` while a dispatch lease is held (a confirm or the recovery worker owns the row)." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } } } }, "202": { "description": "Approved and leased, but the dispatch reached no decision (transport failure, payments 5xx); parked for the recovery worker. Body carries the intent, `retry: true` and the error.", "content": { "application/json": { "schema": { "type": "object", "required": [ "intent" ], "properties": { "intent": { "type": "object", "description": "Agent-proposed financial operation. Two families share the row: legacy\nin-app intents flow proposed → confirmed → executing → completed/failed;\nR2 pinned proposals (`identity_hash` set, filed by `createIntent_Intents`)\nflow proposed → approved (parked) | submitting (leased) → submitted\n→ completed/failed, and only `proposed` may become cancelled/expired.\nAppend-only `intent_audit` log for both. Reads (`getIntent_Intents`,\n`confirmIntent_Intents`) return the row plus the connector wire fields\n`intent_id`, `result`, `error`, `confirm_url`, `recovery`.\n", "required": [ "id", "thread_id", "intent_type", "status", "title", "proposed_by", "arguments", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "intent_id": { "type": "string", "format": "uuid", "description": "The same id under the connector wire contract's name (present on reads)." }, "group_id": { "type": [ "string", "null" ], "format": "uuid" }, "thread_id": { "type": "string" }, "deal_id": { "type": [ "string", "null" ], "format": "uuid" }, "intent_type": { "type": "string", "enum": [ "action", "pipeline", "composed" ] }, "status": { "type": "string", "enum": [ "proposed", "confirmed", "executing", "approved", "submitting", "submitted", "completed", "failed", "cancelled", "expired" ] }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "proposed_by": { "type": "string" }, "tool_name": { "type": [ "string", "null" ], "description": "For `action` intents — MCP tool name to invoke." }, "arguments": { "description": "Arbitrary JSON value." }, "pipeline_steps": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "operations": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "builder_metadata": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "validation_result": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "execution_result": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "workflow_id": { "type": [ "string", "null" ], "format": "uuid" }, "confirmed_by": { "type": [ "string", "null" ] }, "modified_arguments": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ], "description": "User edits to `arguments`. Effective args = arguments + modified." }, "schema_version": { "type": [ "string", "null" ] }, "pattern_id": { "type": [ "string", "null" ] }, "composite_action_id": { "type": [ "string", "null" ] }, "source_analysis_id": { "type": [ "string", "null" ], "format": "uuid" }, "audit_lineage": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "bindings_snapshot": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "chain_id": { "type": [ "string", "null" ], "description": "The chain the proposal executes on; dispatch routes by it, never by the confirmer's session." }, "wallet_id": { "type": [ "string", "null" ], "description": "The wallet the proposal was made for (the proposing session's default wallet on `chain_id`)." }, "actor_entity_id": { "type": [ "string", "null" ], "description": "The account holder the proposal is for — the only entity that may confirm it." }, "request_id": { "type": [ "string", "null" ], "description": "Caller-supplied disambiguator folded into the identity hash." }, "identity_hash": { "type": [ "string", "null" ], "description": "`sha256` of the canonical identity tuple; set ⇒ an R2 pinned proposal." }, "proposal_version": { "type": "integer" }, "proposer_kind": { "type": [ "string", "null" ], "description": "`connector` | `personal` — the session kind that filed it." }, "proposer_agent": { "type": [ "string", "null" ], "description": "`agent_id` / `mcp_agent_id` of the filing credential, when any." }, "approved_by": { "type": [ "string", "null" ] }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" }, "lease_owner": { "type": [ "string", "null" ] }, "lease_until": { "type": [ "string", "null" ], "format": "date-time" }, "submit_attempts": { "type": "integer" }, "recovery_attempts": { "type": "integer" }, "submission_key": { "type": [ "string", "null" ], "description": "The persisted MQ idempotency key (= the intent id)." }, "message_id": { "type": [ "string", "null" ], "description": "The canonical payments message id once submitted — poll it with the message-status endpoint or `wait_for_settlement`." }, "submitted_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_error": { "type": [ "string", "null" ], "description": "The last dispatch / recovery failure text." }, "approval_credential_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the sealed confirmer credential (never returned) stops being usable for an unattended re-drive." }, "result": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ], "description": "`execution_result` under the wire contract's name." }, "error": { "type": [ "string", "null" ], "description": "`last_error` under the wire contract's name." }, "confirm_url": { "type": [ "string", "null" ], "description": "The in-app confirmation page (`/private?reader=intent//`) while the intent is not terminal." }, "recovery": { "type": "string", "enum": [ "none", "in_progress" ], "description": "`in_progress` while a dispatch lease is held (a confirm or the recovery worker owns the row)." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } } } }, "401": { "description": "Missing or unreadable credential — JSON `{ error, code: \"unauthorized\" }`.", "content": { "application/json": { "schema": { "type": "object", "description": "A structured refusal from an intent route. Clients branch on `code`\n(`intent_chain_mismatch`, `intent_expired`, `intent_actor_mismatch`,\n`intent_wallet_mismatch`, `intent_identity_mismatch`,\n`intent_terminal`, `intent_not_proposed`, `intent_pinned`,\n`intent_not_modifiable`, `intent_not_retryable`,\n`intent_dispatch_failed`, `intent_not_found`, `intent_internal`,\n`unauthorized`, `direct_user_session_required`,\n`session_kind_not_allowed`, `actor_mismatch`, `chain_mismatch`,\n`chain_not_allowed`, `chain_unmapped`, `wallet_mismatch`,\n`invalid_amount`, `tool_not_proposable`, …), never on the prose.\nEVERY refusal on the intent routes — 401, 403, 404, 409, 500 — is this\nJSON shape, never text/plain: payments' `intent_status` reader and\nthe app both key on the body. Some codes carry extra keys\n(`pinned_chain_id`, `session_chain_id`, `pinned_wallet_id`,\n`identity_hash`, `status`, `intent`, `fields`, `agent_bound`).\n", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "`direct_user_session_required` (body also `session_kind`, `agent_bound`), `intent_actor_mismatch`, `workspace_forbidden` (body `{ error, code }`); legacy rows also refuse below `ManageWorkflows`.", "content": { "application/json": { "schema": { "type": "object", "description": "A structured refusal from an intent route. Clients branch on `code`\n(`intent_chain_mismatch`, `intent_expired`, `intent_actor_mismatch`,\n`intent_wallet_mismatch`, `intent_identity_mismatch`,\n`intent_terminal`, `intent_not_proposed`, `intent_pinned`,\n`intent_not_modifiable`, `intent_not_retryable`,\n`intent_dispatch_failed`, `intent_not_found`, `intent_internal`,\n`unauthorized`, `direct_user_session_required`,\n`session_kind_not_allowed`, `actor_mismatch`, `chain_mismatch`,\n`chain_not_allowed`, `chain_unmapped`, `wallet_mismatch`,\n`invalid_amount`, `tool_not_proposable`, …), never on the prose.\nEVERY refusal on the intent routes — 401, 403, 404, 409, 500 — is this\nJSON shape, never text/plain: payments' `intent_status` reader and\nthe app both key on the body. Some codes carry extra keys\n(`pinned_chain_id`, `session_chain_id`, `pinned_wallet_id`,\n`identity_hash`, `status`, `intent`, `fields`, `agent_bound`).\n", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": true } } } }, "404": { "description": "`intent_not_found` — not the caller's to see, or another workspace in the path (existence undisclosed; JSON body).", "content": { "application/json": { "schema": { "type": "object", "description": "A structured refusal from an intent route. Clients branch on `code`\n(`intent_chain_mismatch`, `intent_expired`, `intent_actor_mismatch`,\n`intent_wallet_mismatch`, `intent_identity_mismatch`,\n`intent_terminal`, `intent_not_proposed`, `intent_pinned`,\n`intent_not_modifiable`, `intent_not_retryable`,\n`intent_dispatch_failed`, `intent_not_found`, `intent_internal`,\n`unauthorized`, `direct_user_session_required`,\n`session_kind_not_allowed`, `actor_mismatch`, `chain_mismatch`,\n`chain_not_allowed`, `chain_unmapped`, `wallet_mismatch`,\n`invalid_amount`, `tool_not_proposable`, …), never on the prose.\nEVERY refusal on the intent routes — 401, 403, 404, 409, 500 — is this\nJSON shape, never text/plain: payments' `intent_status` reader and\nthe app both key on the body. Some codes carry extra keys\n(`pinned_chain_id`, `session_chain_id`, `pinned_wallet_id`,\n`identity_hash`, `status`, `intent`, `fields`, `agent_bound`).\n", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": true } } } }, "409": { "description": "`intent_identity_mismatch`, `intent_chain_mismatch`, `intent_wallet_mismatch`, `intent_expired`, `intent_dispatch_failed` (a definite payments refusal; body carries `status: failed` and `intent`), `intent_terminal` (body `{ error, code, … }`).", "content": { "application/json": { "schema": { "type": "object", "description": "A structured refusal from an intent route. Clients branch on `code`\n(`intent_chain_mismatch`, `intent_expired`, `intent_actor_mismatch`,\n`intent_wallet_mismatch`, `intent_identity_mismatch`,\n`intent_terminal`, `intent_not_proposed`, `intent_pinned`,\n`intent_not_modifiable`, `intent_not_retryable`,\n`intent_dispatch_failed`, `intent_not_found`, `intent_internal`,\n`unauthorized`, `direct_user_session_required`,\n`session_kind_not_allowed`, `actor_mismatch`, `chain_mismatch`,\n`chain_not_allowed`, `chain_unmapped`, `wallet_mismatch`,\n`invalid_amount`, `tool_not_proposable`, …), never on the prose.\nEVERY refusal on the intent routes — 401, 403, 404, 409, 500 — is this\nJSON shape, never text/plain: payments' `intent_status` reader and\nthe app both key on the body. Some codes carry extra keys\n(`pinned_chain_id`, `session_chain_id`, `pinned_wallet_id`,\n`identity_hash`, `status`, `intent`, `fields`, `agent_bound`).\n", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": true } } } }, "500": { "description": "`intent_internal` — a store failure (JSON body). Never a payments refusal.", "content": { "application/json": { "schema": { "type": "object", "description": "A structured refusal from an intent route. Clients branch on `code`\n(`intent_chain_mismatch`, `intent_expired`, `intent_actor_mismatch`,\n`intent_wallet_mismatch`, `intent_identity_mismatch`,\n`intent_terminal`, `intent_not_proposed`, `intent_pinned`,\n`intent_not_modifiable`, `intent_not_retryable`,\n`intent_dispatch_failed`, `intent_not_found`, `intent_internal`,\n`unauthorized`, `direct_user_session_required`,\n`session_kind_not_allowed`, `actor_mismatch`, `chain_mismatch`,\n`chain_not_allowed`, `chain_unmapped`, `wallet_mismatch`,\n`invalid_amount`, `tool_not_proposable`, …), never on the prose.\nEVERY refusal on the intent routes — 401, 403, 404, 409, 500 — is this\nJSON shape, never text/plain: payments' `intent_status` reader and\nthe app both key on the body. Some codes carry extra keys\n(`pinned_chain_id`, `session_chain_id`, `pinned_wallet_id`,\n`identity_hash`, `status`, `intent`, `fields`, `agent_bound`).\n", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": true } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_confirmIntent_Intents", "resource_uri": "yf://agents/intents", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/{id}/intents/{intent_id}/confirm" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx\nr = httpx.post(\n f\"https://agents.yieldfabric.com/working-groups/{gid}/intents/{intent_id}/confirm\",\n headers={\"Authorization\": f\"Bearer {jwt}\"},\n timeout=60.0,\n)\nr.raise_for_status()\nintent = r.json()[\"intent\"]\n" } ], "x-related": [ { "operationId": "modifyIntent_Intents", "relation": "precondition" }, { "operationId": "cancelIntent_Intents", "relation": "alternative" }, { "operationId": "getIntentAudit_Intents", "relation": "read-after-write" }, { "guide": "intents-and-drafts", "relation": "concept" } ] } }, "/working-groups/{id}/intents/{intent_id}/retry": { "post": { "operationId": "retryIntent_Intents", "x-method": "POST", "x-path": "/working-groups/{id}/intents/{intent_id}/retry", "x-handler": "wg::retry_intent", "tags": [ "Intents" ], "summary": "Retry a failed intent (Failed → Staged)", "description": "Transitions a `failed` intent back to `staged` via the Box 3 state\nmachine, preserving the original lineage in `intent_audit`. The\ncaller (UI or agent) is expected to immediately re-issue\n`confirmIntent_Intents` to trigger fresh execution. Auth: bearer\nJWT; caller must hold `ManageWorkflows`.\n\nThe row is loaded through the §5.9 authorised read first (`404\nintent_not_found` when it is not the caller's to see or lives in\nanother workspace). A pinned proposal is never retried in place —\n`400 intent_not_retryable` (the connector re-proposes; putting it back\nto `proposed` would re-enter the open-identity index).\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "intent_id", "in": "path", "required": true, "description": "Intent id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Intent moved back to `staged`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "staged" ] } } } } } }, "400": { "description": "`intent_not_retryable` — not `failed`, or a pinned proposal (body `{ error, code }`).", "content": { "application/json": { "schema": { "type": "object", "description": "A structured refusal from an intent route. Clients branch on `code`\n(`intent_chain_mismatch`, `intent_expired`, `intent_actor_mismatch`,\n`intent_wallet_mismatch`, `intent_identity_mismatch`,\n`intent_terminal`, `intent_not_proposed`, `intent_pinned`,\n`intent_not_modifiable`, `intent_not_retryable`,\n`intent_dispatch_failed`, `intent_not_found`, `intent_internal`,\n`unauthorized`, `direct_user_session_required`,\n`session_kind_not_allowed`, `actor_mismatch`, `chain_mismatch`,\n`chain_not_allowed`, `chain_unmapped`, `wallet_mismatch`,\n`invalid_amount`, `tool_not_proposable`, …), never on the prose.\nEVERY refusal on the intent routes — 401, 403, 404, 409, 500 — is this\nJSON shape, never text/plain: payments' `intent_status` reader and\nthe app both key on the body. Some codes carry extra keys\n(`pinned_chain_id`, `session_chain_id`, `pinned_wallet_id`,\n`identity_hash`, `status`, `intent`, `fields`, `agent_bound`).\n", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": true } } } }, "401": { "description": "Missing or unreadable credential — JSON `{ error, code: \"unauthorized\" }`.", "content": { "application/json": { "schema": { "type": "object", "description": "A structured refusal from an intent route. Clients branch on `code`\n(`intent_chain_mismatch`, `intent_expired`, `intent_actor_mismatch`,\n`intent_wallet_mismatch`, `intent_identity_mismatch`,\n`intent_terminal`, `intent_not_proposed`, `intent_pinned`,\n`intent_not_modifiable`, `intent_not_retryable`,\n`intent_dispatch_failed`, `intent_not_found`, `intent_internal`,\n`unauthorized`, `direct_user_session_required`,\n`session_kind_not_allowed`, `actor_mismatch`, `chain_mismatch`,\n`chain_not_allowed`, `chain_unmapped`, `wallet_mismatch`,\n`invalid_amount`, `tool_not_proposable`, …), never on the prose.\nEVERY refusal on the intent routes — 401, 403, 404, 409, 500 — is this\nJSON shape, never text/plain: payments' `intent_status` reader and\nthe app both key on the body. Some codes carry extra keys\n(`pinned_chain_id`, `session_chain_id`, `pinned_wallet_id`,\n`identity_hash`, `status`, `intent`, `fields`, `agent_bound`).\n", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "`workspace_forbidden` (body `{ error, code }`).", "content": { "application/json": { "schema": { "type": "object", "description": "A structured refusal from an intent route. Clients branch on `code`\n(`intent_chain_mismatch`, `intent_expired`, `intent_actor_mismatch`,\n`intent_wallet_mismatch`, `intent_identity_mismatch`,\n`intent_terminal`, `intent_not_proposed`, `intent_pinned`,\n`intent_not_modifiable`, `intent_not_retryable`,\n`intent_dispatch_failed`, `intent_not_found`, `intent_internal`,\n`unauthorized`, `direct_user_session_required`,\n`session_kind_not_allowed`, `actor_mismatch`, `chain_mismatch`,\n`chain_not_allowed`, `chain_unmapped`, `wallet_mismatch`,\n`invalid_amount`, `tool_not_proposable`, …), never on the prose.\nEVERY refusal on the intent routes — 401, 403, 404, 409, 500 — is this\nJSON shape, never text/plain: payments' `intent_status` reader and\nthe app both key on the body. Some codes carry extra keys\n(`pinned_chain_id`, `session_chain_id`, `pinned_wallet_id`,\n`identity_hash`, `status`, `intent`, `fields`, `agent_bound`).\n", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": true } } } }, "404": { "description": "`intent_not_found` — not the caller's to see, or another workspace in the path (existence undisclosed).", "content": { "application/json": { "schema": { "type": "object", "description": "A structured refusal from an intent route. Clients branch on `code`\n(`intent_chain_mismatch`, `intent_expired`, `intent_actor_mismatch`,\n`intent_wallet_mismatch`, `intent_identity_mismatch`,\n`intent_terminal`, `intent_not_proposed`, `intent_pinned`,\n`intent_not_modifiable`, `intent_not_retryable`,\n`intent_dispatch_failed`, `intent_not_found`, `intent_internal`,\n`unauthorized`, `direct_user_session_required`,\n`session_kind_not_allowed`, `actor_mismatch`, `chain_mismatch`,\n`chain_not_allowed`, `chain_unmapped`, `wallet_mismatch`,\n`invalid_amount`, `tool_not_proposable`, …), never on the prose.\nEVERY refusal on the intent routes — 401, 403, 404, 409, 500 — is this\nJSON shape, never text/plain: payments' `intent_status` reader and\nthe app both key on the body. Some codes carry extra keys\n(`pinned_chain_id`, `session_chain_id`, `pinned_wallet_id`,\n`identity_hash`, `status`, `intent`, `fields`, `agent_bound`).\n", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": true } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_retryIntent_Intents", "resource_uri": "yf://agents/intents", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/{id}/intents/{intent_id}/retry" } ], "x-related": [ { "operationId": "confirmIntent_Intents", "relation": "next-step" }, { "operationId": "getIntentAudit_Intents", "relation": "read-after-write" }, { "guide": "intents-and-drafts", "relation": "concept" } ] } }, "/working-groups/{id}/members": { "post": { "operationId": "addMember_Members", "x-method": "POST", "x-path": "/working-groups/{id}/members", "x-handler": "wg::add_member", "tags": [ "Members" ], "summary": "Invite an entity (human or agent) into the group", "description": "Adds a human or agent as a member of the working group. Requires the\ncaller to hold `ManageMembers`. The `member_type` field selects which\nentity kind is being added (`human` or `agent`); for agents an inline\n`agent_definition` may be carried so the agent is provisioned on first\nadd. `wallet_address` is optional but recommended for humans — without\nit, on-chain workflow steps assigned to this member must resolve a\nwallet via the auth-identity API. Personal notebook workspaces reject\nadditional members (returns 403). Idempotent at the\n`(group_id, entity_id)` unique constraint — re-posting upserts the row.\nAuth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "entity_id", "member_type", "display_name" ], "properties": { "entity_id": { "type": "string" }, "member_type": { "type": "string", "enum": [ "human", "agent" ] }, "role": { "type": "string", "default": "member", "enum": [ "owner", "admin", "member", "observer" ] }, "display_name": { "type": "string" }, "agent_definition": { "oneOf": [ { "type": "null" }, { "type": "object", "description": "Agent persona attached to an `agent`-type member.", "required": [ "id", "role" ], "properties": { "id": { "type": "string", "description": "Unique agent identifier." }, "role": { "type": "string", "description": "Agent role/purpose." }, "personality": { "type": [ "string", "null" ] }, "expertise": { "type": "array", "items": { "type": "string" } }, "weight": { "type": "number", "default": 1, "description": "Agent weight in consensus (0.0-1.0)." }, "focus": { "type": [ "string", "null" ] }, "anti_focus": { "type": [ "string", "null" ] }, "reasoning_style": { "type": [ "string", "null" ] }, "topics": { "type": "array", "items": { "type": "string" } } } } ] }, "wallet_address": { "type": [ "string", "null" ] } } }, "examples": { "human": { "summary": "Add a human member", "value": { "entity_id": "usr_2bk9...", "member_type": "human", "role": "member", "display_name": "Alice Trader", "wallet_address": "0xabc..." } }, "agent": { "summary": "Add an agent with a definition", "value": { "entity_id": "agent:risk-reviewer", "member_type": "agent", "role": "member", "display_name": "Risk Reviewer", "agent_definition": { "system_prompt": "You review proposed trades.", "capabilities": [ "risk" ] } } } } } } }, "responses": { "201": { "description": "Member added (or upserted). Body is the `WorkingGroupMember` row.", "content": { "application/json": { "schema": { "type": "object", "description": "A row from `working_group_members`.", "required": [ "id", "group_id", "entity_id", "member_type", "role", "display_name", "status", "joined_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "group_id": { "type": "string", "format": "uuid" }, "entity_id": { "type": "string", "description": "Identity URI (e.g. `user:alice@yieldfabric.com`, `agent:credit_risk_analyst`).\n" }, "member_type": { "type": "string", "description": "`human` or `agent`.", "enum": [ "human", "agent" ] }, "role": { "type": "string", "enum": [ "owner", "admin", "member", "observer" ] }, "display_name": { "type": "string" }, "agent_definition": { "oneOf": [ { "type": "null" }, { "type": "object", "description": "Agent persona attached to an `agent`-type member.", "required": [ "id", "role" ], "properties": { "id": { "type": "string", "description": "Unique agent identifier." }, "role": { "type": "string", "description": "Agent role/purpose." }, "personality": { "type": [ "string", "null" ] }, "expertise": { "type": "array", "items": { "type": "string" } }, "weight": { "type": "number", "default": 1, "description": "Agent weight in consensus (0.0-1.0)." }, "focus": { "type": [ "string", "null" ] }, "anti_focus": { "type": [ "string", "null" ] }, "reasoning_style": { "type": [ "string", "null" ] }, "topics": { "type": "array", "items": { "type": "string" } } } } ] }, "wallet_address": { "type": [ "string", "null" ], "description": "On-chain address (when a wallet was linked at join time)." }, "status": { "type": "string", "enum": [ "active", "removed" ] }, "joined_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "invited_by": { "type": [ "string", "null" ], "description": "entity_id of the inviter." } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_addMember_Members", "resource_uri": "yf://agents/members", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"entity_id\":\"usr_x\",\"member_type\":\"human\",\"display_name\":\"Bob\"}' \\\n https://agents.yieldfabric.com/working-groups/{id}/members\n" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx\nr = httpx.post(\n f\"https://agents.yieldfabric.com/working-groups/{gid}/members\",\n headers={\"Authorization\": f\"Bearer {jwt}\"},\n json={\n \"entity_id\": \"usr_x\",\n \"member_type\": \"human\",\n \"role\": \"member\",\n \"display_name\": \"Bob\",\n },\n)\nr.raise_for_status()\n" } ], "x-related": [ { "operationId": "listMembers_Members", "relation": "sibling" }, { "operationId": "updateMember_Members", "relation": "sibling" }, { "operationId": "removeMember_Members", "relation": "sibling" }, { "guide": "working-groups", "relation": "concept" } ] }, "get": { "operationId": "listMembers_Members", "x-method": "GET", "x-path": "/working-groups/{id}/members", "x-handler": "wg::list_members", "tags": [ "Members" ], "summary": "List active members of the working group", "description": "Returns every active member (humans and agents) of the working group:\n`entity_id`, `member_type`, `role`, `display_name`, `wallet_address`,\ninvited-by, and timestamps. Inactive / removed members are filtered\nout. Auth: bearer JWT; caller must hold `ViewMembers`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "members" ], "properties": { "members": { "type": "array", "items": { "type": "object", "description": "A row from `working_group_members`.", "required": [ "id", "group_id", "entity_id", "member_type", "role", "display_name", "status", "joined_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "group_id": { "type": "string", "format": "uuid" }, "entity_id": { "type": "string", "description": "Identity URI (e.g. `user:alice@yieldfabric.com`, `agent:credit_risk_analyst`).\n" }, "member_type": { "type": "string", "description": "`human` or `agent`.", "enum": [ "human", "agent" ] }, "role": { "type": "string", "enum": [ "owner", "admin", "member", "observer" ] }, "display_name": { "type": "string" }, "agent_definition": { "oneOf": [ { "type": "null" }, { "type": "object", "description": "Agent persona attached to an `agent`-type member.", "required": [ "id", "role" ], "properties": { "id": { "type": "string", "description": "Unique agent identifier." }, "role": { "type": "string", "description": "Agent role/purpose." }, "personality": { "type": [ "string", "null" ] }, "expertise": { "type": "array", "items": { "type": "string" } }, "weight": { "type": "number", "default": 1, "description": "Agent weight in consensus (0.0-1.0)." }, "focus": { "type": [ "string", "null" ] }, "anti_focus": { "type": [ "string", "null" ] }, "reasoning_style": { "type": [ "string", "null" ] }, "topics": { "type": "array", "items": { "type": "string" } } } } ] }, "wallet_address": { "type": [ "string", "null" ], "description": "On-chain address (when a wallet was linked at join time)." }, "status": { "type": "string", "enum": [ "active", "removed" ] }, "joined_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "invited_by": { "type": [ "string", "null" ], "description": "entity_id of the inviter." } } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listMembers_Members", "resource_uri": "yf://agents/members", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/{id}/members" } ], "x-related": [ { "operationId": "addMember_Members", "relation": "sibling" }, { "operationId": "getGroupPresence_Presence", "relation": "sibling" }, { "guide": "working-groups", "relation": "concept" } ] } }, "/working-groups/{id}/members/{mid}": { "patch": { "operationId": "updateMember_Members", "x-method": "PATCH", "x-path": "/working-groups/{id}/members/{mid}", "x-handler": "wg::update_member", "tags": [ "Members" ], "summary": "Change a member's role", "description": "Updates a member's role (`owner`, `admin`, `member`, etc.). Wrappers\naround `MembershipStore::update_role`. Writes a `member_role_updated`\nrow to `working_group_audit_events`. Auth: bearer JWT; caller must\nhold `ManageMembers`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "mid", "in": "path", "required": true, "description": "Member id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "owner", "admin", "member", "observer" ] } } }, "examples": { "promote": { "summary": "Promote to admin", "value": { "role": "admin" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "updated" ], "properties": { "updated": { "type": "boolean" } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_updateMember_Members", "resource_uri": "yf://agents/members", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PATCH -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"role\":\"admin\"}' \\\n https://agents.yieldfabric.com/working-groups/{id}/members/{mid}\n" } ], "x-related": [ { "operationId": "addMember_Members", "relation": "sibling" }, { "operationId": "removeMember_Members", "relation": "sibling" }, { "guide": "working-groups", "relation": "concept" } ] }, "delete": { "operationId": "removeMember_Members", "x-method": "DELETE", "x-path": "/working-groups/{id}/members/{mid}", "x-handler": "wg::remove_member", "tags": [ "Members" ], "summary": "Remove a member from the group", "description": "Soft-deletes the membership row. Refuses with `409 Conflict` when the\ntarget member is the assignee of any `human_task` or `approval_gate`\nstep in a pending / running workflow — the caller must reassign those\nsteps first. Writes a `member_removed` row to\n`working_group_audit_events`. Auth: bearer JWT; caller must hold\n`ManageMembers`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "mid", "in": "path", "required": true, "description": "Member id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Member removed.", "content": { "application/json": { "schema": { "type": "object", "description": "204 No Content on success.", "properties": {} } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "409": { "description": "Conflicting state (e.g. step already completed, intent already cancelled, duplicate idempotency key with different body).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_removeMember_Members", "resource_uri": "yf://agents/members", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X DELETE -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/{id}/members/{mid}" } ], "x-related": [ { "operationId": "reassignStep_Workflows", "relation": "prerequisite" }, { "operationId": "updateMember_Members", "relation": "sibling" }, { "guide": "working-groups", "relation": "concept" } ] } }, "/working-groups/{id}/merge-kgs": { "post": { "operationId": "mergeWorkingGroupKgs_WorkingGroups", "x-method": "POST", "x-path": "/working-groups/{id}/merge-kgs", "x-handler": "handlers::pipelines::merge_working_group_kgs", "tags": [ "Working Groups" ], "summary": "Merge KGs in a working group into a single canonical KG", "description": "Combines the working group's source KGs into one merged knowledge graph,\ndedupes nodes by cosine similarity (default threshold 0.92), and\noptionally promotes the result to the group's `canonical_kg_id` pointer.\nIf `source_kg_ids` is omitted the handler enumerates the root KGs\n(`parent_kg_id IS NULL`) in the group; passing an explicit list lets\ncallers merge a subset. Response carries node / edge counts and the\nnumber of collapsed nodes for visibility. Auth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source_kg_ids": { "oneOf": [ { "type": "array", "items": { "type": "string", "format": "uuid" } }, { "type": "null" } ], "description": "Optional explicit list of source KG ids. When omitted, every root\nKG (parent_kg_id = NULL) in the working group is included.\n" }, "similarity_threshold": { "type": [ "number", "null" ], "description": "Optional cosine similarity threshold for semantic dedup. Default 0.92." }, "merged_kg_name": { "type": [ "string", "null" ] }, "update_canonical_pointer": { "type": "boolean", "default": true } } }, "examples": { "default": { "summary": "Merge every root KG in the group with default settings", "value": {} }, "explicit": { "summary": "Merge a specific pair and keep current canonical pointer", "value": { "source_kg_ids": [ "8c7e1a32-1111-4e44-b9d1-aaaaaaaaaaaa", "8c7e1a32-2222-4e44-b9d1-bbbbbbbbbbbb" ], "similarity_threshold": 0.95, "merged_kg_name": "wg-canonical-2026q2", "update_canonical_pointer": false } } } } } }, "responses": { "200": { "description": "Merge complete. Body carries merge stats and the new `merged_kg_id`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "merged_kg_id", "source_kg_ids", "total_input_nodes", "total_input_edges", "final_node_count", "final_edge_count", "nodes_collapsed", "edges_dropped", "canonical_pointer_updated" ], "properties": { "merged_kg_id": { "type": "string", "format": "uuid" }, "source_kg_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "total_input_nodes": { "type": "integer", "minimum": 0 }, "total_input_edges": { "type": "integer", "minimum": 0 }, "final_node_count": { "type": "integer", "minimum": 0 }, "final_edge_count": { "type": "integer", "minimum": 0 }, "nodes_collapsed": { "type": "integer", "minimum": 0 }, "edges_dropped": { "type": "integer", "minimum": 0 }, "canonical_pointer_updated": { "type": "boolean" } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_mergeWorkingGroupKgs_WorkingGroups", "resource_uri": "yf://agents/working-groups", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"similarity_threshold\":0.9}' \\\n https://agents.yieldfabric.com/working-groups/{id}/merge-kgs\n" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx\nr = httpx.post(\n f\"https://agents.yieldfabric.com/working-groups/{gid}/merge-kgs\",\n headers={\"Authorization\": f\"Bearer {jwt}\"},\n json={\"similarity_threshold\": 0.9},\n timeout=120.0,\n)\nr.raise_for_status()\nmerged = r.json()\n" } ], "x-related": [ { "guide": "working-groups", "relation": "concept" } ] } }, "/working-groups/{id}/pipeline-drafts": { "get": { "operationId": "listPipelineDrafts_PipelineDrafts", "x-method": "GET", "x-path": "/working-groups/{id}/pipeline-drafts", "x-handler": "wg::list_pipeline_drafts", "tags": [ "Pipeline Drafts" ], "summary": "List pipeline drafts (scratch workflows) for a working group", "description": "Return pipeline drafts authored against the working group identified by\n`id`. Drafts are the scratch state for workflows being designed in chat\n(typically by the Pipeline Builder agent) before they are submitted as\nreusable `workflow_templates`. Filter by status with the `status` query\nparam — defaults to `draft` (a frontend alias for the underlying\n`proposed` state). Auth: bearer JWT. Caller must be a group member\nwith `ViewWorkflows` permission. Idempotent.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status. `draft` (default) maps to the internal `proposed`\nstate; pass `confirmed` to list drafts that have been submitted as\ntemplates, `cancelled` for rejected drafts.\n", "schema": { "type": "string", "enum": [ "draft", "proposed", "confirmed", "cancelled" ], "default": "draft" } } ], "responses": { "200": { "description": "Object with `drafts` array.", "content": { "application/json": { "schema": { "type": "object", "required": [ "drafts" ], "properties": { "drafts": { "type": "array", "items": { "type": "object", "description": "A pipeline draft is a `financial_intents` row of type `pipeline` with\nstatus `proposed` — the wire format renames status `proposed` →\n`draft` for backwards compat with the frontend.\n", "required": [ "id", "name", "status", "created_by", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "group_id": { "type": [ "string", "null" ], "format": "uuid" }, "thread_id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "steps": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ], "description": "Array of step definitions in CreateStepInput form." }, "discovered_tasks": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "explanation": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "confirmed", "executing", "completed", "failed", "cancelled" ] }, "workflow_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } }, "examples": { "one-draft": { "summary": "One draft in proposed state", "value": { "drafts": [ { "id": "ddddeeee-1234-5678-9abc-deffeedd1234", "name": "Weekly portfolio review", "description": "Auto-generated portfolio status workflow", "steps": [ { "key": "load_positions", "type": "agent", "name": "Load positions" }, { "key": "summarise", "type": "agent", "name": "Summarise positions" } ], "explanation": "Two-step weekly review: load + summarise.", "status": "draft", "workflow_id": null, "created_by": "agent.pipeline_builder", "created_at": "2027-05-16T11:00:00Z", "updated_at": "2027-05-16T11:00:00Z" } ] } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listPipelineDrafts_PipelineDrafts", "resource_uri": "yf://agents/pipeline-drafts", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/working-groups/6c1c79bb-7e2e-4a06-83a7-9d4d6c7a0e21/pipeline-drafts?status=draft\"" } ], "x-related": [ { "operationId": "getPipelineDraft_PipelineDrafts" }, { "operationId": "savePipelineDraft_PipelineDrafts" }, { "operationId": "submitPipelineDraft_PipelineDrafts" }, { "operationId": "rejectPipelineDraft_PipelineDrafts" }, { "url": "guides/pipelines-and-kgs.md", "description": "Pipelines and KGs guide" } ] }, "post": { "operationId": "savePipelineDraft_PipelineDrafts", "x-method": "POST", "x-path": "/working-groups/{id}/pipeline-drafts", "x-handler": "wg::save_pipeline_draft", "tags": [ "Pipeline Drafts" ], "summary": "Create or upsert a pipeline draft for a working-group thread", "description": "Persist a pipeline draft for a working group, keyed by `(group_id,\nthread_id)`. The handler upserts: if a draft is already in `proposed`\nstate for the same group + thread, its title, description, steps, and\nbuilder metadata are overwritten; otherwise a new row is created. The\nbody's `discovered_tasks` and `explanation` are stored in\n`builder_metadata` for the Pipeline Builder agent to consume on later\nrounds. Auth: bearer JWT. Caller must have `ManageWorkflows`\npermission on the group. Idempotent at the `(group, thread)` level —\nre-saving the same draft simply updates it.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "thread_id", "name", "steps" ], "properties": { "thread_id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "steps": { "type": "array", "items": { "type": "object", "description": "Step definition accepted by createWorkflow / save_pipeline_draft.", "required": [ "step_key", "name", "step_type" ], "properties": { "step_key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "step_type": { "type": "string" }, "step_config": { "description": "Arbitrary JSON value." }, "assignee_type": { "type": [ "string", "null" ], "enum": [ "entity", "role", "group", "originator", null ] }, "assignee_id": { "type": [ "string", "null" ] }, "depends_on": { "type": "array", "items": { "type": "string" } }, "input_bindings": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] } } } }, "discovered_tasks": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "explanation": { "type": [ "string", "null" ] } } }, "examples": { "two-steps": { "summary": "A two-step builder draft", "value": { "thread_id": "22222222-3333-4444-5555-666666666666", "name": "Weekly portfolio review", "description": "Auto-generated portfolio status workflow", "steps": [ { "key": "load_positions", "name": "Load positions", "step_type": "agent", "config": { "agent_id": "acme.position-loader" } }, { "key": "summarise", "name": "Summarise positions", "step_type": "agent", "config": { "agent_id": "acme.summariser" }, "depends_on": [ "load_positions" ] } ], "discovered_tasks": [], "explanation": "Two-step weekly review: load + summarise." } } } } } }, "responses": { "200": { "description": "Draft upserted. Returns the persisted row id and status.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "status", "group_id", "thread_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "group_id": { "type": "string", "format": "uuid" }, "thread_id": { "type": "string" } } }, "examples": { "saved": { "summary": "Saved", "value": { "id": "ddddeeee-1234-5678-9abc-deffeedd1234", "status": "proposed", "group_id": "6c1c79bb-7e2e-4a06-83a7-9d4d6c7a0e21", "thread_id": "22222222-3333-4444-5555-666666666666" } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_savePipelineDraft_PipelineDrafts", "resource_uri": "yf://agents/pipeline-drafts", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" \\\n -d '{\"thread_id\":\"22222222-3333-4444-5555-666666666666\",\"name\":\"Weekly review\",\"steps\":[]}' \\\n https://agents.yieldfabric.com/working-groups/6c1c79bb-7e2e-4a06-83a7-9d4d6c7a0e21/pipeline-drafts\n" } ], "x-related": [ { "operationId": "getPipelineDraft_PipelineDrafts" }, { "operationId": "modifyPipelineDraft_PipelineDrafts" }, { "operationId": "submitPipelineDraft_PipelineDrafts" }, { "operationId": "rejectPipelineDraft_PipelineDrafts" }, { "url": "guides/pipelines-and-kgs.md", "description": "Pipelines and KGs guide" } ] } }, "/working-groups/{id}/pipeline-drafts/{draft_id}": { "get": { "operationId": "getPipelineDraft_PipelineDrafts", "x-method": "GET", "x-path": "/working-groups/{id}/pipeline-drafts/{draft_id}", "x-handler": "wg::get_pipeline_draft", "tags": [ "Pipeline Drafts" ], "summary": "Get a single pipeline draft", "description": "Return one pipeline draft. Carries the draft's step list (in\n`CreateStepInput` format), the agent's natural-language explanation,\nthe proposing agent id, and the current status. Drafts are stored in\nthe unified `financial_intents` table with `intent_type='pipeline'` so\nthe response also exposes `workflow_id` (set once the draft has been\nsubmitted and the workflow instantiated). Auth: bearer JWT. Caller\nmust be a group member with `ViewWorkflows`. Idempotent.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "draft_id", "in": "path", "required": true, "description": "Pipeline-draft id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Pipeline draft details.", "content": { "application/json": { "schema": { "type": "object", "description": "A pipeline draft is a `financial_intents` row of type `pipeline` with\nstatus `proposed` — the wire format renames status `proposed` →\n`draft` for backwards compat with the frontend.\n", "required": [ "id", "name", "status", "created_by", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "group_id": { "type": [ "string", "null" ], "format": "uuid" }, "thread_id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "steps": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ], "description": "Array of step definitions in CreateStepInput form." }, "discovered_tasks": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "explanation": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "confirmed", "executing", "completed", "failed", "cancelled" ] }, "workflow_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } }, "examples": { "draft": { "summary": "Two-step weekly review draft", "value": { "id": "ddddeeee-1234-5678-9abc-deffeedd1234", "group_id": "6c1c79bb-7e2e-4a06-83a7-9d4d6c7a0e21", "thread_id": "22222222-3333-4444-5555-666666666666", "name": "Weekly portfolio review", "description": "Auto-generated portfolio status workflow", "steps": [ { "key": "load_positions", "type": "agent", "name": "Load positions" }, { "key": "summarise", "type": "agent", "name": "Summarise positions" } ], "discovered_tasks": [], "explanation": "Two-step weekly review: load + summarise.", "status": "draft", "workflow_id": null, "created_by": "agent.pipeline_builder", "created_at": "2027-05-16T11:00:00Z", "updated_at": "2027-05-16T11:00:00Z" } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getPipelineDraft_PipelineDrafts", "resource_uri": "yf://agents/pipeline-drafts", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/6c1c79bb-7e2e-4a06-83a7-9d4d6c7a0e21/pipeline-drafts/ddddeeee-1234-5678-9abc-deffeedd1234" } ], "x-related": [ { "operationId": "listPipelineDrafts_PipelineDrafts" }, { "operationId": "modifyPipelineDraft_PipelineDrafts" }, { "operationId": "submitPipelineDraft_PipelineDrafts" }, { "operationId": "rejectPipelineDraft_PipelineDrafts" }, { "url": "guides/pipelines-and-kgs.md", "description": "Pipelines and KGs guide" } ] }, "patch": { "operationId": "modifyPipelineDraft_PipelineDrafts", "x-method": "PATCH", "x-path": "/working-groups/{id}/pipeline-drafts/{draft_id}", "x-handler": "wg::modify_pipeline_draft", "tags": [ "Pipeline Drafts" ], "summary": "Patch a pipeline draft's fields", "description": "Update one or more of a draft's `name`, `description`, or `steps`. All\nthree fields are optional (PATCH semantics — `COALESCE($field, current)`\nis applied in the underlying UPDATE). Only drafts still in the\n`proposed` state can be modified; submitting or rejecting locks them.\nAuth: bearer JWT. Caller must have `ManageWorkflows` on the group.\nNot idempotent in the strict sense (timestamps update on each call) but\nsafe to retry with the same body. Returns 404 when the draft does not\nexist or has already been submitted.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "draft_id", "in": "path", "required": true, "description": "Pipeline-draft id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "steps": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] } } }, "examples": { "rename": { "summary": "Just rename", "value": { "name": "Weekly portfolio review (v2)" } }, "update-steps": { "summary": "Replace the step list", "value": { "steps": [ { "key": "load_positions", "name": "Load positions", "step_type": "agent" }, { "key": "summarise", "name": "Summarise", "step_type": "agent" }, { "key": "notify", "name": "Send notification", "step_type": "human_task" } ] } } } } } }, "responses": { "200": { "description": "Draft updated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "status", "modified" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "draft" ] }, "modified": { "type": "boolean" } } }, "examples": { "modified": { "summary": "Modified", "value": { "id": "ddddeeee-1234-5678-9abc-deffeedd1234", "status": "draft", "modified": true } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_modifyPipelineDraft_PipelineDrafts", "resource_uri": "yf://agents/pipeline-drafts", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PATCH -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Renamed draft\"}' \\\n https://agents.yieldfabric.com/working-groups/6c1c79bb-7e2e-4a06-83a7-9d4d6c7a0e21/pipeline-drafts/ddddeeee-1234-5678-9abc-deffeedd1234\n" } ], "x-related": [ { "operationId": "getPipelineDraft_PipelineDrafts" }, { "operationId": "savePipelineDraft_PipelineDrafts" }, { "operationId": "submitPipelineDraft_PipelineDrafts" }, { "operationId": "rejectPipelineDraft_PipelineDrafts" }, { "url": "guides/pipelines-and-kgs.md", "description": "Pipelines and KGs guide" } ] } }, "/working-groups/{id}/pipeline-drafts/{draft_id}/reject": { "post": { "operationId": "rejectPipelineDraft_PipelineDrafts", "x-method": "POST", "x-path": "/working-groups/{id}/pipeline-drafts/{draft_id}/reject", "x-handler": "wg::reject_pipeline_draft", "tags": [ "Pipeline Drafts" ], "summary": "Reject and cancel a pipeline draft", "description": "Mark the draft as `cancelled` so it stops appearing in the active\ndrafts list. The draft row itself is preserved for audit. No request\nbody is required; the handler accepts an empty JSON object. Auth:\nbearer JWT. Caller must have `ViewWorkflows` on the group. Not\nidempotent in the strict sense (the status is set unconditionally on\nevery call) but safe to retry.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "draft_id", "in": "path", "required": true, "description": "Pipeline-draft id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Draft cancelled.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "rejected" ] } } }, "examples": { "rejected": { "summary": "Rejected", "value": { "id": "ddddeeee-1234-5678-9abc-deffeedd1234", "status": "rejected" } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_rejectPipelineDraft_PipelineDrafts", "resource_uri": "yf://agents/pipeline-drafts", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" \\\n -d '{}' \\\n https://agents.yieldfabric.com/working-groups/6c1c79bb-7e2e-4a06-83a7-9d4d6c7a0e21/pipeline-drafts/ddddeeee-1234-5678-9abc-deffeedd1234/reject\n" } ], "x-related": [ { "operationId": "submitPipelineDraft_PipelineDrafts" }, { "operationId": "getPipelineDraft_PipelineDrafts" }, { "operationId": "modifyPipelineDraft_PipelineDrafts" }, { "url": "guides/pipelines-and-kgs.md", "description": "Pipelines and KGs guide" } ] } }, "/working-groups/{id}/pipeline-drafts/{draft_id}/submit": { "post": { "operationId": "submitPipelineDraft_PipelineDrafts", "x-method": "POST", "x-path": "/working-groups/{id}/pipeline-drafts/{draft_id}/submit", "x-handler": "wg::submit_pipeline_draft", "tags": [ "Pipeline Drafts" ], "summary": "Submit a draft as a reusable workflow template", "description": "Promote a `proposed` draft to a reusable `workflow_template`. The\nhandler converts each draft step (accepting both `step_key`/`step_type`/\n`step_config` and the shorter `key`/`type`/`config` shapes) into a\n`TemplateStep`, builds a `WorkflowTemplate` named after the draft, and\npersists it via the template registry. Any `reasoning_context` carried\nin `builder_metadata` is copied to the template's\n`reasoning_context` column. The draft is then marked `confirmed`.\nSubmitting a draft that is already confirmed is a no-op success.\nOptional body lets the caller request `auto_start: true` (not yet\nhonoured server-side). Auth: bearer JWT. Caller must have\n`ViewWorkflows`. Not idempotent — each submit re-runs the template\nupsert (safe on retry).\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "draft_id", "in": "path", "required": true, "description": "Pipeline-draft id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "auto_start": { "type": [ "boolean", "null" ], "default": false } } }, "examples": { "plain": { "summary": "Just submit", "value": {} }, "with-auto-start": { "summary": "Request auto-start (advisory)", "value": { "auto_start": true } } } } } }, "responses": { "200": { "description": "Draft submitted. Returns the new template name (snake_cased from the draft title).", "content": { "application/json": { "schema": { "type": "object", "required": [ "draft_id", "template_name", "display_name", "status" ], "properties": { "draft_id": { "type": "string", "format": "uuid" }, "template_name": { "type": "string", "description": "Generated template slug." }, "display_name": { "type": "string" }, "status": { "type": "string", "enum": [ "submitted", "confirmed", "executing", "completed", "failed", "cancelled" ] } } }, "examples": { "submitted": { "summary": "Submitted", "value": { "draft_id": "ddddeeee-1234-5678-9abc-deffeedd1234", "template_name": "weekly_portfolio_review", "display_name": "Weekly portfolio review", "status": "submitted" } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_submitPipelineDraft_PipelineDrafts", "resource_uri": "yf://agents/pipeline-drafts", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" \\\n -d '{}' \\\n https://agents.yieldfabric.com/working-groups/6c1c79bb-7e2e-4a06-83a7-9d4d6c7a0e21/pipeline-drafts/ddddeeee-1234-5678-9abc-deffeedd1234/submit\n" } ], "x-related": [ { "operationId": "getPipelineDraft_PipelineDrafts" }, { "operationId": "modifyPipelineDraft_PipelineDrafts" }, { "operationId": "rejectPipelineDraft_PipelineDrafts" }, { "url": "guides/pipelines-and-kgs.md", "description": "Pipelines and KGs guide" } ] } }, "/working-groups/{id}/presence": { "get": { "operationId": "getGroupPresence_Presence", "x-method": "GET", "x-path": "/working-groups/{id}/presence", "x-handler": "wg::get_group_presence", "tags": [ "Presence" ], "summary": "Snapshot of who is currently online in the group", "description": "Returns the current presence list for every member of the group whose\n`visibility_mode` is not `invisible`. Reads from `user_presence` (the\ncross-server source of truth). For real-time updates subscribe to\n`streamChat_Chat` and watch for `PresenceUpdate` events. Auth:\nbearer JWT; caller must hold `ViewMembers`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current presence rows.", "content": { "application/json": { "schema": { "type": "object", "required": [ "members" ], "properties": { "members": { "type": "array", "items": { "type": "object", "required": [ "entity_id", "status", "last_seen_at" ], "properties": { "entity_id": { "type": "string" }, "status": { "type": "string", "enum": [ "online", "away", "busy", "invisible", "offline" ] }, "last_seen_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getGroupPresence_Presence", "resource_uri": "yf://agents/presence", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/{id}/presence" } ], "x-related": [ { "operationId": "presenceJoin_Presence", "relation": "sibling" }, { "operationId": "presenceHeartbeat_Presence", "relation": "sibling" }, { "operationId": "streamChat_Chat", "relation": "watch" }, { "guide": "streaming", "relation": "concept" } ] } }, "/working-groups/{id}/files/{file_id}": { "delete": { "operationId": "deleteRoomFile_WorkingGroups", "x-method": "DELETE", "x-path": "/working-groups/{id}/files/{file_id}", "x-handler": "deal_room::handlers::delete_room_file", "tags": [ "Working Groups" ], "summary": "Remove a file from a room", "description": "Deletes one active room file. An upload can be the wrong file, a\nduplicate, or a failed attempt, and a room with no way to undo one\naccumulates them.\n\nTwo files are NOT removable, and each refuses with a reason rather than\na database error:\n\n* a SIGNED file — someone attested to those exact bytes, so it is\n evidence and it stays (409);\n* a file whose content reached the room's KNOWLEDGE GRAPH — deleting\n the bytes would leave the room answering out of a file that no longer\n exists, so it leaves knowledge first (409). The `document_sources`\n foreign key enforces this regardless.\n\nEverything else deletes cleanly, including a file that was indexed for\nsearch but never promoted: its vector admissions and signature rows\ncascade and the room's storage quota is returned.\n\nAuthority is the uploader or a room admin — a member may add files, but\nremoving someone else's is an admin act. Service tokens are refused;\nthe caller must be an active member whose terms are accepted.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The file was removed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted", "filename" ], "properties": { "deleted": { "type": "string", "format": "uuid" }, "filename": { "type": "string" } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "A service token, or a member who neither uploaded the file nor administers the room." }, "404": { "description": "No such active file in this room." }, "409": { "description": "The file is signed, or its content is in the room's knowledge." } }, "x-mcp": { "tool_name": "yieldfabric_agents_deleteRoomFile_WorkingGroups", "resource_uri": "yf://agents/working-groups", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X DELETE -H \"Authorization: Bearer $JWT\" \\\n https://agents.yieldfabric.com/working-groups/{id}/files/{file_id}\n" } ], "x-related": [ { "operationId": "uploadRoomFiles_WorkingGroups", "relation": "sibling" }, { "operationId": "downloadRoomFile_WorkingGroups", "relation": "sibling" } ] } }, "/working-groups/{id}/query": { "post": { "operationId": "groupRagQuery_WorkingGroups", "x-method": "POST", "x-path": "/working-groups/{id}/query", "x-handler": "wg::group_rag_query", "tags": [ "Working Groups" ], "summary": "Run a RAG query against the group's documents", "description": "Issues a Retrieval-Augmented Generation query scoped to the working\ngroup's documents. The pipeline assembles a context window from the\ngroup's chunks (and any KGs attached to those documents), prompts the\nLLM, and returns the generated answer plus citations, retrieval\nquality, and the strategy that was selected. The optional `use_graph_rag`\nflag enables graph-aware retrieval where supported. Set\n`include_federated: true` to also fan out to groups that have granted\nthis group federation access. `full` and `selective` grants merge\npermitted citations; `summary_only` grants add only a bounded aggregate\nhit count to `federated_sources`, without returning or LLM-processing\nremote retrieved text. This is the same behaviour as the dedicated\n`POST /working-groups/{id}/query/federated` route, which is an\nalways-federated alias; `federated_rerank_top_n` (default 3, server\nmaximum 20) caps results from each federated group. Auth: bearer JWT;\ncaller must hold `ViewDocuments`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "RAG query body. Extra fields are passed through to the retrieval\npipeline as opaque filter hints (`top_k`, `score_floor`, etc.) —\neach strategy reads what it understands, ignores the rest. Kept open\non purpose so adding a new strategy filter doesn't bump the schema.\n", "required": [ "query" ], "additionalProperties": true, "properties": { "query": { "type": "string" }, "use_graph_rag": { "type": "boolean", "default": false, "description": "Enable graph-aware retrieval where the group's KGs support it." }, "include_federated": { "type": "boolean", "default": false, "description": "Also retrieve from groups that have granted this group federation access, merging their citations and adding a `federated_sources` block to the response. Equivalent to calling the always-federated `POST /working-groups/{id}/query/federated` route. On `POST .../query/federated` this flag is forced on." }, "federated_rerank_top_n": { "type": "integer", "minimum": 1, "maximum": 20, "default": 3, "description": "Cap on reranked results pulled from EACH federated group (the own group uses its default). Only applies when `include_federated` is true." } } }, "examples": { "simple": { "summary": "Plain query", "value": { "query": "Summarize the latest counterparty memo" } }, "graph": { "summary": "Graph-aware retrieval", "value": { "query": "How does this counterparty relate to the new credit facility?", "use_graph_rag": true } }, "federated": { "summary": "Include federated groups", "value": { "query": "List counterparties seen across our partner desks", "include_federated": true, "federated_rerank_top_n": 5 } } } } } }, "responses": { "200": { "description": "Generated answer plus citations and retrieval metadata.", "content": { "application/json": { "schema": { "type": "object", "required": [ "answer", "citations", "chunks_retrieved" ], "properties": { "answer": { "type": "string" }, "confidence": { "type": [ "number", "null" ] }, "citations": { "type": "array", "description": "One per surfaced chunk/frame. Shape is strategy-specific\n(chunk citations carry `chunk_id` + `excerpt`; frame citations\ncarry `frame_id` + `label`) — kept open per item.\n", "items": { "type": "object", "additionalProperties": true } }, "chunks_retrieved": { "type": "integer", "minimum": 0 }, "strategy_used": { "type": [ "string", "null" ] }, "federated_sources": { "type": "array", "description": "Present when federation was requested. Full/selective entries describe surfaced remote citations; summary_only entries expose only the bounded aggregate hit count and never add remote citations.", "items": { "type": "object", "required": [ "group_id", "chunks_retrieved", "policy_type" ], "properties": { "group_id": { "type": "string", "format": "uuid" }, "chunks_retrieved": { "type": "integer", "minimum": 0, "maximum": 20 }, "policy_type": { "type": "string", "enum": [ "full", "selective", "summary_only" ] } } } } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_groupRagQuery_WorkingGroups", "resource_uri": "yf://agents/working-groups", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"query\":\"summarize the latest counterparty memo\"}' \\\n https://agents.yieldfabric.com/working-groups/{id}/query\n" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx\nr = httpx.post(\n f\"https://agents.yieldfabric.com/working-groups/{group_id}/query\",\n headers={\"Authorization\": f\"Bearer {jwt}\"},\n json={\"query\": \"summarize the latest counterparty memo\"},\n)\nr.raise_for_status()\nanswer = r.json()[\"answer\"]\n" } ], "x-related": [ { "operationId": "federatedRagQuery_WorkingGroups", "relation": "sibling" }, { "operationId": "listGroupDocuments_GroupDocuments", "relation": "prerequisite" }, { "guide": "working-groups", "relation": "concept" } ] } }, "/working-groups/{id}/query/batch": { "post": { "operationId": "groupRagQueryBatch_WorkingGroups", "x-method": "POST", "x-path": "/working-groups/{id}/query/batch", "x-handler": "wg::group_rag_query_batch", "tags": [ "Working Groups" ], "summary": "Answer several room questions in one request", "description": "Runs up to 8 RAG queries against the group's documents in ONE request,\neach shaped exactly like a `POST /working-groups/{id}/query` body, and\nreturns their answers in the order asked.\n\nWhy it exists: the service admits a bounded number of concurrent AI\nrequests PER PERSON (`AGENTS_INFERENCE_PER_ENTITY`, default 3) and\nrejects the rest with `429 inference_limit`. A screen that needs several\nanswers at once — the deal brief reads five parked facets per document\nset — is one person's SINGLE action, so sending it as separate requests\nspent several permits on one action and lost whichever queries exceeded\nthe ceiling. A batch holds ONE permit for the whole read. Internal\nfan-out is bounded so one permit cannot buy unbounded inference.\n\nOne query failing never fails the batch: each entry carries its own `ok`,\nand a failed one carries the `status` and `error` it would have had on\nits own. Auth, billing and admission are identical to the single-query\nroute; the caller must hold `ViewDocuments`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "queries" ], "properties": { "queries": { "type": "array", "minItems": 1, "maxItems": 8, "description": "Each item is a single-query request body.", "items": { "type": "object", "description": "RAG query body. Extra fields are passed through to the retrieval\npipeline as opaque filter hints (`top_k`, `score_floor`, etc.) —\neach strategy reads what it understands, ignores the rest. Kept open\non purpose so adding a new strategy filter doesn't bump the schema.\n", "required": [ "query" ], "additionalProperties": true, "properties": { "query": { "type": "string" }, "use_graph_rag": { "type": "boolean", "default": false, "description": "Enable graph-aware retrieval where the group's KGs support it." }, "include_federated": { "type": "boolean", "default": false, "description": "Also retrieve from groups that have granted this group federation access, merging their citations and adding a `federated_sources` block to the response. Equivalent to calling the always-federated `POST /working-groups/{id}/query/federated` route. On `POST .../query/federated` this flag is forced on." }, "federated_rerank_top_n": { "type": "integer", "minimum": 1, "maximum": 20, "default": 3, "description": "Cap on reranked results pulled from EACH federated group (the own group uses its default). Only applies when `include_federated` is true." } } } } } }, "examples": { "brief": { "summary": "The deal brief's five parked facets", "value": { "queries": [ { "query": "What are the key deal terms?", "max_answer_tokens": 4000 }, { "query": "What is the capital structure?", "max_answer_tokens": 4000 }, { "query": "What is the collateral pool?", "max_answer_tokens": 4000 }, { "query": "What are the key dates?", "max_answer_tokens": 4000 }, { "query": "Who are the parties?", "max_answer_tokens": 4000 } ] } } } } } }, "responses": { "200": { "description": "One result per query, in the order asked. A successful entry is the\nsingle-query response object plus `ok: true`; a failed one is\n`{ ok: false, status, error }`.\n", "content": { "application/json": { "schema": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" }, "status": { "type": "integer", "description": "Present when `ok` is false — the status this query would have returned alone." }, "error": { "type": [ "string", "null" ] }, "answer": { "type": [ "string", "null" ] }, "citations": { "type": [ "array", "null" ], "items": { "type": "object" } }, "confidence": { "type": [ "number", "null" ] }, "chunks_retrieved": { "type": [ "integer", "null" ] } } } } } } } } }, "400": { "description": "The batch was empty or carried more than 8 queries." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "429": { "description": "Too much AI work is already in flight for this caller\n(`code: inference_limit`). Carries `Retry-After`; the whole batch is\nadmitted or rejected together.\n" } }, "x-mcp": { "tool_name": "yieldfabric_agents_groupRagQueryBatch_WorkingGroups", "resource_uri": "yf://agents/working-groups", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"queries\":[{\"query\":\"what are the key dates?\"},{\"query\":\"who are the parties?\"}]}' \\\n https://agents.yieldfabric.com/working-groups/{id}/query/batch\n" } ], "x-related": [ { "operationId": "groupRagQuery_WorkingGroups", "relation": "sibling" }, { "guide": "working-groups", "relation": "concept" } ] } }, "/working-groups/{id}/query/federated": { "post": { "operationId": "federatedRagQuery_WorkingGroups", "x-method": "POST", "x-path": "/working-groups/{id}/query/federated", "x-handler": "wg::federated_rag_query", "tags": [ "Working Groups" ], "summary": "RAG query that fans out across federated groups", "description": "Runs a RAG query against this group's documents AND every other group\nthat has granted federation access to this group via an active\n`knowledge_federation_policies` row. `full` and `selective` policies\nmerge permitted remote citations into the response. `summary_only`\npolicies expose only a bounded aggregate hit count in\n`federated_sources`; no remote title, summary, excerpt, citation, or\nretrieved text is sent through the LLM reranker/generator. The\nfederated branch is capped per remote group by the request's\n`federated_rerank_top_n` (default 3, server maximum 20) to keep latency\npredictable. This route always federates regardless of the body's\n`include_federated` flag — it is a thin alias over\n`POST /working-groups/{id}/query` with `include_federated` forced on.\nAuth: bearer JWT; caller must hold `ViewDocuments` on the source group.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "RAG query body. Extra fields are passed through to the retrieval\npipeline as opaque filter hints (`top_k`, `score_floor`, etc.) —\neach strategy reads what it understands, ignores the rest. Kept open\non purpose so adding a new strategy filter doesn't bump the schema.\n", "required": [ "query" ], "additionalProperties": true, "properties": { "query": { "type": "string" }, "use_graph_rag": { "type": "boolean", "default": false, "description": "Enable graph-aware retrieval where the group's KGs support it." }, "include_federated": { "type": "boolean", "default": false, "description": "Also retrieve from groups that have granted this group federation access, merging their citations and adding a `federated_sources` block to the response. Equivalent to calling the always-federated `POST /working-groups/{id}/query/federated` route. On `POST .../query/federated` this flag is forced on." }, "federated_rerank_top_n": { "type": "integer", "minimum": 1, "maximum": 20, "default": 3, "description": "Cap on reranked results pulled from EACH federated group (the own group uses its default). Only applies when `include_federated` is true." } } }, "examples": { "simple": { "summary": "Federated query", "value": { "query": "List counterparties seen across our partner desks" } } } } } }, "responses": { "200": { "description": "Generated answer plus citations and federated-source summary.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "answer", "citations", "chunks_retrieved" ], "properties": { "answer": { "type": "string" }, "confidence": { "type": [ "number", "null" ] }, "citations": { "type": "array", "description": "One per surfaced chunk/frame. Shape is strategy-specific\n(chunk citations carry `chunk_id` + `excerpt`; frame citations\ncarry `frame_id` + `label`) — kept open per item.\n", "items": { "type": "object", "additionalProperties": true } }, "chunks_retrieved": { "type": "integer", "minimum": 0 }, "strategy_used": { "type": [ "string", "null" ] }, "federated_sources": { "type": "array", "description": "Present when federation was requested. Full/selective entries describe surfaced remote citations; summary_only entries expose only the bounded aggregate hit count and never add remote citations.", "items": { "type": "object", "required": [ "group_id", "chunks_retrieved", "policy_type" ], "properties": { "group_id": { "type": "string", "format": "uuid" }, "chunks_retrieved": { "type": "integer", "minimum": 0, "maximum": 20 }, "policy_type": { "type": "string", "enum": [ "full", "selective", "summary_only" ] } } } } } }, { "type": "object", "required": [ "federated_sources" ] } ] } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_federatedRagQuery_WorkingGroups", "resource_uri": "yf://agents/working-groups", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"query\":\"list counterparties across partner desks\"}' \\\n https://agents.yieldfabric.com/working-groups/{id}/query/federated\n" } ], "x-related": [ { "operationId": "groupRagQuery_WorkingGroups", "relation": "sibling" }, { "operationId": "listFederationPolicies_Federation", "relation": "prerequisite" }, { "guide": "working-groups", "relation": "concept" } ] } }, "/working-groups/{id}/solo-thread": { "post": { "operationId": "ensureSoloThread_WorkingGroups", "x-method": "POST", "x-path": "/working-groups/{id}/solo-thread", "x-handler": "wg::ensure_solo_thread", "tags": [ "Working Groups" ], "summary": "Get or create the caller's private \"Solo Terminal\" thread", "description": "Returns (creating if absent) the caller's private Solo Terminal thread\ninside this team workspace. The thread carries `private_to_entity_id =\ncaller` so other group members never see it in `listThreads` or in the\ngroup SSE stream. Idempotent — repeated calls return the same thread.\nUseful for personal scratch chats that live next to the team's shared\nthreads. No request body. Auth: bearer JWT; caller must hold\n`ViewThreads`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Solo thread row (existing or newly created).", "content": { "application/json": { "schema": { "type": "object", "required": [ "thread" ], "properties": { "thread": { "type": "object", "description": "A conversation thread inside a working group.", "required": [ "id", "group_id", "title", "thread_type", "status", "created_by", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "group_id": { "type": "string", "format": "uuid" }, "parent_thread_id": { "type": [ "string", "null" ], "format": "uuid", "description": "When this is a subthread (e.g. a Weaver private chat), the\nparent's id. `null` for top-level threads.\n" }, "private_to_entity_id": { "type": [ "string", "null" ], "description": "When set, this thread is visible only to the named entity.\nCombined with `parent_thread_id` makes a per-user private\nsubthread.\n" }, "title": { "type": "string" }, "thread_type": { "type": "string", "description": "Discriminator for what the thread is used for.\n", "enum": [ "discussion", "reasoning", "pipeline_main", "pipeline_task", "team_chat", "dm", "weaver", "solo_chat", "notebook_entity", "deal_composer", "deal_shared" ] }, "reference_id": { "type": [ "string", "null" ], "description": "Optional pointer to an external entity (workflow id, frame id,\nWeaver root, etc.). Format depends on `thread_type`.\n" }, "status": { "type": "string", "enum": [ "active", "closed" ] }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_ensureSoloThread_WorkingGroups", "resource_uri": "yf://agents/working-groups", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/{id}/solo-thread" } ], "x-related": [ { "operationId": "openWeaverSubthread_Threads", "relation": "sibling" }, { "operationId": "postMessage_Threads", "relation": "next-step" }, { "guide": "threads", "relation": "concept" } ] } }, "/working-groups/{id}/threads": { "post": { "operationId": "createThread_Threads", "x-method": "POST", "x-path": "/working-groups/{id}/threads", "x-handler": "wg::create_thread", "tags": [ "Threads" ], "summary": "Create a new discussion thread", "description": "Creates a thread inside the working group. `title` is the user-visible\nheading; `thread_type` defaults to `discussion` but supports the\nfull set the discussion store knows about (`discussion`, `team_chat`,\n`reasoning`, `file_extraction`, `solo_chat`, `weaver`, `dm`, etc.).\n`reference_id` links the thread to another resource (e.g.\n`workflow::step:` for per-step threads). Auth: bearer\nJWT; caller must hold `PostMessages`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string" }, "thread_type": { "type": "string", "default": "discussion", "enum": [ "discussion", "reasoning", "pipeline_main", "pipeline_task", "team_chat", "dm", "weaver", "solo_chat", "notebook_entity" ] }, "reference_id": { "type": [ "string", "null" ] } } }, "examples": { "minimal": { "summary": "Simple discussion thread", "value": { "title": "Counterparty discussion" } }, "workflow-step": { "summary": "Thread anchored to a workflow step", "value": { "title": "Discuss settlement", "thread_type": "discussion", "reference_id": "workflow:8c7e1a32-1111-4e44-b9d1-aaaaaaaaaaaa:step:settle" } } } } } }, "responses": { "201": { "description": "Thread created.", "content": { "application/json": { "schema": { "type": "object", "description": "A conversation thread inside a working group.", "required": [ "id", "group_id", "title", "thread_type", "status", "created_by", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "group_id": { "type": "string", "format": "uuid" }, "parent_thread_id": { "type": [ "string", "null" ], "format": "uuid", "description": "When this is a subthread (e.g. a Weaver private chat), the\nparent's id. `null` for top-level threads.\n" }, "private_to_entity_id": { "type": [ "string", "null" ], "description": "When set, this thread is visible only to the named entity.\nCombined with `parent_thread_id` makes a per-user private\nsubthread.\n" }, "title": { "type": "string" }, "thread_type": { "type": "string", "description": "Discriminator for what the thread is used for.\n", "enum": [ "discussion", "reasoning", "pipeline_main", "pipeline_task", "team_chat", "dm", "weaver", "solo_chat", "notebook_entity", "deal_composer", "deal_shared" ] }, "reference_id": { "type": [ "string", "null" ], "description": "Optional pointer to an external entity (workflow id, frame id,\nWeaver root, etc.). Format depends on `thread_type`.\n" }, "status": { "type": "string", "enum": [ "active", "closed" ] }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_createThread_Threads", "resource_uri": "yf://agents/threads", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"title\":\"Counterparty discussion\"}' \\\n https://agents.yieldfabric.com/working-groups/{id}/threads\n" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx\nr = httpx.post(\n f\"https://agents.yieldfabric.com/working-groups/{gid}/threads\",\n headers={\"Authorization\": f\"Bearer {jwt}\"},\n json={\"title\": \"Counterparty discussion\"},\n)\nr.raise_for_status()\n" } ], "x-related": [ { "operationId": "listThreads_Threads", "relation": "sibling" }, { "operationId": "postMessage_Threads", "relation": "next-step" }, { "guide": "threads", "relation": "concept" } ] }, "get": { "operationId": "listThreads_Threads", "x-method": "GET", "x-path": "/working-groups/{id}/threads", "x-handler": "wg::list_threads", "tags": [ "Threads" ], "summary": "List visible threads in the working group", "description": "Returns a page of the threads in the group the caller can see, newest\nfirst (`created_at DESC, id DESC` for deterministic timestamp ties).\nConcurrent inserts/deletes can still shift offsets; this is not a snapshot.\nPrivate threads (`private_to_entity_id` set, e.g. Solo Terminal,\nWeaver subthreads belonging to other users) are filtered out — only the\nowner sees their own. `types` narrows to a comma-separated `thread_type`\nallow-list in SQL; omit it for every type. The page is `limit` (default\n100, maximum 500) rows from `offset`; the additive `pagination` object\nsays whether more exist and the next offset. An omitted limit used to\nmean the whole group — 294,818 rows on the live deployment, mostly\nper-document bookkeeping threads — and is now the default page: a\nclient that wants conversations asks for `types=team_chat,discussion`,\nand one that needs a specific thread reads it with\n`GET /working-groups/{id}/threads/{tid}`. Auth: bearer JWT; caller must\nhold `ViewThreads`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "types", "in": "query", "required": false, "description": "Comma-separated `thread_type` allow-list. An explicit empty list\nreturns no rows.\n", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size; defaults to 100 and is clamped to 1..500.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Rows to skip; defaults to 0. `pagination.next_offset` carries the next.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "One page of visible threads plus pagination metadata.", "content": { "application/json": { "schema": { "type": "object", "required": [ "threads", "pagination" ], "properties": { "threads": { "type": "array", "items": { "type": "object", "description": "A conversation thread inside a working group.", "required": [ "id", "group_id", "title", "thread_type", "status", "created_by", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "group_id": { "type": "string", "format": "uuid" }, "parent_thread_id": { "type": [ "string", "null" ], "format": "uuid", "description": "When this is a subthread (e.g. a Weaver private chat), the\nparent's id. `null` for top-level threads.\n" }, "private_to_entity_id": { "type": [ "string", "null" ], "description": "When set, this thread is visible only to the named entity.\nCombined with `parent_thread_id` makes a per-user private\nsubthread.\n" }, "title": { "type": "string" }, "thread_type": { "type": "string", "description": "Discriminator for what the thread is used for.\n", "enum": [ "discussion", "reasoning", "pipeline_main", "pipeline_task", "team_chat", "dm", "weaver", "solo_chat", "notebook_entity", "deal_composer", "deal_shared" ] }, "reference_id": { "type": [ "string", "null" ], "description": "Optional pointer to an external entity (workflow id, frame id,\nWeaver root, etc.). Format depends on `thread_type`.\n" }, "status": { "type": "string", "enum": [ "active", "closed" ] }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } }, "pagination": { "type": "object", "description": "Offset page metadata. `has_more` is false and `next_offset` null on the\nlast page.\n", "required": [ "limit", "offset", "has_more", "next_offset" ], "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 500 }, "offset": { "type": "integer", "minimum": 0 }, "has_more": { "type": "boolean" }, "next_offset": { "type": [ "integer", "null" ], "minimum": 0 } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listThreads_Threads", "resource_uri": "yf://agents/threads", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/{id}/threads" } ], "x-related": [ { "operationId": "createThread_Threads", "relation": "sibling" }, { "operationId": "getMessages_Threads", "relation": "child" }, { "guide": "threads", "relation": "concept" } ] } }, "/working-groups/{id}/threads/{tid}": { "get": { "operationId": "getThread_Threads", "x-method": "GET", "x-path": "/working-groups/{id}/threads/{tid}", "x-handler": "wg::get_thread", "tags": [ "Threads" ], "summary": "Read one thread by id", "description": "Returns one thread's metadata under the same visibility rule as the\nlist: a private subthread (Solo Terminal, Weaver) is visible only to its\nowner, and anything else — a thread in another group, a deleted thread,\nsomeone else's private subthread — answers 404. Use this to resolve the\nthread a client is looking at (and its `parent_thread_id`) instead of\nlisting the group and searching: the list is a bounded page, not the\nwhole group. Auth: bearer JWT; caller must hold `ViewThreads`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "tid", "in": "path", "required": true, "description": "Thread id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The thread.", "content": { "application/json": { "schema": { "type": "object", "description": "A conversation thread inside a working group.", "required": [ "id", "group_id", "title", "thread_type", "status", "created_by", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "group_id": { "type": "string", "format": "uuid" }, "parent_thread_id": { "type": [ "string", "null" ], "format": "uuid", "description": "When this is a subthread (e.g. a Weaver private chat), the\nparent's id. `null` for top-level threads.\n" }, "private_to_entity_id": { "type": [ "string", "null" ], "description": "When set, this thread is visible only to the named entity.\nCombined with `parent_thread_id` makes a per-user private\nsubthread.\n" }, "title": { "type": "string" }, "thread_type": { "type": "string", "description": "Discriminator for what the thread is used for.\n", "enum": [ "discussion", "reasoning", "pipeline_main", "pipeline_task", "team_chat", "dm", "weaver", "solo_chat", "notebook_entity", "deal_composer", "deal_shared" ] }, "reference_id": { "type": [ "string", "null" ], "description": "Optional pointer to an external entity (workflow id, frame id,\nWeaver root, etc.). Format depends on `thread_type`.\n" }, "status": { "type": "string", "enum": [ "active", "closed" ] }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/{id}/threads/{tid}" } ], "x-related": [ { "operationId": "listThreads_Threads", "relation": "sibling" }, { "operationId": "getMessages_Threads", "relation": "child" }, { "guide": "threads", "relation": "concept" } ] }, "patch": { "operationId": "renameThread_Threads", "x-method": "PATCH", "x-path": "/working-groups/{id}/threads/{tid}", "x-handler": "wg::rename_thread", "tags": [ "Threads" ], "summary": "Rename a thread", "description": "A new title for a user-created `discussion` thread or for one of the\ncaller's own private conversations (`solo_chat` with\n`private_to_entity_id` = the caller — a conversation with Javier\nstarted about a subject). The team chat, DMs and system threads\n(pipeline, reasoning, weaver, notebook, deal) answer 409: their titles\nare set by the feature that owns them. Auth: bearer JWT; a discussion's\ncreator may rename it, anyone else needs `ManageGroup`; a private\nconversation only its owner. The title is trimmed and must be one to\ntwo hundred characters.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "tid", "in": "path", "required": true, "description": "Thread id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The new title, trimmed." } } }, "example": { "title": "Board prep" } } } }, "responses": { "200": { "description": "Thread renamed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "renamed", "id", "title" ], "properties": { "renamed": { "type": "boolean", "description": "Always `true` on success." }, "id": { "type": "string", "format": "uuid", "description": "The renamed thread." }, "title": { "type": "string", "description": "The title as stored." } } }, "example": { "renamed": true, "id": "9ff699ae-4339-4b03-84a0-561702fa0743", "title": "Board prep" } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "409": { "description": "Conflicting state (e.g. step already completed, intent already cancelled, duplicate idempotency key with different body).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_renameThread_Threads", "resource_uri": "yf://agents/threads", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PATCH -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" \\\n -d '{\"title\":\"Board prep\"}' \\\n https://agents.yieldfabric.com/working-groups/{id}/threads/{tid}\n" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx\nr = httpx.patch(\n f\"https://agents.yieldfabric.com/working-groups/{gid}/threads/{tid}\",\n headers={\"Authorization\": f\"Bearer {jwt}\"},\n json={\"title\": \"Board prep\"},\n)\nr.raise_for_status()\n" } ], "x-related": [ { "operationId": "deleteThread_Threads", "relation": "sibling" }, { "operationId": "listThreads_Threads", "relation": "sibling" }, { "guide": "threads", "relation": "concept" } ] }, "delete": { "operationId": "deleteThread_Threads", "x-method": "DELETE", "x-path": "/working-groups/{id}/threads/{tid}", "x-handler": "wg::delete_thread", "tags": [ "Threads" ], "summary": "Delete a thread", "description": "Soft-deletes a user-created `discussion` thread or one of the caller's\nown private conversations (`solo_chat` with `private_to_entity_id` =\nthe caller): the row keeps its messages under `status = 'deleted'` and\nevery reader hides it — it leaves `GET /working-groups/{id}/threads`,\nand its message routes answer 404. The team chat, DMs, other people's\nsolo chats and system threads (pipeline, reasoning, weaver, notebook,\ndeal) are load-bearing for other features and answer 409 (403 for a\nprivate conversation that is not yours). Auth: bearer JWT; a\ndiscussion's creator may delete it, anyone else needs `ManageGroup`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "tid", "in": "path", "required": true, "description": "Thread id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Thread deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted", "id" ], "properties": { "deleted": { "type": "boolean", "description": "Always `true` on success." }, "id": { "type": "string", "format": "uuid", "description": "The deleted thread." } } }, "example": { "deleted": true, "id": "9ff699ae-4339-4b03-84a0-561702fa0743" } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "409": { "description": "Conflicting state (e.g. step already completed, intent already cancelled, duplicate idempotency key with different body).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_deleteThread_Threads", "resource_uri": "yf://agents/threads", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X DELETE -H \"Authorization: Bearer $JWT\" \\\n https://agents.yieldfabric.com/working-groups/{id}/threads/{tid}\n" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx\nr = httpx.delete(\n f\"https://agents.yieldfabric.com/working-groups/{gid}/threads/{tid}\",\n headers={\"Authorization\": f\"Bearer {jwt}\"},\n)\nr.raise_for_status()\n" } ], "x-related": [ { "operationId": "createThread_Threads", "relation": "sibling" }, { "operationId": "listThreads_Threads", "relation": "sibling" }, { "guide": "threads", "relation": "concept" } ] } }, "/working-groups/{id}/threads/{tid}/messages": { "post": { "operationId": "postMessage_Threads", "x-method": "POST", "x-path": "/working-groups/{id}/threads/{tid}/messages", "x-handler": "wg::post_message", "tags": [ "Threads" ], "summary": "Post a human message to a thread", "description": "Persists the caller's message into the thread, broadcasts a\n`NewMessage` event to the group's SSE stream (filtered to the owner\nfor private subthreads), and — for thread types that warrant it —\nspawns background work: agent replies (when `msg_references.recipients`\nnames `agent:` entries or the thread defaults the general\nassistant), Weaver replies for Weaver subthreads, pipeline-flow\ncontrol. `msg_references` is a free-form JSON sidecar; the handler\nuses `recipients` (array of `agent:` strings) to route. Auth:\nbearer JWT; caller must hold `PostMessages`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "tid", "in": "path", "required": true, "description": "Thread id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string" }, "msg_references": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ], "description": "Optional structured references — typically `{ recipients: [...],\n... }` to address specific agents/members.\n" } } }, "examples": { "plain": { "summary": "Simple message", "value": { "content": "How does the new credit limit affect last week's deals?" } }, "mention-agent": { "summary": "Mention a specific agent recipient", "value": { "content": "@risk-reviewer please assess", "msg_references": { "recipients": [ "agent:risk-reviewer" ] } } } } } } }, "responses": { "201": { "description": "Message persisted; agent replies (if any) are dispatched async.", "content": { "application/json": { "schema": { "type": "object", "description": "One message in a group thread.", "required": [ "id", "thread_id", "sender_entity_id", "sender_type", "content", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "thread_id": { "type": "string", "format": "uuid" }, "sender_entity_id": { "type": "string" }, "sender_type": { "type": "string", "enum": [ "human", "agent", "system" ] }, "content": { "type": "string" }, "msg_references": { "description": "Arbitrary JSON value." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_postMessage_Threads", "resource_uri": "yf://agents/threads", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"content\":\"hello team\"}' \\\n https://agents.yieldfabric.com/working-groups/{id}/threads/{tid}/messages\n" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx\nr = httpx.post(\n f\"https://agents.yieldfabric.com/working-groups/{gid}/threads/{tid}/messages\",\n headers={\"Authorization\": f\"Bearer {jwt}\"},\n json={\"content\": \"hello team\"},\n)\nr.raise_for_status()\n" } ], "x-related": [ { "operationId": "getMessages_Threads", "relation": "read-after-write" }, { "operationId": "streamChat_Chat", "relation": "watch" }, { "guide": "threads", "relation": "concept" } ] }, "get": { "operationId": "getMessages_Threads", "x-method": "GET", "x-path": "/working-groups/{id}/threads/{tid}/messages", "x-handler": "wg::get_messages", "tags": [ "Threads" ], "summary": "List messages in a thread (cursor-paginated, newest-first when older requested)", "description": "Returns up to `limit` messages in the thread, paginated by the\n`before` timestamp cursor. Default limit is 200, clamped to 500.\nMessages carry sender (`human` / `agent` / `system`), content, and\nany `references` JSON the poster attached. Useful for back-filling\nhistory before subscribing to the SSE stream. Auth: bearer JWT;\ncaller must hold `ViewThreads`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "tid", "in": "path", "required": true, "description": "Thread id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (default 200, max 500).", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 200 } }, { "name": "before", "in": "query", "required": false, "description": "ISO-8601 cursor — return messages strictly before this timestamp.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Messages in the thread.", "content": { "application/json": { "schema": { "type": "object", "required": [ "messages" ], "properties": { "messages": { "type": "array", "items": { "type": "object", "description": "One message in a group thread.", "required": [ "id", "thread_id", "sender_entity_id", "sender_type", "content", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "thread_id": { "type": "string", "format": "uuid" }, "sender_entity_id": { "type": "string" }, "sender_type": { "type": "string", "enum": [ "human", "agent", "system" ] }, "content": { "type": "string" }, "msg_references": { "description": "Arbitrary JSON value." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getMessages_Threads", "resource_uri": "yf://agents/threads", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" \"https://agents.yieldfabric.com/working-groups/{id}/threads/{tid}/messages?limit=100\"" } ], "x-related": [ { "operationId": "postMessage_Threads", "relation": "sibling" }, { "operationId": "streamChat_Chat", "relation": "watch" }, { "guide": "threads", "relation": "concept" } ] } }, "/working-groups/{id}/threads/{tid}/read": { "post": { "operationId": "markThreadRead_Threads", "x-method": "POST", "x-path": "/working-groups/{id}/threads/{tid}/read", "x-handler": "wg::mark_thread_read", "tags": [ "Threads" ], "summary": "Advance the caller's last-read cursor", "description": "Sets the caller's `last_read_message_id` for this group to the\nsupplied message id. Drives unread-count calculations in\n`listDmConversations` and friends. Also broadcasts a `ReadReceipt`\nevent to the group SSE stream so peers see \"Alice has read up to\nmsg X\". Auth: bearer JWT; caller must hold `ViewThreads`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "tid", "in": "path", "required": true, "description": "Thread id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "last_read_message_id" ], "properties": { "last_read_message_id": { "type": "string", "format": "uuid" } } }, "examples": { "bookmark": { "summary": "Mark up to this message as read", "value": { "last_read_message_id": "5d6b..." } } } } } }, "responses": { "200": { "description": "Cursor advanced.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_markThreadRead_Threads", "resource_uri": "yf://agents/threads", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"last_read_message_id\":\"\"}' \\\n https://agents.yieldfabric.com/working-groups/{id}/threads/{tid}/read\n" } ], "x-related": [ { "operationId": "getMessages_Threads", "relation": "sibling" }, { "guide": "threads", "relation": "concept" } ] } }, "/working-groups/{id}/threads/{tid}/typing": { "post": { "operationId": "typingIndicator_Threads", "x-method": "POST", "x-path": "/working-groups/{id}/threads/{tid}/typing", "x-handler": "wg::typing_indicator", "tags": [ "Threads" ], "summary": "Broadcast that the caller is typing", "description": "Lightweight signal — no DB write, no LLM call. The handler upserts\na 5-second-TTL in-memory entry and broadcasts a `HumanTyping` event\nto the group's SSE subscribers (local + cross-server relay). Used by\nthe chat UI to render the \"Alice is typing…\" pip. Auth: bearer JWT.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "tid", "in": "path", "required": true, "description": "Thread id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Indicator broadcast.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_typingIndicator_Threads", "resource_uri": "yf://agents/threads", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/{id}/threads/{tid}/typing" } ], "x-related": [ { "operationId": "streamChat_Chat", "relation": "watch" }, { "guide": "threads", "relation": "concept" } ] } }, "/working-groups/{id}/threads/{tid}/weaver": { "post": { "operationId": "openWeaverSubthread_Threads", "x-method": "POST", "x-path": "/working-groups/{id}/threads/{tid}/weaver", "x-handler": "wg::open_weaver_subthread", "tags": [ "Threads" ], "summary": "Open (or create) the caller's private Weaver subthread", "description": "Returns the caller's private \"Weaver\" subthread rooted at the named\nsource thread. The Weaver is the per-user agent with persistent\nmemory and a read-only tool grant on the parent thread — it speaks\nprivately back to the owner (no other group member sees Weaver\nreplies). Idempotent: repeated calls return the same subthread.\nLazy-mints the user's Weaver agent on first call so its memory\nnamespace exists before they post. Rooting a Weaver subthread at\nanother subthread is rejected with 400. No request body. Auth:\nbearer JWT; caller must hold `ViewThreads`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "tid", "in": "path", "required": true, "description": "Thread id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Weaver subthread (existing or newly created).", "content": { "application/json": { "schema": { "type": "object", "required": [ "thread" ], "properties": { "thread": { "type": "object", "description": "A conversation thread inside a working group.", "required": [ "id", "group_id", "title", "thread_type", "status", "created_by", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "group_id": { "type": "string", "format": "uuid" }, "parent_thread_id": { "type": [ "string", "null" ], "format": "uuid", "description": "When this is a subthread (e.g. a Weaver private chat), the\nparent's id. `null` for top-level threads.\n" }, "private_to_entity_id": { "type": [ "string", "null" ], "description": "When set, this thread is visible only to the named entity.\nCombined with `parent_thread_id` makes a per-user private\nsubthread.\n" }, "title": { "type": "string" }, "thread_type": { "type": "string", "description": "Discriminator for what the thread is used for.\n", "enum": [ "discussion", "reasoning", "pipeline_main", "pipeline_task", "team_chat", "dm", "weaver", "solo_chat", "notebook_entity", "deal_composer", "deal_shared" ] }, "reference_id": { "type": [ "string", "null" ], "description": "Optional pointer to an external entity (workflow id, frame id,\nWeaver root, etc.). Format depends on `thread_type`.\n" }, "status": { "type": "string", "enum": [ "active", "closed" ] }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_openWeaverSubthread_Threads", "resource_uri": "yf://agents/threads", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/{id}/threads/{tid}/weaver" } ], "x-related": [ { "operationId": "ensureSoloThread_WorkingGroups", "relation": "sibling" }, { "operationId": "postMessage_Threads", "relation": "next-step" }, { "guide": "threads", "relation": "concept" } ] } }, "/working-groups/{id}/topics": { "get": { "operationId": "resolveTopic_WorkingGroups", "x-method": "GET", "x-path": "/working-groups/{id}/topics", "x-handler": "wg::resolve_topic", "tags": [ "Working Groups" ], "summary": "Resolve (or create) the thread topic for a workflow / step", "description": "Looks up (and lazily creates) the discussion thread associated with a\nworkflow or a specific workflow step. With only `workflow_id` set the\nhandler returns the workflow's main topic thread; with both\n`workflow_id` and `step_key` set it returns the per-step thread (so\nper-step chat lands in its own subthread). Both branches are idempotent\n— the underlying store ensures a single thread per `(workflow, [step])`.\nAuth: bearer JWT; caller must hold `ViewThreads`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "workflow_id", "in": "query", "required": true, "description": "Workflow instance id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "step_key", "in": "query", "required": false, "description": "Optional step key. When set, the per-step thread is returned.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The topic thread row.", "content": { "application/json": { "schema": { "type": "object", "required": [ "topic" ], "properties": { "topic": { "type": "object", "description": "A conversation thread inside a working group.", "required": [ "id", "group_id", "title", "thread_type", "status", "created_by", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "group_id": { "type": "string", "format": "uuid" }, "parent_thread_id": { "type": [ "string", "null" ], "format": "uuid", "description": "When this is a subthread (e.g. a Weaver private chat), the\nparent's id. `null` for top-level threads.\n" }, "private_to_entity_id": { "type": [ "string", "null" ], "description": "When set, this thread is visible only to the named entity.\nCombined with `parent_thread_id` makes a per-user private\nsubthread.\n" }, "title": { "type": "string" }, "thread_type": { "type": "string", "description": "Discriminator for what the thread is used for.\n", "enum": [ "discussion", "reasoning", "pipeline_main", "pipeline_task", "team_chat", "dm", "weaver", "solo_chat", "notebook_entity", "deal_composer", "deal_shared" ] }, "reference_id": { "type": [ "string", "null" ], "description": "Optional pointer to an external entity (workflow id, frame id,\nWeaver root, etc.). Format depends on `thread_type`.\n" }, "status": { "type": "string", "enum": [ "active", "closed" ] }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_resolveTopic_WorkingGroups", "resource_uri": "yf://agents/working-groups", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" \\\n \"https://agents.yieldfabric.com/working-groups/{id}/topics?workflow_id=$WID&step_key=approve\"\n" } ], "x-related": [ { "operationId": "streamChat_Chat", "relation": "sibling" }, { "operationId": "getMessages_Threads", "relation": "next-step" }, { "guide": "threads", "relation": "concept" } ] } }, "/working-groups/{id}/workflows": { "post": { "operationId": "createWorkflow_Workflows", "x-method": "POST", "x-path": "/working-groups/{id}/workflows", "x-handler": "wg::create_workflow", "tags": [ "Workflows" ], "summary": "Create a workflow from a DAG of steps", "description": "Provisions a new workflow inside the working group. The body carries a\n`name`, optional `description`, and the `steps` DAG (each\n`CreateStepInput` names a step_key, step_type, config, optional\nassignee, and `depends_on` predecessors). Step types include\n`human_task`, `agent_task`, `approval_gate`, `notification`,\n`reasoning_session`, `conditional`, and `parallel_group`. The handler\nalso auto-adds every step assignee as a group member so the next\n`/execute` doesn't 403, fires SSE notifications to those assignees,\nand returns the persisted `GroupWorkflow` row (status `pending`).\nWhen any step needs an on-chain PipelineGate, the service first verifies\nthe selected-chain account for the caller and every required assignee. A\nmissing account returns the structured `CHAIN_ACCOUNT_REQUIRED` 409 before\nthe workflow, membership rows, notifications, or on-chain registration are\ncreated. Automatic recovery is valid only when the returned entity matches\nthe current actor; another assignee must activate their own account.\nCall `startWorkflow_Workflows` to advance from `pending` → `running`.\nAuth: bearer JWT; caller must hold `ManageWorkflows`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "steps" ], "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "steps": { "type": "array", "items": { "type": "object", "description": "Step definition accepted by createWorkflow / save_pipeline_draft.", "required": [ "step_key", "name", "step_type" ], "properties": { "step_key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "step_type": { "type": "string" }, "step_config": { "description": "Arbitrary JSON value." }, "assignee_type": { "type": [ "string", "null" ], "enum": [ "entity", "role", "group", "originator", null ] }, "assignee_id": { "type": [ "string", "null" ] }, "depends_on": { "type": "array", "items": { "type": "string" } }, "input_bindings": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] } } } } } }, "examples": { "minimal": { "summary": "One human task", "value": { "name": "Document review", "description": "Ask Alice to sign off", "steps": [ { "step_key": "sign", "name": "Sign-off", "step_type": "human_task", "assignee_type": "entity", "assignee_id": "usr_alice", "depends_on": [] } ] } }, "approval-chain": { "summary": "Two-step approval chain", "value": { "name": "Treasury payment", "steps": [ { "step_key": "prepare", "name": "Prepare payment", "step_type": "agent_task", "step_config": { "agent_id": "agent:treasurer" }, "depends_on": [] }, { "step_key": "approve", "name": "CFO approval", "step_type": "approval_gate", "step_config": { "min_approvals": 1 }, "assignee_type": "entity", "assignee_id": "usr_cfo", "depends_on": [ "prepare" ] } ] } } } } } }, "responses": { "201": { "description": "Workflow created in `pending` status.", "content": { "application/json": { "schema": { "type": "object", "description": "A pipeline (DAG of steps) inside a working group.", "required": [ "id", "group_id", "name", "status", "created_by", "metadata", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "group_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "failed", "cancelled" ] }, "created_by": { "type": "string", "description": "entity_id of the creator." }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "result_summary": { "type": [ "string", "null" ] }, "metadata": { "description": "Arbitrary JSON value." }, "external_pipeline_id": { "type": [ "string", "null" ], "description": "Payments/MQ message id from `createPipeline` (not the on-chain\nnumeric id).\n" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "409": { "description": "The effective user or group has no activated smart account on the\nauthenticated session's selected chain. The handler returns this before\nthe gated operation performs a durable write, submits MQ work, or starts\nan on-chain action. Activate the exact returned entity and chain, refresh\nthe same actor's session, then retry the original request once.\n", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "error", "code", "entity_kind", "entity_id", "chain_id", "operation" ], "properties": { "error": { "type": "string", "description": "Human-readable explanation. Branch on `code`, not this text." }, "code": { "type": "string", "const": "CHAIN_ACCOUNT_REQUIRED" }, "entity_kind": { "type": "string", "enum": [ "user", "group" ] }, "entity_id": { "type": "string", "minLength": 1 }, "chain_id": { "type": "string", "minLength": 1, "description": "Chain selected by the authenticated session." }, "operation": { "type": [ "string", "null" ], "description": "Stable operation label that required the account." } } }, "example": { "error": "A smart account must be activated on the selected chain before this operation can continue", "code": "CHAIN_ACCOUNT_REQUIRED", "entity_kind": "user", "entity_id": "usr_alice", "chain_id": "153", "operation": "start_workflow" } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_createWorkflow_Workflows", "resource_uri": "yf://agents/workflows", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Quick task\",\"steps\":[{\"step_key\":\"do\",\"name\":\"Do\",\"step_type\":\"human_task\",\"depends_on\":[]}]}' \\\n https://agents.yieldfabric.com/working-groups/{id}/workflows\n" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx\nr = httpx.post(\n f\"https://agents.yieldfabric.com/working-groups/{gid}/workflows\",\n headers={\"Authorization\": f\"Bearer {jwt}\"},\n json={\n \"name\": \"Quick task\",\n \"steps\": [\n {\n \"step_key\": \"do\",\n \"name\": \"Do\",\n \"step_type\": \"human_task\",\n \"depends_on\": [],\n }\n ],\n },\n)\nr.raise_for_status()\nwf = r.json()\n" } ], "x-related": [ { "operationId": "startWorkflow_Workflows", "relation": "next-step" }, { "operationId": "instantiateTemplate_Workflows", "relation": "alternative" }, { "operationId": "getWorkflow_Workflows", "relation": "read-after-write" }, { "operationId": "streamWorkflow_Workflows", "relation": "watch" }, { "guide": "workflows", "relation": "concept" } ] }, "get": { "operationId": "listWorkflows_Workflows", "x-method": "GET", "x-path": "/working-groups/{id}/workflows", "x-handler": "wg::list_workflows", "tags": [ "Workflows" ], "summary": "List workflows for a working group", "description": "Returns every `GroupWorkflow` row scoped to the group, regardless of\nstatus. The frontend filters running / pending / completed as needed.\nAuth: bearer JWT; caller must hold `ViewWorkflows`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "workflows" ], "properties": { "workflows": { "type": "array", "items": { "type": "object", "description": "A pipeline (DAG of steps) inside a working group.", "required": [ "id", "group_id", "name", "status", "created_by", "metadata", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "group_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "failed", "cancelled" ] }, "created_by": { "type": "string", "description": "entity_id of the creator." }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "result_summary": { "type": [ "string", "null" ] }, "metadata": { "description": "Arbitrary JSON value." }, "external_pipeline_id": { "type": [ "string", "null" ], "description": "Payments/MQ message id from `createPipeline` (not the on-chain\nnumeric id).\n" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_listWorkflows_Workflows", "resource_uri": "yf://agents/workflows", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/{id}/workflows" } ], "x-related": [ { "operationId": "getWorkflow_Workflows", "relation": "child" }, { "operationId": "createWorkflow_Workflows", "relation": "sibling" }, { "guide": "workflows", "relation": "concept" } ] } }, "/working-groups/{id}/workflows/from-template": { "post": { "operationId": "instantiateTemplate_Workflows", "x-method": "POST", "x-path": "/working-groups/{id}/workflows/from-template", "x-handler": "wg::instantiate_template", "tags": [ "Workflows" ], "summary": "Create a workflow from a saved template", "description": "Instantiates a `WorkflowTemplate` (referenced by `template_name`)\ninto a concrete workflow in this group. `variables` carries any\ntemplate-time substitutions. `role_assignments` maps abstract role\nnames (e.g. `\"originator\"`, `\"counterparty\"`) to real entity ids;\n`wallet_assignments` maps those entity ids to on-chain wallet\naddresses (used to register signer slots on the PipelineGate).\nAny assignees not yet group members are auto-added with their\nwallet recorded. Returns the persisted `GroupWorkflow` row (status\n`pending`); call `startWorkflow_Workflows` to activate. Auth: bearer\nJWT; caller must hold `ManageWorkflows`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "template_name" ], "properties": { "template_name": { "type": "string" }, "variables": { "description": "Arbitrary JSON value." }, "role_assignments": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Maps template role names to real entity IDs." }, "wallet_assignments": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Maps entity IDs to wallet addresses for on-chain pipeline signer\nregistration.\n" } } }, "examples": { "bilateral-payment": { "summary": "Bilateral payment template with two-party roles", "value": { "template_name": "bilateral_payment", "variables": { "amount": 100, "token": "USDC" }, "role_assignments": { "originator": "usr_alice", "counterparty": "usr_bob" }, "wallet_assignments": { "usr_alice": "0xaaa...", "usr_bob": "0xbbb..." } } } } } } }, "responses": { "201": { "description": "Workflow created.", "content": { "application/json": { "schema": { "type": "object", "description": "A pipeline (DAG of steps) inside a working group.", "required": [ "id", "group_id", "name", "status", "created_by", "metadata", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "group_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "failed", "cancelled" ] }, "created_by": { "type": "string", "description": "entity_id of the creator." }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "result_summary": { "type": [ "string", "null" ] }, "metadata": { "description": "Arbitrary JSON value." }, "external_pipeline_id": { "type": [ "string", "null" ], "description": "Payments/MQ message id from `createPipeline` (not the on-chain\nnumeric id).\n" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_instantiateTemplate_Workflows", "resource_uri": "yf://agents/workflows", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"template_name\":\"bilateral_payment\",\"variables\":{},\"role_assignments\":{}}' \\\n https://agents.yieldfabric.com/working-groups/{id}/workflows/from-template\n" } ], "x-related": [ { "operationId": "createWorkflow_Workflows", "relation": "alternative" }, { "operationId": "listTemplates_WorkflowTemplates", "relation": "prerequisite" }, { "operationId": "startWorkflow_Workflows", "relation": "next-step" }, { "guide": "workflows", "relation": "concept" } ] } }, "/working-groups/{id}/workflows/{wid}": { "get": { "operationId": "getWorkflow_Workflows", "x-method": "GET", "x-path": "/working-groups/{id}/workflows/{wid}", "x-handler": "wg::get_workflow", "tags": [ "Workflows" ], "summary": "Fetch a workflow plus its current step rows", "description": "Returns the workflow row and every `WorkflowStep` row owned by it.\nStep rows carry their current status (`pending`, `ready`,\n`in_progress`, `completed`, `failed`, `skipped`, `cancelled`),\nresolved `step_config`, assignee, predecessor list, result JSON, and\n`external_message_id` (set whenever a step has dispatched an on-chain\noperation). Use the SSE `streamWorkflow_Workflows` endpoint to follow\nstatus changes in real time. Auth: bearer JWT; authorization uses the\neffective context (`acting_as` for a delegation, otherwise `sub`) and that\nentity must hold `ViewWorkflows`. This matches the execution endpoint, so a\ngroup-delegated caller can poll the exact step it just started.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "wid", "in": "path", "required": true, "description": "Workflow instance id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Workflow and step rows.", "content": { "application/json": { "schema": { "type": "object", "required": [ "workflow", "steps" ], "properties": { "workflow": { "type": "object", "description": "A pipeline (DAG of steps) inside a working group.", "required": [ "id", "group_id", "name", "status", "created_by", "metadata", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "group_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "failed", "cancelled" ] }, "created_by": { "type": "string", "description": "entity_id of the creator." }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "result_summary": { "type": [ "string", "null" ] }, "metadata": { "description": "Arbitrary JSON value." }, "external_pipeline_id": { "type": [ "string", "null" ], "description": "Payments/MQ message id from `createPipeline` (not the on-chain\nnumeric id).\n" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 datetime (UTC)." } } }, "steps": { "type": "array", "items": { "type": "object", "description": "One step in a workflow DAG.", "required": [ "id", "workflow_id", "step_key", "name", "step_type", "step_config", "depends_on", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "workflow_id": { "type": "string", "format": "uuid" }, "step_key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "step_type": { "type": "string", "description": "One of the primitive task types — `agent_task`, `human_task`,\n`approval_gate`, `notification`, `conditional`, `parallel_group`,\n`reasoning_session`, `wait`, `wait_for_state`, `oracle_read`,\n`balance_read`.\n" }, "step_config": { "description": "Arbitrary JSON value." }, "assignee_type": { "type": [ "string", "null" ], "enum": [ "entity", "role", "group", "originator", null ] }, "assignee_id": { "type": [ "string", "null" ] }, "depends_on": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "pending", "ready", "in_progress", "completed", "failed", "skipped" ] }, "result": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ] }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_message_id": { "type": [ "string", "null" ] }, "input_bindings": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ], "description": "Runtime input bindings: maps consumer input field →\n(source_step_key, source_output_field). When the step transitions\nto `ready`, values are resolved from predecessor results and\ninjected into `step_config.parameters`.\n" } } } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_getWorkflow_Workflows", "resource_uri": "yf://agents/workflows", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/{id}/workflows/{wid}" } ], "x-related": [ { "operationId": "streamWorkflow_Workflows", "relation": "watch" }, { "operationId": "startWorkflow_Workflows", "relation": "sibling" }, { "guide": "workflows", "relation": "concept" } ] } }, "/working-groups/{id}/workflows/{wid}/start": { "post": { "operationId": "startWorkflow_Workflows", "x-method": "POST", "x-path": "/working-groups/{id}/workflows/{wid}/start", "x-handler": "wg::start_workflow", "tags": [ "Workflows" ], "summary": "Activate a pending workflow", "description": "Transitions a `pending` workflow into `running` and kicks off the\nfinalisation pipeline: promote `originator` assignees to the caller,\nensure assignees are group members with wallets recorded, register\nthe on-chain PipelineGate (when a bearer JWT is present), stamp\noriginator metadata, and spawn the auto-execute + chat-bridge\nbackground tasks. No request body. The first deps-empty steps will\ntransition to `ready` and become claimable by their assignees.\nFor a gate-backed workflow, a read-only preflight verifies the caller and\nevery gate signer on the JWT-selected chain before the workflow leaves\n`pending` or any membership/configuration write occurs. A missing account\nreturns `CHAIN_ACCOUNT_REQUIRED`; activate that exact entity and chain,\nrefresh the same actor's JWT, then retry this request once. If another\nsigner is named, that signer must activate their own account first.\nAuth: bearer JWT; caller must hold `StartWorkflow`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "wid", "in": "path", "required": true, "description": "Workflow instance id (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Workflow started.", "content": { "application/json": { "schema": { "type": "object", "required": [ "started" ], "properties": { "started": { "type": "boolean" } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "409": { "description": "The effective user or group has no activated smart account on the\nauthenticated session's selected chain. The handler returns this before\nthe gated operation performs a durable write, submits MQ work, or starts\nan on-chain action. Activate the exact returned entity and chain, refresh\nthe same actor's session, then retry the original request once.\n", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "error", "code", "entity_kind", "entity_id", "chain_id", "operation" ], "properties": { "error": { "type": "string", "description": "Human-readable explanation. Branch on `code`, not this text." }, "code": { "type": "string", "const": "CHAIN_ACCOUNT_REQUIRED" }, "entity_kind": { "type": "string", "enum": [ "user", "group" ] }, "entity_id": { "type": "string", "minLength": 1 }, "chain_id": { "type": "string", "minLength": 1, "description": "Chain selected by the authenticated session." }, "operation": { "type": [ "string", "null" ], "description": "Stable operation label that required the account." } } }, "example": { "error": "A smart account must be activated on the selected chain before this operation can continue", "code": "CHAIN_ACCOUNT_REQUIRED", "entity_kind": "user", "entity_id": "usr_alice", "chain_id": "153", "operation": "start_workflow" } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_startWorkflow_Workflows", "resource_uri": "yf://agents/workflows", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/{id}/workflows/{wid}/start" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx\nr = httpx.post(\n f\"https://agents.yieldfabric.com/working-groups/{gid}/workflows/{wid}/start\",\n headers={\"Authorization\": f\"Bearer {jwt}\"},\n)\nr.raise_for_status()\n" } ], "x-related": [ { "operationId": "createWorkflow_Workflows", "relation": "prerequisite" }, { "operationId": "streamWorkflow_Workflows", "relation": "watch" }, { "operationId": "executeStep_Workflows", "relation": "next-step" }, { "guide": "workflows", "relation": "concept" } ] } }, "/working-groups/{id}/workflows/{wid}/steps/{step_key}/approve": { "post": { "operationId": "approveStep_Workflows", "x-method": "POST", "x-path": "/working-groups/{id}/workflows/{wid}/steps/{step_key}/approve", "x-handler": "wg::approve_step", "tags": [ "Workflows" ], "summary": "Approve an approval-gate step", "description": "Records an approval on an `approval_gate` step. The handler supports\ntwo flavours: a \"standard\" approval (off-chain, optional on-chain\nsignStep when the gate has an `onchain_step_index`) and an\n\"onchain_sign\" approval mode used by materialized multi-sig auth\nsteps. In on-chain mode, the optional `on_chain_sign_message_id`\nshort-circuits the backend signStep dispatch — the frontend has\nalready submitted the signature against the payments service.\nReturns `gate_complete: true` once the configured `min_approvals`\nthreshold has been reached. Auth: bearer JWT (REQUIRED); caller\nmust hold `ApproveAssignedGate` AND be a named approver, the\nassignee, or a group admin/owner.\n\nApprovals that sign on chain, or whose step already has a materialized\nPipelineGate index, preflight the selected-chain account before recording\napproval or audit state. Purely off-chain approvals remain walletless.\nA missing required account returns the flat `CHAIN_ACCOUNT_REQUIRED` 409;\nactivate the returned actor and chain, refresh, and retry once.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "wid", "in": "path", "required": true, "description": "Workflow instance id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "step_key", "in": "path", "required": true, "description": "Workflow-step key (string from the workflow definition).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": [ "string", "null" ] }, "on_chain_sign_message_id": { "type": [ "string", "null" ], "description": "Payments MQ / GraphQL message id from `signStep`, stored on the\nstep for audit/UI. When omitted on an `onchain_sign` gate, the\nbackend issues `signStep` itself.\n" } } }, "examples": { "plain": { "summary": "Plain approval with no comment", "value": {} }, "with-comment": { "summary": "Approval with comment + frontend-signed mid", "value": { "comment": "looks good", "on_chain_sign_message_id": "msg_5fae..." } } } } } }, "responses": { "200": { "description": "Approval recorded.", "content": { "application/json": { "schema": { "type": "object", "description": "Approval outcome. `gate_complete` flips true when the approval\nquorum was reached. Extra signer/audit fields land here for\n`onchain_sign` gates — keep `additionalProperties` open.\n", "additionalProperties": true, "required": [ "approved", "gate_complete" ], "properties": { "approved": { "type": "boolean" }, "gate_complete": { "type": "boolean" }, "on_chain_sign_message_id": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "409": { "description": "The effective user or group has no activated smart account on the\nauthenticated session's selected chain. The handler returns this before\nthe gated operation performs a durable write, submits MQ work, or starts\nan on-chain action. Activate the exact returned entity and chain, refresh\nthe same actor's session, then retry the original request once.\n", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "error", "code", "entity_kind", "entity_id", "chain_id", "operation" ], "properties": { "error": { "type": "string", "description": "Human-readable explanation. Branch on `code`, not this text." }, "code": { "type": "string", "const": "CHAIN_ACCOUNT_REQUIRED" }, "entity_kind": { "type": "string", "enum": [ "user", "group" ] }, "entity_id": { "type": "string", "minLength": 1 }, "chain_id": { "type": "string", "minLength": 1, "description": "Chain selected by the authenticated session." }, "operation": { "type": [ "string", "null" ], "description": "Stable operation label that required the account." } } }, "example": { "error": "A smart account must be activated on the selected chain before this operation can continue", "code": "CHAIN_ACCOUNT_REQUIRED", "entity_kind": "user", "entity_id": "usr_alice", "chain_id": "153", "operation": "start_workflow" } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_approveStep_Workflows", "resource_uri": "yf://agents/workflows", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" -d '{}' \\\n https://agents.yieldfabric.com/working-groups/{id}/workflows/{wid}/steps/{step_key}/approve\n" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx\nr = httpx.post(\n f\"https://agents.yieldfabric.com/working-groups/{gid}/workflows/{wid}/steps/{step_key}/approve\",\n headers={\"Authorization\": f\"Bearer {jwt}\"},\n json={\"comment\": \"looks good\"},\n)\nr.raise_for_status()\n" } ], "x-related": [ { "operationId": "rejectStep_Workflows", "relation": "sibling" }, { "operationId": "executeStep_Workflows", "relation": "sibling" }, { "guide": "workflows", "relation": "concept" } ] } }, "/working-groups/{id}/workflows/{wid}/steps/{step_key}/complete": { "post": { "operationId": "completeStep_Workflows", "x-method": "POST", "x-path": "/working-groups/{id}/workflows/{wid}/steps/{step_key}/complete", "x-handler": "wg::complete_step", "tags": [ "Workflows" ], "summary": "Mark a human / agent / notification step complete", "description": "Marks a step as `completed` and persists an optional `result` JSON.\nThe endpoint accepts `human_task`, `agent_task`, and `notification`\nsteps; other step types must use the type-appropriate endpoint\n(`approve`, `execute`, etc.). Before the off-chain status flips, the\nhandler dispatches a `signStep` to the PipelineGate (or returns\n\"Already signed\" idempotently). On success, downstream steps with\nsatisfied deps are advanced and the auto-executor is kicked.\nFor a gate-backed step, a read-only selected-chain account preflight runs\nbefore `signStep` or the off-chain completion write. A missing account\nreturns the flat `CHAIN_ACCOUNT_REQUIRED` 409; activate the exact returned\nentity/chain, refresh the same actor's JWT, and retry once.\nAuth: bearer JWT; caller must hold `ExecuteAssignedHumanTask` AND\nbe the step's assignee or a group admin/owner.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "wid", "in": "path", "required": true, "description": "Workflow instance id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "step_key", "in": "path", "required": true, "description": "Workflow-step key (string from the workflow definition).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "oneOf": [ { "description": "Arbitrary JSON value." }, { "type": "null" } ], "description": "Optional structured result payload for the completed step." } } }, "examples": { "no-result": { "summary": "Complete with no result body", "value": {} }, "with-result": { "summary": "Complete and attach a result JSON", "value": { "result": { "decision": "approved", "note": "signed off via UI" } } } } } } }, "responses": { "200": { "description": "Step completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "action_id", "completed" ], "properties": { "action_id": { "type": "string", "format": "uuid" }, "completed": { "type": "boolean" } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "409": { "description": "The effective user or group has no activated smart account on the\nauthenticated session's selected chain. The handler returns this before\nthe gated operation performs a durable write, submits MQ work, or starts\nan on-chain action. Activate the exact returned entity and chain, refresh\nthe same actor's session, then retry the original request once.\n", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "error", "code", "entity_kind", "entity_id", "chain_id", "operation" ], "properties": { "error": { "type": "string", "description": "Human-readable explanation. Branch on `code`, not this text." }, "code": { "type": "string", "const": "CHAIN_ACCOUNT_REQUIRED" }, "entity_kind": { "type": "string", "enum": [ "user", "group" ] }, "entity_id": { "type": "string", "minLength": 1 }, "chain_id": { "type": "string", "minLength": 1, "description": "Chain selected by the authenticated session." }, "operation": { "type": [ "string", "null" ], "description": "Stable operation label that required the account." } } }, "example": { "error": "A smart account must be activated on the selected chain before this operation can continue", "code": "CHAIN_ACCOUNT_REQUIRED", "entity_kind": "user", "entity_id": "usr_alice", "chain_id": "153", "operation": "start_workflow" } } } }, "502": { "description": "On-chain signStep call failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_completeStep_Workflows", "resource_uri": "yf://agents/workflows", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" -d '{}' \\\n https://agents.yieldfabric.com/working-groups/{id}/workflows/{wid}/steps/{step_key}/complete\n" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx\nr = httpx.post(\n f\"https://agents.yieldfabric.com/working-groups/{gid}/workflows/{wid}/steps/{step_key}/complete\",\n headers={\"Authorization\": f\"Bearer {jwt}\"},\n json={\"result\": {\"decision\": \"approved\"}},\n)\nr.raise_for_status()\n" } ], "x-related": [ { "operationId": "failStep_Workflows", "relation": "sibling" }, { "operationId": "executeStep_Workflows", "relation": "sibling" }, { "operationId": "approveStep_Workflows", "relation": "sibling" }, { "guide": "workflows", "relation": "concept" } ] } }, "/working-groups/{id}/workflows/{wid}/steps/{step_key}/execute": { "post": { "operationId": "executeStep_Workflows", "x-method": "POST", "x-path": "/working-groups/{id}/workflows/{wid}/steps/{step_key}/execute", "x-handler": "wg::execute_step", "tags": [ "Workflows" ], "summary": "Execute a payment / signature step (sign-then-op flow)", "description": "Executes a step whose `step_config.execution_target = payment`. The\nhandler runs a synchronous two-phase orchestration: phase 1 submits\n`signStep` to the PipelineGate and blocks on `messageOutcome` until\nthe gate's `StepSigned`/`StepCompleted` events land on chain; phase 2\ndispatches the actual operation (auth REST for `createWallet`,\nGraphQL gateway otherwise) and waits for its on-chain ack before\nreturning. Multi-sig steps use a relaxed status check so each listed\nsigner's `/execute` can proceed concurrently; the gate enforces\nno-double-signing. Returns the message id(s) and the final\non-chain transaction hash. Auth: bearer JWT (REQUIRED — phase 1 needs\nit for the payments service); caller must hold\n`ExecuteAssignedHumanTask` AND be the step's assignee or a group\nadmin/owner. No request body — the operation parameters are read from\nthe step's compiled `step_config`.\n\nThe selected-chain account preflight runs before binding re-resolution,\n`signStep`, MQ submission, or any workflow mutation. A missing account\nreturns the flat `CHAIN_ACCOUNT_REQUIRED` 409. Activate the exact returned\nactor and chain, refresh that same session, and retry this request once.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "wid", "in": "path", "required": true, "description": "Workflow instance id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "step_key", "in": "path", "required": true, "description": "Workflow-step key (string from the workflow definition).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation submitted and confirmed on chain.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Per-primitive execution result — shape varies by step type (payment\ndispatch / agent_task / upload). Kept open because each primitive\nlayers its own bookkeeping fields onto the response. `message_id`\nis always present when the runtime dispatched an external operation.\n", "properties": { "message_id": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "409": { "description": "The effective user or group has no activated smart account on the\nauthenticated session's selected chain. The handler returns this before\nthe gated operation performs a durable write, submits MQ work, or starts\nan on-chain action. Activate the exact returned entity and chain, refresh\nthe same actor's session, then retry the original request once.\n", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "error", "code", "entity_kind", "entity_id", "chain_id", "operation" ], "properties": { "error": { "type": "string", "description": "Human-readable explanation. Branch on `code`, not this text." }, "code": { "type": "string", "const": "CHAIN_ACCOUNT_REQUIRED" }, "entity_kind": { "type": "string", "enum": [ "user", "group" ] }, "entity_id": { "type": "string", "minLength": 1 }, "chain_id": { "type": "string", "minLength": 1, "description": "Chain selected by the authenticated session." }, "operation": { "type": [ "string", "null" ], "description": "Stable operation label that required the account." } } }, "example": { "error": "A smart account must be activated on the selected chain before this operation can continue", "code": "CHAIN_ACCOUNT_REQUIRED", "entity_kind": "user", "entity_id": "usr_alice", "chain_id": "153", "operation": "start_workflow" } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_executeStep_Workflows", "resource_uri": "yf://agents/workflows", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/{id}/workflows/{wid}/steps/{step_key}/execute" }, { "lang": "python", "label": "Python (httpx)", "source": "import httpx\nr = httpx.post(\n f\"https://agents.yieldfabric.com/working-groups/{gid}/workflows/{wid}/steps/{step_key}/execute\",\n headers={\"Authorization\": f\"Bearer {jwt}\"},\n timeout=180.0,\n)\nr.raise_for_status()\noutcome = r.json() # contains submitted/completed/transaction_hash\n" } ], "x-related": [ { "operationId": "completeStep_Workflows", "relation": "sibling" }, { "operationId": "approveStep_Workflows", "relation": "sibling" }, { "operationId": "signChildPipeline_Workflows", "relation": "sibling" }, { "guide": "workflows", "relation": "concept" } ] } }, "/working-groups/{id}/workflows/{wid}/steps/{step_key}/fail": { "post": { "operationId": "failStep_Workflows", "x-method": "POST", "x-path": "/working-groups/{id}/workflows/{wid}/steps/{step_key}/fail", "x-handler": "wg::fail_step", "tags": [ "Workflows" ], "summary": "Fail a workflow step with a reason", "description": "Marks a step `failed` and halts the workflow at that step — downstream\nsteps never advance. Sibling of `completeStep_Workflows` for the\ncancellation path: DMS's `cancel_party_action` uses this so cancelling\nan inbox row transitions the underlying workflow step (otherwise the\nworkflow would orphan with the step stuck in its prior status). The\nreason is persisted in the step row and broadcast to subscribers via\nthe SSE stream. Auth: bearer JWT; caller must hold\n`ExecuteAssignedHumanTask` AND be the step's assignee or a\ngroup admin/owner.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "wid", "in": "path", "required": true, "description": "Workflow instance id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "step_key", "in": "path", "required": true, "description": "Workflow-step key (string from the workflow definition).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string" } } }, "examples": { "cancel": { "summary": "Cancel because counterparty declined", "value": { "reason": "Counterparty declined the trade." } } } } } }, "responses": { "200": { "description": "Step failed; workflow halted at this step.", "content": { "application/json": { "schema": { "type": "object", "required": [ "failed" ], "properties": { "failed": { "type": "boolean" } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "409": { "description": "Conflicting state (e.g. step already completed, intent already cancelled, duplicate idempotency key with different body).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_failStep_Workflows", "resource_uri": "yf://agents/workflows", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"reason\":\"Counterparty declined\"}' \\\n https://agents.yieldfabric.com/working-groups/{id}/workflows/{wid}/steps/{step_key}/fail\n" } ], "x-related": [ { "operationId": "completeStep_Workflows", "relation": "sibling" }, { "operationId": "rejectStep_Workflows", "relation": "sibling" }, { "guide": "workflows", "relation": "concept" } ] } }, "/working-groups/{id}/workflows/{wid}/steps/{step_key}/reassign": { "post": { "operationId": "reassignStep_Workflows", "x-method": "POST", "x-path": "/working-groups/{id}/workflows/{wid}/steps/{step_key}/reassign", "x-handler": "wg::reassign_step", "tags": [ "Workflows" ], "summary": "Reassign a human-task step to another entity", "description": "Reassigns a `human_task` step to a different entity. The new assignee\nis auto-added as a group member if not already present, an audit row\nis written, and the change is recorded in\n`working_group_step_actions` with the previous assignee. Only\n`human_task` step types are accepted; approval-gate / payment-step\nreassignment uses different flows. Auth: bearer JWT; caller must\nhold `ReassignTask`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "wid", "in": "path", "required": true, "description": "Workflow instance id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "step_key", "in": "path", "required": true, "description": "Workflow-step key (string from the workflow definition).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "assignee_entity_id" ], "properties": { "assignee_entity_id": { "type": "string" } } }, "examples": { "reassign": { "summary": "Reassign to a different user", "value": { "assignee_entity_id": "usr_charlie" } } } } } }, "responses": { "200": { "description": "Step reassigned.", "content": { "application/json": { "schema": { "type": "object", "required": [ "reassigned", "step_key", "assignee_entity_id" ], "properties": { "reassigned": { "type": "boolean" }, "step_key": { "type": "string" }, "assignee_entity_id": { "type": "string" } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_reassignStep_Workflows", "resource_uri": "yf://agents/workflows", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"assignee_entity_id\":\"usr_charlie\"}' \\\n https://agents.yieldfabric.com/working-groups/{id}/workflows/{wid}/steps/{step_key}/reassign\n" } ], "x-related": [ { "operationId": "removeMember_Members", "relation": "precondition-for" }, { "operationId": "getWorkflow_Workflows", "relation": "sibling" }, { "guide": "workflows", "relation": "concept" } ] } }, "/working-groups/{id}/workflows/{wid}/steps/{step_key}/register-child": { "post": { "operationId": "registerChildRequirement_Workflows", "x-method": "POST", "x-path": "/working-groups/{id}/workflows/{wid}/steps/{step_key}/register-child", "x-handler": "wg::register_child_requirement", "tags": [ "Workflows" ], "summary": "Register a child pipeline as a requirement on the sender's account", "description": "Once a child pipeline has been confirmed on chain (its\n`child_pipeline_id` is set on the step's `result`), the account owner\ncalls this with a live JWT to register the child pipeline as a\nrequirement on their ConfidentialAccount. Idempotent — if the child\npipeline has already been registered (`child_pipeline_registered =\ntrue` in the step result), the handler returns success without a\nsecond on-chain submission. The step must be in `in_progress`.\nNo request body. Auth: bearer JWT (REQUIRED); caller must hold\n`ExecuteAssignedHumanTask`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "wid", "in": "path", "required": true, "description": "Workflow instance id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "step_key", "in": "path", "required": true, "description": "Workflow-step key (string from the workflow definition).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "No request body required. The handler reads `child_pipeline_id`\nfrom the parent step's `result` JSON and forwards a register message\nto payments. The body slot is reserved for future per-call overrides\n(account address, execution metadata) — kept open for forward\ncompatibility.\n", "additionalProperties": true }, "examples": { "empty": { "summary": "Empty body — no fields are read", "value": {} } } } } }, "responses": { "200": { "description": "Child pipeline registered (or already registered).", "content": { "application/json": { "schema": { "type": "object", "required": [ "registered" ], "properties": { "registered": { "type": "boolean" }, "child_pipeline_id": { "type": [ "integer", "null" ] }, "message_id": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "409": { "description": "Conflicting state (e.g. step already completed, intent already cancelled, duplicate idempotency key with different body).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_registerChildRequirement_Workflows", "resource_uri": "yf://agents/workflows", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/{id}/workflows/{wid}/steps/{step_key}/register-child" } ], "x-related": [ { "operationId": "signChildPipeline_Workflows", "relation": "next-step" }, { "operationId": "executeStep_Workflows", "relation": "sibling" }, { "guide": "workflows", "relation": "concept" } ] } }, "/working-groups/{id}/workflows/{wid}/steps/{step_key}/reject": { "post": { "operationId": "rejectStep_Workflows", "x-method": "POST", "x-path": "/working-groups/{id}/workflows/{wid}/steps/{step_key}/reject", "x-handler": "wg::reject_step", "tags": [ "Workflows" ], "summary": "Reject an approval-gate step", "description": "Marks an `approval_gate` step rejected and halts the workflow at that\ngate. The reason is persisted into `working_group_step_actions` and an\naudit row is written. Auth: bearer JWT; caller must hold\n`RejectAssignedGate` AND be a named approver, the assignee, or a\ngroup admin/owner.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "wid", "in": "path", "required": true, "description": "Workflow instance id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "step_key", "in": "path", "required": true, "description": "Workflow-step key (string from the workflow definition).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string" } } }, "examples": { "decline": { "summary": "Decline with reason", "value": { "reason": "Counterparty risk too high." } } } } } }, "responses": { "200": { "description": "Step rejected.", "content": { "application/json": { "schema": { "type": "object", "required": [ "rejected" ], "properties": { "rejected": { "type": "boolean" } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "409": { "description": "Conflicting state (e.g. step already completed, intent already cancelled, duplicate idempotency key with different body).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_rejectStep_Workflows", "resource_uri": "yf://agents/workflows", "idempotent": false }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"reason\":\"counterparty risk\"}' \\\n https://agents.yieldfabric.com/working-groups/{id}/workflows/{wid}/steps/{step_key}/reject\n" } ], "x-related": [ { "operationId": "approveStep_Workflows", "relation": "sibling" }, { "operationId": "failStep_Workflows", "relation": "sibling" }, { "guide": "workflows", "relation": "concept" } ] } }, "/working-groups/{id}/workflows/{wid}/steps/{step_key}/sign-child": { "post": { "operationId": "signChildPipeline_Workflows", "x-method": "POST", "x-path": "/working-groups/{id}/workflows/{wid}/steps/{step_key}/sign-child", "x-handler": "wg::sign_child_pipeline", "tags": [ "Workflows" ], "summary": "Sign a step within a child pipeline", "description": "Issues a `signStep` for a particular `step_index` inside the child\npipeline anchored on the current step. Verifies that the caller is in\n`child_pipeline_signer_entity_ids` (or is a group admin/owner) and\nresolves their on-chain wallet from the matching position in\n`child_pipeline_signers`. The handler is idempotent: existing\n`confirmed` / `pending` signatures short-circuit with success. The\nstep must be `in_progress`. Auth: bearer JWT (REQUIRED); caller must\nhold `ExecuteAssignedHumanTask`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "wid", "in": "path", "required": true, "description": "Workflow instance id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "step_key", "in": "path", "required": true, "description": "Workflow-step key (string from the workflow definition).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "step_index" ], "properties": { "step_index": { "type": "integer", "description": "On-chain step index (within the child pipeline) to sign." } } }, "examples": { "sign-step-0": { "summary": "Sign the first step in the child pipeline", "value": { "step_index": 0 } } } } } }, "responses": { "200": { "description": "Sign queued (or already-signed/-pending).", "content": { "application/json": { "schema": { "type": "object", "required": [ "signed" ], "properties": { "signed": { "type": "boolean" }, "message_id": { "type": [ "string", "null" ] }, "child_pipeline_id": { "type": [ "integer", "null" ] }, "already_confirmed": { "type": [ "boolean", "null" ] }, "already_pending": { "type": [ "boolean", "null" ] } } } } } }, "400": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "409": { "description": "Conflicting state (e.g. step already completed, intent already cancelled, duplicate idempotency key with different body).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-mcp": { "tool_name": "yieldfabric_agents_signChildPipeline_Workflows", "resource_uri": "yf://agents/workflows", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST -H \"Authorization: Bearer $JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"step_index\":0}' \\\n https://agents.yieldfabric.com/working-groups/{id}/workflows/{wid}/steps/{step_key}/sign-child\n" } ], "x-related": [ { "operationId": "registerChildRequirement_Workflows", "relation": "prerequisite" }, { "operationId": "executeStep_Workflows", "relation": "sibling" }, { "guide": "workflows", "relation": "concept" } ] } }, "/working-groups/{id}/workflows/{wid}/stream": { "get": { "operationId": "streamWorkflow_Workflows", "x-method": "GET", "x-path": "/working-groups/{id}/workflows/{wid}/stream", "x-handler": "wg::stream_workflow", "tags": [ "Workflows" ], "summary": "SSE stream of workflow step events", "description": "Opens a Server-Sent Events stream of workflow events. The first frame\nis a `Snapshot` carrying the current `workflow` row and `steps` array.\nSubsequent frames are typed `WorkflowEvent` variants (see\n`x-event-types`) — step transitions, approval tally updates, workflow\ncompletion / failure. Browser clients can authenticate by passing the\nJWT as `?access_token=` since EventSource cannot send headers.\nThere is no resume cursor — on reconnect, the client receives a\nfresh `Snapshot` and continues live; events that fired during the\ndisconnect are not replayed. Auth: bearer JWT (via header) OR\n`access_token` query (for EventSource).\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "wid", "in": "path", "required": true, "description": "Workflow instance id (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "access_token", "in": "query", "required": false, "description": "JWT — used by browser EventSource clients that cannot send `Authorization`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Server-Sent Events stream. Each event is framed as `event: \\ndata: \\n\\n`\n(chat + workflow streams) or `data: {\"type\":\"\", ...}\\n\\n` (pipeline stream\nwhere the typed enum is serialized directly per `#[serde(tag = \"type\")]`).\nSee the operation's `x-event-types` array for the full enumeration of event\nvariants and their data schemas. There is no `?last_message_ts=` resume\ncursor on chat/workflow streams today; the pipeline stream replays its in-memory\nlog on every (re)subscribe.\n", "content": { "text/event-stream": { "schema": { "type": "object", "description": "Each SSE event has an `event` name (the wire-level `event:` line) and a\n`data` JSON payload (the wire-level `data:` line, JSON-decoded). The exact\nschemas for each event variant are documented in the operation's\n`x-event-types` extension.\n", "required": [ "event", "data" ], "properties": { "event": { "type": "string", "description": "Event name from the operation's `x-event-types` enumeration." }, "data": { "description": "JSON payload. Shape depends on `event` — see `x-event-types`." }, "id": { "type": [ "string", "null" ], "description": "Optional SSE event id (used for resume cursors)." } } } } } }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "404": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } } }, "x-event-types": [ { "name": "Snapshot", "schema": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "Snapshot" ] }, "workflow": { "description": "GroupWorkflow row" }, "steps": { "type": "array", "items": { "description": "WorkflowStep row" } } } } }, { "name": "StepReady", "schema": { "type": "object", "required": [ "type", "workflow_id", "step_key", "step_name", "step_type" ], "properties": { "type": { "type": "string", "enum": [ "StepReady" ] }, "workflow_id": { "type": "string", "format": "uuid" }, "step_key": { "type": "string" }, "step_name": { "type": "string" }, "step_type": { "type": "string" }, "assignee": { "type": [ "string", "null" ] } } } }, { "name": "StepStarted", "schema": { "type": "object", "required": [ "type", "workflow_id", "step_key", "step_name", "executor" ], "properties": { "type": { "type": "string", "enum": [ "StepStarted" ] }, "workflow_id": { "type": "string", "format": "uuid" }, "step_key": { "type": "string" }, "step_name": { "type": "string" }, "executor": { "type": "string" } } } }, { "name": "StepCompleted", "schema": { "type": "object", "required": [ "type", "workflow_id", "step_key", "step_name" ], "properties": { "type": { "type": "string", "enum": [ "StepCompleted" ] }, "workflow_id": { "type": "string", "format": "uuid" }, "step_key": { "type": "string" }, "step_name": { "type": "string" }, "result": {} } } }, { "name": "ApprovalReceived", "schema": { "type": "object", "required": [ "type", "workflow_id", "step_key", "by", "current", "required" ], "properties": { "type": { "type": "string", "enum": [ "ApprovalReceived" ] }, "workflow_id": { "type": "string", "format": "uuid" }, "step_key": { "type": "string" }, "by": { "type": "string" }, "current": { "type": "integer" }, "required": { "type": "integer" } } } }, { "name": "StepSkipped", "schema": { "type": "object", "required": [ "type", "workflow_id", "step_key", "reason" ], "properties": { "type": { "type": "string", "enum": [ "StepSkipped" ] }, "workflow_id": { "type": "string", "format": "uuid" }, "step_key": { "type": "string" }, "reason": { "type": "string" } } } }, { "name": "WorkflowCompleted", "schema": { "type": "object", "required": [ "type", "workflow_id" ], "properties": { "type": { "type": "string", "enum": [ "WorkflowCompleted" ] }, "workflow_id": { "type": "string", "format": "uuid" }, "result_summary": { "type": [ "string", "null" ] } } } }, { "name": "StepUpdated", "schema": { "type": "object", "required": [ "type", "workflow_id", "step_key", "status" ], "properties": { "type": { "type": "string", "enum": [ "StepUpdated" ] }, "workflow_id": { "type": "string", "format": "uuid" }, "step_key": { "type": "string" }, "status": { "type": "string" } } } }, { "name": "StepFailed", "schema": { "type": "object", "required": [ "type", "workflow_id", "step_key", "error" ], "properties": { "type": { "type": "string", "enum": [ "StepFailed" ] }, "workflow_id": { "type": "string", "format": "uuid" }, "step_key": { "type": "string" }, "error": { "type": "string" } } } }, { "name": "WorkflowFailed", "schema": { "type": "object", "required": [ "type", "workflow_id", "error" ], "properties": { "type": { "type": "string", "enum": [ "WorkflowFailed" ] }, "workflow_id": { "type": "string", "format": "uuid" }, "error": { "type": "string" } } } }, { "name": "Lagged", "description": "Stream-control notice (synthetic): the subscriber fell behind and `skipped` events were dropped. Not a WorkflowEvent variant.", "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "Lagged" ] }, "skipped": { "type": "integer" } } } }, { "name": "StreamEnded", "description": "Stream-control notice (synthetic): the broadcast channel closed. Not a WorkflowEvent variant — the wire connection will close after this.", "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "StreamEnded" ] } } } } ], "x-mcp": { "tool_name": "yieldfabric_agents_streamWorkflow_Workflows", "resource_uri": "yf://agents/workflows", "idempotent": true }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -N -H \"Authorization: Bearer $JWT\" https://agents.yieldfabric.com/working-groups/{id}/workflows/{wid}/stream" } ], "x-related": [ { "operationId": "getWorkflow_Workflows", "relation": "alternative" }, { "operationId": "startWorkflow_Workflows", "relation": "prerequisite" }, { "guide": "streaming", "relation": "concept" }, { "guide": "workflows", "relation": "concept" } ] } }, "/api/notebook/entities/by-frame-id/{id}/investigation/context": { "get": { "operationId": "investigationContext_Notebook", "x-method": "GET", "x-path": "/api/notebook/entities/by-frame-id/{id}/investigation/context", "x-handler": "handlers::notebook::investigation_cases::context", "tags": [ "Notebook" ], "summary": "Resolve scope and capabilities for any ontology frame.", "description": "Bearer authentication is required. A case belongs to the verified principal and effective delegation. Workspace subjects use only their home workspace; private subjects may include selected, currently accessible workspaces. Saved derivatives retain every source dependency. Publication requires home-contained evidence and write permission. Keep is curation, not endorsement. Identity review never merges entities.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workspace_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "kg_id", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Authorized response; Cache-Control: no-store.", "content": { "application/json": { "schema": { "type": "object", "required": [ "target", "label", "concept_type", "frame_kind", "private", "home_workspace_id", "home_name", "workspaces", "can_publish", "can_review", "internal_available", "public_available", "case_id" ], "properties": { "target": { "type": "object", "required": [ "kg_id", "frame_id" ], "properties": { "kg_id": { "type": "string", "format": "uuid" }, "frame_id": { "type": "string" } } }, "label": { "type": "string" }, "concept_type": { "type": [ "string", "null" ] }, "frame_kind": { "type": [ "string", "null" ] }, "private": { "type": "boolean" }, "home_workspace_id": { "type": "string", "format": "uuid" }, "home_name": { "type": "string" }, "workspaces": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "is_private" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "is_private": { "type": "boolean" } } } }, "can_publish": { "type": "boolean" }, "can_review": { "type": "boolean" }, "internal_available": { "type": "boolean" }, "public_available": { "type": "boolean" }, "case_id": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "400": { "description": "Invalid selector, ontology or command." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Source access, human review or publication permission denied." }, "404": { "description": "Subject, case or source absent or inaccessible." } } } }, "/api/notebook/entities/by-frame-id/{id}/investigation/cases": { "post": { "operationId": "createInvestigation_Notebook", "x-method": "POST", "x-path": "/api/notebook/entities/by-frame-id/{id}/investigation/cases", "x-handler": "handlers::notebook::investigation_cases::create", "tags": [ "Notebook" ], "summary": "Create or reopen the caller’s investigation.", "description": "Bearer authentication is required. A case belongs to the verified principal and effective delegation. Workspace subjects use only their home workspace; private subjects may include selected, currently accessible workspaces. Saved derivatives retain every source dependency. Publication requires home-contained evidence and write permission. Keep is curation, not endorsement. Identity review never merges entities.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workspace_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "kg_id", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Authorized response; Cache-Control: no-store.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "version", "question", "note", "note_availability", "selected_workspaces", "items", "next_offset", "brief", "brief_availability", "runs" ], "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "integer" }, "question": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "note_availability": { "type": "string", "enum": [ "available", "needs_refresh", "access_changed", "unavailable" ] }, "selected_workspaces": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "version", "run_id", "availability", "review_status", "statement", "explanation", "assessment", "proposition_kind", "sources", "can_publish", "publication", "epistemic" ], "properties": { "extraction": { "type": "object", "required": [ "entities", "vocabulary", "kind", "predicate", "slots", "ready" ], "description": "Readable projection over native frame roles and the existing ExtractionLexicon. Proposed definitions remain protected until authorized publication.", "properties": { "kind": { "type": [ "string", "null" ], "enum": [ "state", "relation", "event", "speech_act", "mental", null ] }, "predicate": { "type": [ "string", "null" ] }, "ready": { "type": "boolean", "description": "All content dependencies are structurally typed and valid against the current home ontology; this does not establish truth or publication permission." }, "slots": { "type": "object", "additionalProperties": { "type": "string" } }, "entities": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "concept_type", "matches" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "concept_type": { "type": "string" }, "matches": { "type": "array", "description": "Home-graph identity suggestions, never automatic merges.", "items": { "type": "object", "required": [ "reference", "label" ], "properties": { "reference": { "type": "object", "required": [ "kg_id", "frame_id", "revision" ], "properties": { "kg_id": { "type": "string", "format": "uuid" }, "frame_id": { "type": "string" }, "revision": { "type": "string" } } }, "label": { "type": "string" } } } } } } }, "vocabulary": { "type": "object", "description": "Minimal native ExtractionLexicon additions used by this claim's dependency closure. Includes concepts, terms, parties and verbs; never executable actions or generated rules.", "properties": { "concepts": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "extends": { "type": [ "string", "null" ] }, "desc": { "type": [ "string", "null" ] } } } ] } }, "terms": { "type": "object", "additionalProperties": { "type": "string" } }, "parties": { "type": "object", "additionalProperties": { "type": "string" } }, "verbs": { "type": "array", "items": { "type": "object", "required": [ "pattern", "kind", "binds" ], "properties": { "pattern": { "type": "string" }, "kind": { "type": "string" }, "binds": { "type": "object", "additionalProperties": { "type": "string" } }, "stance_default": { "type": [ "string", "null" ] } } } } } } } }, "id": { "type": "string" }, "version": { "type": "integer" }, "run_id": { "type": [ "string", "null" ], "format": "uuid" }, "availability": { "type": "string", "enum": [ "available", "needs_refresh", "access_changed", "unavailable" ] }, "review_status": { "type": "string", "enum": [ "needs_review", "kept", "dismissed", "published", "endorsed", "challenged", "same_entity", "different_entity", "unsure" ] }, "statement": { "type": [ "string", "null" ] }, "explanation": { "type": [ "string", "null" ] }, "assessment": { "type": [ "string", "null" ] }, "proposition_kind": { "type": [ "string", "null" ] }, "sources": { "type": "array", "items": { "type": "object", "required": [ "reference", "label", "text", "workspace_id", "workspace_name", "concept_type", "frame_kind", "verb", "stance", "lifecycle" ], "properties": { "reference": { "type": "object", "required": [ "kg_id", "frame_id", "revision" ], "properties": { "kg_id": { "type": "string", "format": "uuid" }, "frame_id": { "type": "string" }, "revision": { "type": "string" } } }, "label": { "type": "string" }, "text": { "type": "string" }, "workspace_id": { "type": "string", "format": "uuid" }, "workspace_name": { "type": "string" }, "concept_type": { "type": [ "string", "null" ] }, "frame_kind": { "type": [ "string", "null" ] }, "verb": { "type": [ "string", "null" ] }, "stance": { "type": [ "string", "null" ] }, "lifecycle": { "type": "string" }, "public_research": { "type": "object", "required": [ "provider", "response_id", "generated_at", "status", "parts", "search_calls" ], "properties": { "provider": { "type": "string", "const": "azure_bing" }, "response_id": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "completed", "no_cited_sources" ] }, "search_calls": { "type": "integer" }, "parts": { "type": "array", "items": { "type": "object", "required": [ "text", "citations" ], "properties": { "text": { "type": "string" }, "citations": { "type": "array", "items": { "type": "object", "required": [ "url", "title", "start_index", "end_index" ], "properties": { "url": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" } } } } } } } } } } } }, "can_publish": { "type": "boolean" }, "publication": { "oneOf": [ { "type": "object", "required": [ "kg_id", "frame_id" ], "properties": { "kg_id": { "type": "string", "format": "uuid" }, "frame_id": { "type": "string" } } }, { "type": "null" } ] }, "epistemic": { "oneOf": [ { "type": "object", "required": [ "state", "supports", "challenges", "questions" ], "properties": { "state": { "type": "string" }, "supports": { "type": "integer" }, "challenges": { "type": "integer" }, "questions": { "type": "integer" } } }, { "type": "null" } ] } } } }, "next_offset": { "type": [ "integer", "null" ] }, "brief": { "type": [ "string", "null" ] }, "brief_availability": { "type": "string", "enum": [ "available", "needs_refresh", "access_changed", "unavailable" ] }, "runs": { "type": "array", "items": { "type": "object", "required": [ "id", "status", "stop_reason", "source_workspaces", "created_at", "deadline", "evidence_count", "prompt_tokens", "completion_tokens" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "running", "completed", "partial", "failed", "interrupted" ] }, "stop_reason": { "type": [ "string", "null" ] }, "source_workspaces": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "created_at": { "type": "string", "format": "date-time" }, "deadline": { "type": "string", "format": "date-time" }, "evidence_count": { "type": "integer" }, "prompt_tokens": { "type": [ "integer", "null" ] }, "completion_tokens": { "type": [ "integer", "null" ] } } } } } } } } }, "400": { "description": "Invalid selector, ontology or command." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Source access, human review or publication permission denied." }, "404": { "description": "Subject, case or source absent or inaccessible." }, "409": { "description": "A version changed, an active run exists, or an idempotency key conflicts." }, "503": { "description": "Evidence or model unavailable." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "question" ], "properties": { "question": { "type": "string", "minLength": 1, "maxLength": 1600 }, "selected_workspaces": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "additionalProperties": false } } } } } }, "/api/notebook/investigations/{id}": { "get": { "operationId": "getInvestigation_Notebook", "x-method": "GET", "x-path": "/api/notebook/investigations/{id}", "x-handler": "handlers::notebook::investigation_cases::get", "tags": [ "Notebook" ], "summary": "Read saved research under current source permissions.", "description": "Bearer authentication is required. A case belongs to the verified principal and effective delegation. Workspace subjects use only their home workspace; private subjects may include selected, currently accessible workspaces. Saved derivatives retain every source dependency. Publication requires home-contained evidence and write permission. Keep is curation, not endorsement. Identity review never merges entities. Returns at most 24 findings and 20 recent run receipts. Access changes hide dependent findings, notes and briefs. Changed evidence produces needs_refresh; source deletion purges derived text. Null usage is unknown, not zero cost.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 10000 } } ], "responses": { "200": { "description": "Authorized response; Cache-Control: no-store.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "version", "question", "note", "note_availability", "selected_workspaces", "items", "next_offset", "brief", "brief_availability", "runs" ], "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "integer" }, "question": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "note_availability": { "type": "string", "enum": [ "available", "needs_refresh", "access_changed", "unavailable" ] }, "selected_workspaces": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "version", "run_id", "availability", "review_status", "statement", "explanation", "assessment", "proposition_kind", "sources", "can_publish", "publication", "epistemic" ], "properties": { "extraction": { "type": "object", "required": [ "entities", "vocabulary", "kind", "predicate", "slots", "ready" ], "description": "Readable projection over native frame roles and the existing ExtractionLexicon. Proposed definitions remain protected until authorized publication.", "properties": { "kind": { "type": [ "string", "null" ], "enum": [ "state", "relation", "event", "speech_act", "mental", null ] }, "predicate": { "type": [ "string", "null" ] }, "ready": { "type": "boolean", "description": "All content dependencies are structurally typed and valid against the current home ontology; this does not establish truth or publication permission." }, "slots": { "type": "object", "additionalProperties": { "type": "string" } }, "entities": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "concept_type", "matches" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "concept_type": { "type": "string" }, "matches": { "type": "array", "description": "Home-graph identity suggestions, never automatic merges.", "items": { "type": "object", "required": [ "reference", "label" ], "properties": { "reference": { "type": "object", "required": [ "kg_id", "frame_id", "revision" ], "properties": { "kg_id": { "type": "string", "format": "uuid" }, "frame_id": { "type": "string" }, "revision": { "type": "string" } } }, "label": { "type": "string" } } } } } } }, "vocabulary": { "type": "object", "description": "Minimal native ExtractionLexicon additions used by this claim's dependency closure. Includes concepts, terms, parties and verbs; never executable actions or generated rules.", "properties": { "concepts": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "extends": { "type": [ "string", "null" ] }, "desc": { "type": [ "string", "null" ] } } } ] } }, "terms": { "type": "object", "additionalProperties": { "type": "string" } }, "parties": { "type": "object", "additionalProperties": { "type": "string" } }, "verbs": { "type": "array", "items": { "type": "object", "required": [ "pattern", "kind", "binds" ], "properties": { "pattern": { "type": "string" }, "kind": { "type": "string" }, "binds": { "type": "object", "additionalProperties": { "type": "string" } }, "stance_default": { "type": [ "string", "null" ] } } } } } } } }, "id": { "type": "string" }, "version": { "type": "integer" }, "run_id": { "type": [ "string", "null" ], "format": "uuid" }, "availability": { "type": "string", "enum": [ "available", "needs_refresh", "access_changed", "unavailable" ] }, "review_status": { "type": "string", "enum": [ "needs_review", "kept", "dismissed", "published", "endorsed", "challenged", "same_entity", "different_entity", "unsure" ] }, "statement": { "type": [ "string", "null" ] }, "explanation": { "type": [ "string", "null" ] }, "assessment": { "type": [ "string", "null" ] }, "proposition_kind": { "type": [ "string", "null" ] }, "sources": { "type": "array", "items": { "type": "object", "required": [ "reference", "label", "text", "workspace_id", "workspace_name", "concept_type", "frame_kind", "verb", "stance", "lifecycle" ], "properties": { "reference": { "type": "object", "required": [ "kg_id", "frame_id", "revision" ], "properties": { "kg_id": { "type": "string", "format": "uuid" }, "frame_id": { "type": "string" }, "revision": { "type": "string" } } }, "label": { "type": "string" }, "text": { "type": "string" }, "workspace_id": { "type": "string", "format": "uuid" }, "workspace_name": { "type": "string" }, "concept_type": { "type": [ "string", "null" ] }, "frame_kind": { "type": [ "string", "null" ] }, "verb": { "type": [ "string", "null" ] }, "stance": { "type": [ "string", "null" ] }, "lifecycle": { "type": "string" }, "public_research": { "type": "object", "required": [ "provider", "response_id", "generated_at", "status", "parts", "search_calls" ], "properties": { "provider": { "type": "string", "const": "azure_bing" }, "response_id": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "completed", "no_cited_sources" ] }, "search_calls": { "type": "integer" }, "parts": { "type": "array", "items": { "type": "object", "required": [ "text", "citations" ], "properties": { "text": { "type": "string" }, "citations": { "type": "array", "items": { "type": "object", "required": [ "url", "title", "start_index", "end_index" ], "properties": { "url": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" } } } } } } } } } } } }, "can_publish": { "type": "boolean" }, "publication": { "oneOf": [ { "type": "object", "required": [ "kg_id", "frame_id" ], "properties": { "kg_id": { "type": "string", "format": "uuid" }, "frame_id": { "type": "string" } } }, { "type": "null" } ] }, "epistemic": { "oneOf": [ { "type": "object", "required": [ "state", "supports", "challenges", "questions" ], "properties": { "state": { "type": "string" }, "supports": { "type": "integer" }, "challenges": { "type": "integer" }, "questions": { "type": "integer" } } }, { "type": "null" } ] } } } }, "next_offset": { "type": [ "integer", "null" ] }, "brief": { "type": [ "string", "null" ] }, "brief_availability": { "type": "string", "enum": [ "available", "needs_refresh", "access_changed", "unavailable" ] }, "runs": { "type": "array", "items": { "type": "object", "required": [ "id", "status", "stop_reason", "source_workspaces", "created_at", "deadline", "evidence_count", "prompt_tokens", "completion_tokens" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "running", "completed", "partial", "failed", "interrupted" ] }, "stop_reason": { "type": [ "string", "null" ] }, "source_workspaces": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "created_at": { "type": "string", "format": "date-time" }, "deadline": { "type": "string", "format": "date-time" }, "evidence_count": { "type": "integer" }, "prompt_tokens": { "type": [ "integer", "null" ] }, "completion_tokens": { "type": [ "integer", "null" ] } } } } } } } } }, "400": { "description": "Invalid selector, ontology or command." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Source access, human review or publication permission denied." }, "404": { "description": "Subject, case or source absent or inaccessible." } } }, "patch": { "operationId": "updateInvestigation_Notebook", "x-method": "PATCH", "x-path": "/api/notebook/investigations/{id}", "x-handler": "handlers::notebook::investigation_cases::patch", "tags": [ "Notebook" ], "summary": "Save a versioned research draft.", "description": "Bearer authentication is required. A case belongs to the verified principal and effective delegation. Workspace subjects use only their home workspace; private subjects may include selected, currently accessible workspaces. Saved derivatives retain every source dependency. Publication requires home-contained evidence and write permission. Keep is curation, not endorsement. Identity review never merges entities.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Authorized response; Cache-Control: no-store.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "version", "question", "note", "note_availability", "selected_workspaces", "items", "next_offset", "brief", "brief_availability", "runs" ], "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "integer" }, "question": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "note_availability": { "type": "string", "enum": [ "available", "needs_refresh", "access_changed", "unavailable" ] }, "selected_workspaces": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "version", "run_id", "availability", "review_status", "statement", "explanation", "assessment", "proposition_kind", "sources", "can_publish", "publication", "epistemic" ], "properties": { "extraction": { "type": "object", "required": [ "entities", "vocabulary", "kind", "predicate", "slots", "ready" ], "description": "Readable projection over native frame roles and the existing ExtractionLexicon. Proposed definitions remain protected until authorized publication.", "properties": { "kind": { "type": [ "string", "null" ], "enum": [ "state", "relation", "event", "speech_act", "mental", null ] }, "predicate": { "type": [ "string", "null" ] }, "ready": { "type": "boolean", "description": "All content dependencies are structurally typed and valid against the current home ontology; this does not establish truth or publication permission." }, "slots": { "type": "object", "additionalProperties": { "type": "string" } }, "entities": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "concept_type", "matches" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "concept_type": { "type": "string" }, "matches": { "type": "array", "description": "Home-graph identity suggestions, never automatic merges.", "items": { "type": "object", "required": [ "reference", "label" ], "properties": { "reference": { "type": "object", "required": [ "kg_id", "frame_id", "revision" ], "properties": { "kg_id": { "type": "string", "format": "uuid" }, "frame_id": { "type": "string" }, "revision": { "type": "string" } } }, "label": { "type": "string" } } } } } } }, "vocabulary": { "type": "object", "description": "Minimal native ExtractionLexicon additions used by this claim's dependency closure. Includes concepts, terms, parties and verbs; never executable actions or generated rules.", "properties": { "concepts": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "extends": { "type": [ "string", "null" ] }, "desc": { "type": [ "string", "null" ] } } } ] } }, "terms": { "type": "object", "additionalProperties": { "type": "string" } }, "parties": { "type": "object", "additionalProperties": { "type": "string" } }, "verbs": { "type": "array", "items": { "type": "object", "required": [ "pattern", "kind", "binds" ], "properties": { "pattern": { "type": "string" }, "kind": { "type": "string" }, "binds": { "type": "object", "additionalProperties": { "type": "string" } }, "stance_default": { "type": [ "string", "null" ] } } } } } } } }, "id": { "type": "string" }, "version": { "type": "integer" }, "run_id": { "type": [ "string", "null" ], "format": "uuid" }, "availability": { "type": "string", "enum": [ "available", "needs_refresh", "access_changed", "unavailable" ] }, "review_status": { "type": "string", "enum": [ "needs_review", "kept", "dismissed", "published", "endorsed", "challenged", "same_entity", "different_entity", "unsure" ] }, "statement": { "type": [ "string", "null" ] }, "explanation": { "type": [ "string", "null" ] }, "assessment": { "type": [ "string", "null" ] }, "proposition_kind": { "type": [ "string", "null" ] }, "sources": { "type": "array", "items": { "type": "object", "required": [ "reference", "label", "text", "workspace_id", "workspace_name", "concept_type", "frame_kind", "verb", "stance", "lifecycle" ], "properties": { "reference": { "type": "object", "required": [ "kg_id", "frame_id", "revision" ], "properties": { "kg_id": { "type": "string", "format": "uuid" }, "frame_id": { "type": "string" }, "revision": { "type": "string" } } }, "label": { "type": "string" }, "text": { "type": "string" }, "workspace_id": { "type": "string", "format": "uuid" }, "workspace_name": { "type": "string" }, "concept_type": { "type": [ "string", "null" ] }, "frame_kind": { "type": [ "string", "null" ] }, "verb": { "type": [ "string", "null" ] }, "stance": { "type": [ "string", "null" ] }, "lifecycle": { "type": "string" }, "public_research": { "type": "object", "required": [ "provider", "response_id", "generated_at", "status", "parts", "search_calls" ], "properties": { "provider": { "type": "string", "const": "azure_bing" }, "response_id": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "completed", "no_cited_sources" ] }, "search_calls": { "type": "integer" }, "parts": { "type": "array", "items": { "type": "object", "required": [ "text", "citations" ], "properties": { "text": { "type": "string" }, "citations": { "type": "array", "items": { "type": "object", "required": [ "url", "title", "start_index", "end_index" ], "properties": { "url": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" } } } } } } } } } } } }, "can_publish": { "type": "boolean" }, "publication": { "oneOf": [ { "type": "object", "required": [ "kg_id", "frame_id" ], "properties": { "kg_id": { "type": "string", "format": "uuid" }, "frame_id": { "type": "string" } } }, { "type": "null" } ] }, "epistemic": { "oneOf": [ { "type": "object", "required": [ "state", "supports", "challenges", "questions" ], "properties": { "state": { "type": "string" }, "supports": { "type": "integer" }, "challenges": { "type": "integer" }, "questions": { "type": "integer" } } }, { "type": "null" } ] } } } }, "next_offset": { "type": [ "integer", "null" ] }, "brief": { "type": [ "string", "null" ] }, "brief_availability": { "type": "string", "enum": [ "available", "needs_refresh", "access_changed", "unavailable" ] }, "runs": { "type": "array", "items": { "type": "object", "required": [ "id", "status", "stop_reason", "source_workspaces", "created_at", "deadline", "evidence_count", "prompt_tokens", "completion_tokens" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "running", "completed", "partial", "failed", "interrupted" ] }, "stop_reason": { "type": [ "string", "null" ] }, "source_workspaces": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "created_at": { "type": "string", "format": "date-time" }, "deadline": { "type": "string", "format": "date-time" }, "evidence_count": { "type": "integer" }, "prompt_tokens": { "type": [ "integer", "null" ] }, "completion_tokens": { "type": [ "integer", "null" ] } } } } } } } } }, "400": { "description": "Invalid selector, ontology or command." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Source access, human review or publication permission denied." }, "404": { "description": "Subject, case or source absent or inaccessible." }, "409": { "description": "A version changed, an active run exists, or an idempotency key conflicts." }, "503": { "description": "Evidence or model unavailable." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "expected_version" ], "properties": { "expected_version": { "type": "integer" }, "question": { "type": "string", "minLength": 1, "maxLength": 1600 }, "note": { "type": "string", "maxLength": 8000 }, "selected_workspaces": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "additionalProperties": false } } } } }, "delete": { "operationId": "deleteInvestigation_Notebook", "x-method": "DELETE", "x-path": "/api/notebook/investigations/{id}", "x-handler": "handlers::notebook::investigation_cases::delete", "tags": [ "Notebook" ], "summary": "Delete research frames; published home knowledge remains.", "description": "Bearer authentication is required. A case belongs to the verified principal and effective delegation. Workspace subjects use only their home workspace; private subjects may include selected, currently accessible workspaces. Saved derivatives retain every source dependency. Publication requires home-contained evidence and write permission. Keep is curation, not endorsement. Identity review never merges entities.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "expected_version", "in": "query", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Authorized response; Cache-Control: no-store.", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } } } } } }, "400": { "description": "Invalid selector, ontology or command." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Source access, human review or publication permission denied." }, "404": { "description": "Subject, case or source absent or inaccessible." }, "409": { "description": "A version changed, an active run exists, or an idempotency key conflicts." }, "503": { "description": "Evidence or model unavailable." } } } }, "/api/notebook/investigations/{id}/runs": { "post": { "operationId": "runInvestigation_Notebook", "x-method": "POST", "x-path": "/api/notebook/investigations/{id}/runs", "x-handler": "handlers::notebook::investigation_cases::run", "tags": [ "Notebook" ], "summary": "Investigate internal knowledge or extract native ontology claims from a saved source.", "description": "Bearer authentication is required. A case belongs to the verified principal and effective delegation. Workspace subjects use only their home workspace; private subjects may include selected, currently accessible workspaces. Saved derivatives retain every source dependency. Publication requires home-contained evidence and write permission. Keep is curation, not endorsement. Identity review never merges entities. A request key dispatches once. One active run per case, with per-entity admission and billing. Without source, reuses the shared internal tool loop and disconnect abandons execution. With source, uses shared induction to prepare native entities, propositions and required vocabulary in the protected case. This explicit extraction continues after disconnect and commits its draft atomically. It does not fetch citation URLs or publish knowledge. Unfinished receipts become interrupted at their deadline. An unchanged source, home revision, ontology and extractor version reuse completed extraction unless reprocess is true. Each retry of one request_key still dispatches at most once. Public search remains separate; its saved reports may be explicitly extracted only in their owning case and all source restrictions carry through. Source text and reasoning never enter generic call logs. A source is limited to 16000 characters; generated drafts are bounded to 24 claims and 24 entities. Model ontology context is bounded to 16000 UTF-8 bytes, preserving required definitions; validation and publication use the full home ontology. Validation gets at most one retry per induction stage. Extraction has a 240-second execution limit and 270-second recovery lease; internal research retains 120/150 seconds respectively.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "SSE stage events end with is_final:true, run_id, and optional reused or error. Errors and incomplete streams never mean completion.", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid selector, ontology or command." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "402": { "description": "Billing required." }, "403": { "description": "Source access, human review or publication permission denied." }, "404": { "description": "Subject, case or source absent or inaccessible." }, "409": { "description": "A version changed, an active run exists, or an idempotency key conflicts." }, "429": { "description": "Per-entity inference admission limit exceeded." }, "503": { "description": "Evidence or model unavailable." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "expected_version", "request_key" ], "properties": { "expected_version": { "type": "integer" }, "request_key": { "type": "string", "format": "uuid" }, "source": { "type": "object", "required": [ "kg_id", "frame_id", "revision" ], "properties": { "kg_id": { "type": "string", "format": "uuid" }, "frame_id": { "type": "string" }, "revision": { "type": "string" } } }, "reprocess": { "type": "boolean", "default": false, "description": "Explicitly repeat saved-source extraction. Requires source. May use AI credits." } }, "additionalProperties": false } } } } } }, "/api/notebook/investigations/{id}/runs/{run}": { "get": { "operationId": "getInvestigationRun_Notebook", "x-method": "GET", "x-path": "/api/notebook/investigations/{id}/runs/{run}", "x-handler": "handlers::notebook::investigation_cases::run_receipt", "tags": [ "Notebook" ], "summary": "Read a run receipt without calling a model.", "description": "Bearer authentication is required. A case belongs to the verified principal and effective delegation. Workspace subjects use only their home workspace; private subjects may include selected, currently accessible workspaces. Saved derivatives retain every source dependency. Publication requires home-contained evidence and write permission. Keep is curation, not endorsement. Identity review never merges entities.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "run", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Authorized response; Cache-Control: no-store.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "status", "stop_reason", "source_workspaces", "created_at", "deadline", "evidence_count", "prompt_tokens", "completion_tokens" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "running", "completed", "partial", "failed", "interrupted" ] }, "stop_reason": { "type": [ "string", "null" ] }, "source_workspaces": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "created_at": { "type": "string", "format": "date-time" }, "deadline": { "type": "string", "format": "date-time" }, "evidence_count": { "type": "integer" }, "prompt_tokens": { "type": [ "integer", "null" ] }, "completion_tokens": { "type": [ "integer", "null" ] } } } } } }, "400": { "description": "Invalid selector, ontology or command." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Source access, human review or publication permission denied." }, "404": { "description": "Subject, case or source absent or inaccessible." } } } }, "/api/notebook/investigations/{id}/items/{item}/decisions": { "post": { "operationId": "reviewInvestigationFinding_Notebook", "x-method": "POST", "x-path": "/api/notebook/investigations/{id}/items/{item}/decisions", "x-handler": "handlers::notebook::investigation_cases::decide", "tags": [ "Notebook" ], "summary": "Record human review or publish to the home knowledge graph.", "description": "Bearer authentication is required. A case belongs to the verified principal and effective delegation. Workspace subjects use only their home workspace; private subjects may include selected, currently accessible workspaces. Saved derivatives retain every source dependency. Publication requires home-contained evidence and write permission. Keep is curation, not endorsement. Identity review never merges entities. Publishing an extracted claim requires an explicit resolution for every draft entity: select a current entity in its home KG, or null to create a distinct entity. The claim, required vocabulary additions, selected identities, source dependencies and human review receipt commit in one transaction. Existing ontology definitions are preserved. Untyped drafts cannot publish. Public-source restrictions still apply after extraction. The command identity includes entity_resolutions.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "item", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Authorized response; Cache-Control: no-store.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "version", "question", "note", "note_availability", "selected_workspaces", "items", "next_offset", "brief", "brief_availability", "runs" ], "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "integer" }, "question": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "note_availability": { "type": "string", "enum": [ "available", "needs_refresh", "access_changed", "unavailable" ] }, "selected_workspaces": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "version", "run_id", "availability", "review_status", "statement", "explanation", "assessment", "proposition_kind", "sources", "can_publish", "publication", "epistemic" ], "properties": { "extraction": { "type": "object", "required": [ "entities", "vocabulary", "kind", "predicate", "slots", "ready" ], "description": "Readable projection over native frame roles and the existing ExtractionLexicon. Proposed definitions remain protected until authorized publication.", "properties": { "kind": { "type": [ "string", "null" ], "enum": [ "state", "relation", "event", "speech_act", "mental", null ] }, "predicate": { "type": [ "string", "null" ] }, "ready": { "type": "boolean", "description": "All content dependencies are structurally typed and valid against the current home ontology; this does not establish truth or publication permission." }, "slots": { "type": "object", "additionalProperties": { "type": "string" } }, "entities": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "concept_type", "matches" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "concept_type": { "type": "string" }, "matches": { "type": "array", "description": "Home-graph identity suggestions, never automatic merges.", "items": { "type": "object", "required": [ "reference", "label" ], "properties": { "reference": { "type": "object", "required": [ "kg_id", "frame_id", "revision" ], "properties": { "kg_id": { "type": "string", "format": "uuid" }, "frame_id": { "type": "string" }, "revision": { "type": "string" } } }, "label": { "type": "string" } } } } } } }, "vocabulary": { "type": "object", "description": "Minimal native ExtractionLexicon additions used by this claim's dependency closure. Includes concepts, terms, parties and verbs; never executable actions or generated rules.", "properties": { "concepts": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "extends": { "type": [ "string", "null" ] }, "desc": { "type": [ "string", "null" ] } } } ] } }, "terms": { "type": "object", "additionalProperties": { "type": "string" } }, "parties": { "type": "object", "additionalProperties": { "type": "string" } }, "verbs": { "type": "array", "items": { "type": "object", "required": [ "pattern", "kind", "binds" ], "properties": { "pattern": { "type": "string" }, "kind": { "type": "string" }, "binds": { "type": "object", "additionalProperties": { "type": "string" } }, "stance_default": { "type": [ "string", "null" ] } } } } } } } }, "id": { "type": "string" }, "version": { "type": "integer" }, "run_id": { "type": [ "string", "null" ], "format": "uuid" }, "availability": { "type": "string", "enum": [ "available", "needs_refresh", "access_changed", "unavailable" ] }, "review_status": { "type": "string", "enum": [ "needs_review", "kept", "dismissed", "published", "endorsed", "challenged", "same_entity", "different_entity", "unsure" ] }, "statement": { "type": [ "string", "null" ] }, "explanation": { "type": [ "string", "null" ] }, "assessment": { "type": [ "string", "null" ] }, "proposition_kind": { "type": [ "string", "null" ] }, "sources": { "type": "array", "items": { "type": "object", "required": [ "reference", "label", "text", "workspace_id", "workspace_name", "concept_type", "frame_kind", "verb", "stance", "lifecycle" ], "properties": { "reference": { "type": "object", "required": [ "kg_id", "frame_id", "revision" ], "properties": { "kg_id": { "type": "string", "format": "uuid" }, "frame_id": { "type": "string" }, "revision": { "type": "string" } } }, "label": { "type": "string" }, "text": { "type": "string" }, "workspace_id": { "type": "string", "format": "uuid" }, "workspace_name": { "type": "string" }, "concept_type": { "type": [ "string", "null" ] }, "frame_kind": { "type": [ "string", "null" ] }, "verb": { "type": [ "string", "null" ] }, "stance": { "type": [ "string", "null" ] }, "lifecycle": { "type": "string" }, "public_research": { "type": "object", "required": [ "provider", "response_id", "generated_at", "status", "parts", "search_calls" ], "properties": { "provider": { "type": "string", "const": "azure_bing" }, "response_id": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "completed", "no_cited_sources" ] }, "search_calls": { "type": "integer" }, "parts": { "type": "array", "items": { "type": "object", "required": [ "text", "citations" ], "properties": { "text": { "type": "string" }, "citations": { "type": "array", "items": { "type": "object", "required": [ "url", "title", "start_index", "end_index" ], "properties": { "url": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" } } } } } } } } } } } }, "can_publish": { "type": "boolean" }, "publication": { "oneOf": [ { "type": "object", "required": [ "kg_id", "frame_id" ], "properties": { "kg_id": { "type": "string", "format": "uuid" }, "frame_id": { "type": "string" } } }, { "type": "null" } ] }, "epistemic": { "oneOf": [ { "type": "object", "required": [ "state", "supports", "challenges", "questions" ], "properties": { "state": { "type": "string" }, "supports": { "type": "integer" }, "challenges": { "type": "integer" }, "questions": { "type": "integer" } } }, { "type": "null" } ] } } } }, "next_offset": { "type": [ "integer", "null" ] }, "brief": { "type": [ "string", "null" ] }, "brief_availability": { "type": "string", "enum": [ "available", "needs_refresh", "access_changed", "unavailable" ] }, "runs": { "type": "array", "items": { "type": "object", "required": [ "id", "status", "stop_reason", "source_workspaces", "created_at", "deadline", "evidence_count", "prompt_tokens", "completion_tokens" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "running", "completed", "partial", "failed", "interrupted" ] }, "stop_reason": { "type": [ "string", "null" ] }, "source_workspaces": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "created_at": { "type": "string", "format": "date-time" }, "deadline": { "type": "string", "format": "date-time" }, "evidence_count": { "type": "integer" }, "prompt_tokens": { "type": [ "integer", "null" ] }, "completion_tokens": { "type": [ "integer", "null" ] } } } } } } } } }, "400": { "description": "Invalid selector, ontology or command." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Source access, human review or publication permission denied." }, "404": { "description": "Subject, case or source absent or inaccessible." }, "409": { "description": "A version changed, an active run exists, or an idempotency key conflicts." }, "503": { "description": "Evidence or model unavailable." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "expected_version", "command_id", "decision" ], "properties": { "expected_version": { "type": "integer" }, "command_id": { "type": "string", "format": "uuid" }, "decision": { "type": "string", "enum": [ "keep", "dismiss", "undo", "publish", "endorse", "challenge", "same_entity", "different_entity", "unsure" ] }, "entity_resolutions": { "type": "object", "default": {}, "description": "Map extraction entity IDs to existing home-graph references or null to create distinct identities. Required for publishing an extraction with entities.", "additionalProperties": { "oneOf": [ { "type": "object", "required": [ "kg_id", "frame_id", "revision" ], "properties": { "kg_id": { "type": "string", "format": "uuid" }, "frame_id": { "type": "string" }, "revision": { "type": "string" } } }, { "type": "null" } ] } } }, "additionalProperties": false } } } } } }, "/api/notebook/investigations/{id}/sources": { "get": { "operationId": "getInvestigationSource_Notebook", "x-method": "GET", "x-path": "/api/notebook/investigations/{id}/sources", "x-handler": "handlers::notebook::investigation_cases::source", "tags": [ "Notebook" ], "summary": "Rehydrate an exact cited source under current access.", "description": "Bearer authentication is required. A case belongs to the verified principal and effective delegation. Workspace subjects use only their home workspace; private subjects may include selected, currently accessible workspaces. Saved derivatives retain every source dependency. Publication requires home-contained evidence and write permission. Keep is curation, not endorsement. Identity review never merges entities. The exact current case may also resolve its protected public research provenance, returned in Evidence.public_research with original answer text and citations. This is service attribution, not independently fetched publisher content; another actor, entity home or delegation cannot resolve it.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kg_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "frame_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "revision", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Authorized response; Cache-Control: no-store.", "content": { "application/json": { "schema": { "type": "object", "required": [ "source", "changed" ], "properties": { "source": { "type": "object", "required": [ "reference", "label", "text", "workspace_id", "workspace_name", "concept_type", "frame_kind", "verb", "stance", "lifecycle" ], "properties": { "reference": { "type": "object", "required": [ "kg_id", "frame_id", "revision" ], "properties": { "kg_id": { "type": "string", "format": "uuid" }, "frame_id": { "type": "string" }, "revision": { "type": "string" } } }, "label": { "type": "string" }, "text": { "type": "string" }, "workspace_id": { "type": "string", "format": "uuid" }, "workspace_name": { "type": "string" }, "concept_type": { "type": [ "string", "null" ] }, "frame_kind": { "type": [ "string", "null" ] }, "verb": { "type": [ "string", "null" ] }, "stance": { "type": [ "string", "null" ] }, "lifecycle": { "type": "string" }, "public_research": { "type": "object", "required": [ "provider", "response_id", "generated_at", "status", "parts", "search_calls" ], "properties": { "provider": { "type": "string", "const": "azure_bing" }, "response_id": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "completed", "no_cited_sources" ] }, "search_calls": { "type": "integer" }, "parts": { "type": "array", "items": { "type": "object", "required": [ "text", "citations" ], "properties": { "text": { "type": "string" }, "citations": { "type": "array", "items": { "type": "object", "required": [ "url", "title", "start_index", "end_index" ], "properties": { "url": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" } } } } } } } } } } }, "changed": { "type": "boolean" } } } } } }, "400": { "description": "Invalid selector, ontology or command." }, "401": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "403": { "description": "Source access, human review or publication permission denied." }, "404": { "description": "Subject, case or source absent or inaccessible." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "HS256-signed JWT in the `Authorization: Bearer ` header.\n\nSame shape as the payments service (see\n[yieldfabric-payments/docs/api/components/securitySchemes.yaml](../../../yieldfabric-payments/docs/api/components/securitySchemes.yaml)\nfor the full claim reference). Key facts for the agents service:\n\n- **Algorithm**: HS256 with shared `JWT_SECRET` (same secret as payments).\n- **Required claims**: `sub` (entity id), `aud` (must include an audience the agents service accepts — same convention as payments), `exp`, `iat`, `role`.\n- **Optional claims** include `acting_as` for delegation, `account_address`, `default_chain_id`, `default_wallet_id`, `delegation_scope`, `delegation_token_id`.\n- **Delegation** is a JWT claim, NOT an HTTP header.\n\nTokens are minted by `yieldfabric-auth`; that service is out of scope for\nthis spec. Once you have a valid JWT it works against the agents REST API,\nthe agents GraphQL subgraph (agents.yieldfabric.com), and the federated gateway (api.yieldfabric.com) interchangeably.\n" } }, "parameters": { "GroupId": { "name": "id", "in": "path", "required": true, "description": "Working-group id (UUID).", "schema": { "type": "string", "format": "uuid" } }, "MemberId": { "name": "mid", "in": "path", "required": true, "description": "Member id (UUID).", "schema": { "type": "string", "format": "uuid" } }, "DocumentId": { "name": "docid", "in": "path", "required": true, "description": "Document id (UUID).", "schema": { "type": "string", "format": "uuid" } }, "WorkflowId": { "name": "wid", "in": "path", "required": true, "description": "Workflow instance id (UUID).", "schema": { "type": "string", "format": "uuid" } }, "StepKey": { "name": "step_key", "in": "path", "required": true, "description": "Workflow-step key (string from the workflow definition).", "schema": { "type": "string" } }, "ThreadId": { "name": "tid", "in": "path", "required": true, "description": "Thread id (UUID).", "schema": { "type": "string", "format": "uuid" } }, "IntentId": { "name": "intent_id", "in": "path", "required": true, "description": "Intent id (UUID).", "schema": { "type": "string", "format": "uuid" } }, "PipelineRunId": { "name": "run_id", "in": "path", "required": true, "description": "Pipeline run id (UUID).", "schema": { "type": "string", "format": "uuid" } }, "ProcessingTier": { "name": "processing_tier", "in": "query", "required": false, "description": "Maximum processing depth for this ingest. `store_only` retains the\nencrypted source and document metadata without creating a retrieval\nindex; `vector` additionally chunks and embeds the current document\ngeneration for low-cost discovery/RAG; `full` additionally extracts and\npublishes its knowledge graph. Omission preserves the pre-tier behavior\nand is therefore equivalent to `full`. Bulk-upload clients that want\ninexpensive discovery should send `processing_tier=vector` explicitly.\n", "schema": { "type": "string", "enum": [ "store_only", "vector", "full" ], "default": "full", "description": "Maximum processing depth for a document-ingest run. Capabilities are\nmonotonic: `store_only` persists the source and metadata; `vector` adds\nchunks and embeddings; `full` adds graph extraction. The default is\n`full` for compatibility with callers that predate tier selection.\n" } }, "AgentId": { "name": "id", "in": "path", "required": true, "description": "Agent id (UUID or slug).", "schema": { "type": "string" } }, "KgId": { "name": "kg_id", "in": "path", "required": true, "description": "Knowledge-graph id.", "schema": { "type": "string" } }, "ChunkId": { "name": "chunk_id", "in": "path", "required": true, "description": "Chunk id (UUID).", "schema": { "type": "string", "format": "uuid" } }, "Limit": { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50 } }, "Cursor": { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor from the previous page's `pageInfo.endCursor`.", "schema": { "type": "string" } }, "SinceTs": { "name": "since", "in": "query", "required": false, "description": "Lower bound timestamp (ISO-8601). Items strictly after `since` are returned.", "schema": { "type": "string", "format": "date-time" } } }, "responses": { "BadRequest": { "description": "Malformed request, invalid field, or validation failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "invalid-field": { "summary": "Validation failure", "value": { "error": { "code": "BAD_REQUEST", "message": "field 'name' is required" } } } } } } }, "Unauthorized": { "description": "Missing, malformed, expired, or wrong-audience bearer JWT.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "examples": { "no-token": { "summary": "Missing header", "value": { "error": { "code": "UNAUTHORIZED", "message": "missing bearer token" } } }, "expired": { "summary": "Token expired", "value": { "error": { "code": "UNAUTHORIZED", "message": "token expired" } } } } } } }, "Forbidden": { "description": "Authenticated but the JWT does not have access to the target resource (wrong role, not a group member, federation policy denies the read, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "NotFound": { "description": "Resource not found (working group, workflow, thread, agent, KG, document, intent, ...).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "Conflict": { "description": "Conflicting state (e.g. step already completed, intent already cancelled, duplicate idempotency key with different body).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "ChainAccountRequired": { "description": "The effective user or group has no activated smart account on the\nauthenticated session's selected chain. The handler returns this before\nthe gated operation performs a durable write, submits MQ work, or starts\nan on-chain action. Activate the exact returned entity and chain, refresh\nthe same actor's session, then retry the original request once.\n", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "error", "code", "entity_kind", "entity_id", "chain_id", "operation" ], "properties": { "error": { "type": "string", "description": "Human-readable explanation. Branch on `code`, not this text." }, "code": { "type": "string", "const": "CHAIN_ACCOUNT_REQUIRED" }, "entity_kind": { "type": "string", "enum": [ "user", "group" ] }, "entity_id": { "type": "string", "minLength": 1 }, "chain_id": { "type": "string", "minLength": 1, "description": "Chain selected by the authenticated session." }, "operation": { "type": [ "string", "null" ], "description": "Stable operation label that required the account." } } }, "example": { "error": "A smart account must be activated on the selected chain before this operation can continue", "code": "CHAIN_ACCOUNT_REQUIRED", "entity_kind": "user", "entity_id": "usr_alice", "chain_id": "153", "operation": "start_workflow" } } } }, "InternalError": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "SseStream": { "description": "Server-Sent Events stream. Each event is framed as `event: \\ndata: \\n\\n`\n(chat + workflow streams) or `data: {\"type\":\"\", ...}\\n\\n` (pipeline stream\nwhere the typed enum is serialized directly per `#[serde(tag = \"type\")]`).\nSee the operation's `x-event-types` array for the full enumeration of event\nvariants and their data schemas. There is no `?last_message_ts=` resume\ncursor on chat/workflow streams today; the pipeline stream replays its in-memory\nlog on every (re)subscribe.\n", "content": { "text/event-stream": { "schema": { "type": "object", "description": "Each SSE event has an `event` name (the wire-level `event:` line) and a\n`data` JSON payload (the wire-level `data:` line, JSON-decoded). The exact\nschemas for each event variant are documented in the operation's\n`x-event-types` extension.\n", "required": [ "event", "data" ], "properties": { "event": { "type": "string", "description": "Event name from the operation's `x-event-types` enumeration." }, "data": { "description": "JSON payload. Shape depends on `event` — see `x-event-types`." }, "id": { "type": [ "string", "null" ], "description": "Optional SSE event id (used for resume cursors)." } } } } } }, "InferenceLimited": { "description": "Per-entity concurrency, per-entity recent starts, or instance capacity exceeded. Retry after the indicated number of seconds.", "headers": { "Retry-After": { "description": "Suggested retry delay in seconds; capacity may still be busy at retry time.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "inference_limit" ] } } } } } }, "OpenaiInferenceLimited": { "description": "Inference admission exceeded. The OpenAI error type is rate_limit_error and code is inference_limit.", "headers": { "Retry-After": { "description": "Suggested retry delay in seconds.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "description": "OpenAI-style error envelope used by every /v1 response ≥ 400 (including the middleware's 401s).", "properties": { "error": { "type": "object", "required": [ "message", "type" ], "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "billing_error", "api_error" ] }, "param": { "type": [ "string", "null" ] }, "code": { "type": [ "string", "null" ], "description": "Stable billing recovery reason on a 402 (`card_required`, `credit_plan_required`, `credit_exhausted`, or `billing_paused`); null for non-billing errors." } } } } } } } } }, "schemas": { "ErrorBody": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } } } }, "ErrorCode": { "type": "string", "description": "Structured error code returned in `error.code`. See\n[guides/errors.md](../guides/errors.md) for the full catalogue with\nrecovery strategies.\n", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "IDEMPOTENCY_CONFLICT", "VALIDATION_FAILED", "WORKFLOW_STATE_INVALID", "INTENT_STATE_INVALID", "PIPELINE_STATE_INVALID", "GROUP_NOT_FOUND", "MEMBER_NOT_FOUND", "FEDERATION_DENIED", "RAG_FAILED", "LLM_FAILED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "PaginationInput": { "type": "object", "properties": { "cursor": { "type": [ "string", "null" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50 } } }, "PageInfo": { "type": "object", "required": [ "hasNextPage" ], "properties": { "endCursor": { "type": [ "string", "null" ] }, "hasNextPage": { "type": "boolean" } } }, "SseEnvelope": { "type": "object", "description": "Each SSE event has an `event` name (the wire-level `event:` line) and a\n`data` JSON payload (the wire-level `data:` line, JSON-decoded). The exact\nschemas for each event variant are documented in the operation's\n`x-event-types` extension.\n", "required": [ "event", "data" ], "properties": { "event": { "type": "string", "description": "Event name from the operation's `x-event-types` enumeration." }, "data": { "description": "JSON payload. Shape depends on `event` — see `x-event-types`." }, "id": { "type": [ "string", "null" ], "description": "Optional SSE event id (used for resume cursors)." } } } } }, "security": [ { "bearerAuth": [] } ], "x-yf-service": "agents" }