{"openapi":"3.0.3","info":{"title":"Cencori Embedded Agents","version":"1.0.0","description":"The multi-tenant agent backend for SaaS products. Discover models, connect providers, create tenants, install agents, attach knowledge and tools, run safely, and meter every interaction through one API."},"servers":[{"url":"https://cencori.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Project secret (csk_*) for server ops; short-lived client token (ect_*) for browser execution."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"param":{"type":"string"}}}}},"Tenant":{"type":"object","properties":{"id":{"type":"string","example":"ten_abc"},"external_id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","suspended","deleting","deleted"]},"region":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"}}},"UnifiedModel":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","example":"model"},"created":{"type":"integer"},"owned_by":{"type":"string"},"name":{"type":"string"},"provider":{"type":"string"},"source":{"type":"string","enum":["cencori","byok","custom"]},"connection_id":{"type":"string","nullable":true},"types":{"type":"array","items":{"type":"string"}},"context_window":{"type":"integer"},"status":{"type":"string"},"available":{"type":"boolean"},"unavailable_reason":{"type":"string","nullable":true},"pricing_status":{"type":"string"}}},"Run":{"type":"object","properties":{"id":{"type":"string","example":"run_abc"},"agent_id":{"type":"string"},"status":{"type":"string","enum":["queued","running","requires_action","completed","failed","cancelled","expired"]},"input":{"type":"object"},"output":{"type":"object","nullable":true}}},"Action":{"type":"object","properties":{"id":{"type":"string","example":"act_abc"},"tool":{"type":"string"},"risk_level":{"type":"string"},"status":{"type":"string"},"arguments":{"type":"object"}}}}},"paths":{"/v1/actions":{"post":{"summary":"Create approval-gated action","responses":{"201":{"description":"Action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Action"}}}}}}},"/v1/actions/{actionId}":{"get":{"summary":"Get action (sanitized)","responses":{"200":{"description":"Action"}}}},"/v1/actions/{actionId}/approve":{"post":{"summary":"Approve (idempotent, executes once)","responses":{"200":{"description":"Approved"}}}},"/v1/actions/{actionId}/reject":{"post":{"summary":"Reject (idempotent)","responses":{"200":{"description":"Rejected"}}}},"/v1/agent-catalog":{"get":{"summary":"Published catalog (default public + unlisted)","responses":{"200":{"description":"Catalog"}}}},"/v1/agent-installations":{"get":{"summary":"List installations","responses":{"200":{"description":"List"}}},"post":{"summary":"Install agent for tenant","responses":{"201":{"description":"Installation"}}}},"/v1/agent-installations/{installationId}":{"get":{"summary":"Get installation","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."},"patch":{"summary":"Update installation overlays/policy","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."},"delete":{"summary":"Disable installation","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/agent-installations/{installationId}/rollback":{"post":{"summary":"Roll back installation version","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/agent-installations/{installationId}/upgrade":{"post":{"summary":"Upgrade installation version","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/agents":{"get":{"summary":"List gateway agents","responses":{"200":{"description":"OK"}},"description":"Secret project key or dashboard session (project members)."},"post":{"summary":"Create gateway agent","responses":{"200":{"description":"OK"}},"description":"Secret project key or dashboard session (project members)."}},"/v1/agents/{agentId}":{"get":{"summary":"Get agent","responses":{"200":{"description":"OK"}},"description":"Secret project key or dashboard session (project members)."},"patch":{"summary":"Update agent","responses":{"200":{"description":"OK"}},"description":"Secret project key or dashboard session (project members)."},"delete":{"summary":"Delete agent","responses":{"200":{"description":"OK"}},"description":"Secret project key or dashboard session (project members)."}},"/v1/agents/{agentId}/keys":{"post":{"summary":"Mint an agent-scoped key (dashboard owners only)","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/agents/{agentId}/runs":{"post":{"summary":"Create background run (idempotent)","responses":{"202":{"description":"Run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"}}}}}}},"/v1/agents/{agentId}/versions":{"get":{"summary":"List agent versions","responses":{"200":{"description":"List"}}},"post":{"summary":"Create agent version draft","responses":{"201":{"description":"Version"}}}},"/v1/agents/{agentId}/versions/{version}":{"get":{"summary":"Get agent version","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/agents/{agentId}/versions/{version}/deprecate":{"post":{"summary":"Deprecate version","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/agents/{agentId}/versions/{version}/publish":{"post":{"summary":"Publish (self-serve fast path)","responses":{"200":{"description":"Published"}}}},"/v1/agents/{agentId}/versions/{version}/retire":{"post":{"summary":"Retire version","responses":{"200":{"description":"Retired"}}}},"/v1/agents/{agentId}/versions/{version}/review":{"post":{"summary":"Review (approve → published, reject → draft)","responses":{"200":{"description":"Reviewed"}}}},"/v1/agents/{agentId}/versions/{version}/submit":{"post":{"summary":"Submit for review","responses":{"200":{"description":"In review"}}}},"/v1/agents/{agentId}/versions/{version}/test":{"post":{"summary":"Sandboxed model test and capability readiness check (capped tokens)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"input":{"type":"string","maxLength":2000},"test_connection_ids":{"type":"array","items":{"type":"string"},"description":"Active project-scoped test_only connections used to verify declared connector scopes; credentials are not exercised."}}}}}},"responses":{"200":{"description":"OK"},"422":{"description":"Manifest or declared capability prerequisites are unavailable"}},"description":"Requires a secret project key (`secret_key_required` otherwise). Stores pass/fail evidence on the draft version. Only the model is executed; skills, connectors, and MCP references are checked for readiness without invoking external tools."}},"/v1/agents/{agentId}/versions/{version}/validate":{"post":{"summary":"Validate draft (no side effects)","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/client-tokens":{"post":{"summary":"Mint browser-safe token (secret-key only, 15-min max)","responses":{"201":{"description":"Token"}}}},"/v1/connections":{"get":{"summary":"List tool connections (no secrets)","responses":{"200":{"description":"List"}}},"post":{"summary":"Create tool connection (secret-key only)","responses":{"201":{"description":"Created"}}}},"/v1/connections/oauth/callback":{"get":{"summary":"OAuth redirect (state-signed, public, no key)","responses":{"200":{"description":"Connected"}}}},"/v1/connections/{connectionId}":{"get":{"summary":"Get tool connection (no secrets)","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."},"patch":{"summary":"Update tool connection","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."},"delete":{"summary":"Revoke tool connection","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/connections/{connectionId}/authorize":{"post":{"summary":"Start OAuth consent (returns authorize_url)","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/connections/{connectionId}/refresh":{"post":{"summary":"Rotate access token","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/connections/{connectionId}/test":{"post":{"summary":"Connection health check","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/connectors":{"get":{"summary":"Connector catalog","responses":{"200":{"description":"Catalog"}}}},"/v1/connectors/{connectorId}":{"get":{"summary":"Get connector type","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/end-users":{"get":{"summary":"List end users (secret-key)","responses":{"200":{"description":"List"}}},"post":{"summary":"Upsert end user (secret-key)","responses":{"201":{"description":"User"}}}},"/v1/knowledge-bases":{"get":{"summary":"List knowledge bases","responses":{"200":{"description":"List"}}},"post":{"summary":"Create knowledge base","responses":{"201":{"description":"Created"}}}},"/v1/knowledge-bases/{knowledgeBaseId}":{"get":{"summary":"Get knowledge base","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."},"patch":{"summary":"Update knowledge base","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."},"delete":{"summary":"Delete knowledge base + chunks","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/knowledge-bases/{knowledgeBaseId}/grants":{"post":{"summary":"Grant knowledge base","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."},"get":{"summary":"List grants","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/knowledge-bases/{knowledgeBaseId}/grants/{grantId}":{"delete":{"summary":"Revoke grant","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/knowledge-bases/{knowledgeBaseId}/search":{"post":{"summary":"Grant-filtered search with citations","responses":{"200":{"description":"Hits"}}}},"/v1/knowledge-bases/{knowledgeBaseId}/sources":{"post":{"summary":"Ingest inline text or file","responses":{"201":{"description":"Source"}}},"get":{"summary":"List sources","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/knowledge-bases/{knowledgeBaseId}/sources/{sourceId}":{"get":{"summary":"Get source","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."},"delete":{"summary":"Delete source + chunks","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/knowledge-bases/{knowledgeBaseId}/sources/{sourceId}/sync":{"post":{"summary":"Re-ingest source (checksum-idempotent)","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/mcp/servers":{"post":{"summary":"Register remote MCP server + discover","responses":{"201":{"description":"Server"}}},"get":{"summary":"List registered MCP servers","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/mcp/servers/{serverId}":{"get":{"summary":"Get MCP server","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."},"patch":{"summary":"Update MCP server (URL re-validated)","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."},"delete":{"summary":"Disable MCP server","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/mcp/servers/{serverId}/refresh-tools":{"post":{"summary":"Re-discover MCP tools (diff)","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/mcp/servers/{serverId}/test":{"post":{"summary":"Live handshake probe (not persisted)","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/mcp/servers/{serverId}/tools":{"get":{"summary":"Stored tool snapshot","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/models":{"get":{"summary":"Unified model registry (only discovery surface)","parameters":[{"name":"provider","in":"query","schema":{"type":"string"}},{"name":"type","in":"query","schema":{"type":"string"}},{"name":"available","in":"query","schema":{"type":"boolean"}},{"name":"source","in":"query","schema":{"type":"string","enum":["cencori","byok","custom"]}},{"name":"connection_id","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Registry"}}}},"/v1/provider-connections":{"get":{"summary":"List provider connections","responses":{"200":{"description":"List"}}},"post":{"summary":"Create provider connection (secret-key only)","responses":{"201":{"description":"Created"}}}},"/v1/provider-connections/validate":{"post":{"summary":"Ephemeral provider validation","responses":{"200":{"description":"Valid"}}}},"/v1/provider-connections/{connectionId}":{"get":{"summary":"Get provider connection","responses":{"200":{"description":"Connection"}}},"patch":{"summary":"Update provider connection","responses":{"200":{"description":"Updated"}}},"delete":{"summary":"Delete provider connection","responses":{"200":{"description":"Deleted"}}}},"/v1/provider-connections/{connectionId}/model-syncs":{"post":{"summary":"Preview model sync","responses":{"201":{"description":"Preview"}}}},"/v1/provider-connections/{connectionId}/model-syncs/{syncId}":{"get":{"summary":"Get model sync preview","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/provider-connections/{connectionId}/model-syncs/{syncId}/apply":{"post":{"summary":"Apply model sync (idempotent)","responses":{"200":{"description":"Applied"}}}},"/v1/provider-connections/{connectionId}/test":{"post":{"summary":"Test saved connection","responses":{"200":{"description":"Result"}}}},"/v1/rate-plans":{"get":{"summary":"List rate plans (secret-key)","responses":{"200":{"description":"List"}}},"post":{"summary":"Create rate plan (secret-key)","responses":{"201":{"description":"Plan"}}}},"/v1/runs/{runId}":{"get":{"summary":"Get run","responses":{"200":{"description":"Run"}}}},"/v1/runs/{runId}/cancel":{"post":{"summary":"Cancel run","responses":{"200":{"description":"Cancelled"}}}},"/v1/runs/{runId}/delegate":{"post":{"summary":"Delegate a bounded task to an allowed subagent","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agent_version_id"],"properties":{"agent_version_id":{"type":"string"},"input":{},"installation_id":{"type":"string","description":"Optional active installation owned by the same project and tenant and serving the child agent."}}}}}},"responses":{"201":{"description":"Child run claimed or idempotent prior result"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/runs/{runId}/events":{"get":{"summary":"Run event log","responses":{"200":{"description":"Events"}}}},"/v1/sessions":{"get":{"summary":"List sessions (tenant+user scoped for ect_)","responses":{"200":{"description":"OK"}}},"post":{"summary":"Create scoped session (csk_* or ect_)","responses":{"201":{"description":"Created"}}}},"/v1/sessions/{sessionId}":{"get":{"summary":"Get session (scope-checked)","responses":{"200":{"description":"OK"}}},"delete":{"summary":"Delete session","responses":{"200":{"description":"OK"}}}},"/v1/sessions/{sessionId}/approve":{"post":{"summary":"Approve paused tool call (secret-key)","responses":{"200":{"description":"SSE stream"}}}},"/v1/sessions/{sessionId}/events":{"get":{"summary":"Session event replay (secret-key)","responses":{"200":{"description":"OK"}}}},"/v1/sessions/{sessionId}/reject":{"post":{"summary":"Reject paused tool call (secret-key)","responses":{"200":{"description":"OK"}}}},"/v1/sessions/{sessionId}/turns":{"post":{"summary":"Submit turn (csk_* or ect_ with sessions:turn)","responses":{"200":{"description":"SSE stream"}}}},"/v1/skill-imports":{"post":{"summary":"Stage an import (one source, never auto-publishes)","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/skill-imports/{importId}":{"get":{"summary":"Get staged import with findings","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/skill-imports/{importId}/publish":{"post":{"summary":"Review-gate publish of a staged import","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/skills":{"get":{"summary":"List skills","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."},"post":{"summary":"Create skill identity","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/skills/{skillId}":{"get":{"summary":"Get skill","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."},"patch":{"summary":"Update skill metadata","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/skills/{skillId}/versions":{"get":{"summary":"List skill versions","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."},"post":{"summary":"Draft skill version (scanned)","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/skills/{skillId}/versions/{version}":{"get":{"summary":"Get skill version with content","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/skills/{skillId}/versions/{version}/deprecate":{"post":{"summary":"Deprecate skill version","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/skills/{skillId}/versions/{version}/publish":{"post":{"summary":"Publish skill version (blockers reject)","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/tenants":{"get":{"summary":"List tenants","responses":{"200":{"description":"List"}}},"post":{"summary":"Create/upsert tenant (idempotent by external_id)","responses":{"201":{"description":"Tenant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Tenant"}}}}}}},"/v1/tenants/{tenantId}":{"get":{"summary":"Get tenant","responses":{"200":{"description":"Tenant"}}},"patch":{"summary":"Update tenant","responses":{"200":{"description":"Tenant"}}},"delete":{"summary":"Hard-delete tenant (cascades)","responses":{"200":{"description":"Deleted"}}}},"/v1/tenants/{tenantId}/export":{"post":{"summary":"Export tenant data (compliance)","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/tenants/{tenantId}/users":{"get":{"summary":"List tenant users","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/tenants/{tenantId}/users/{externalUserId}":{"put":{"summary":"Upsert user","responses":{"201":{"description":"User"}}},"get":{"summary":"Get user","responses":{"200":{"description":"User"}}},"delete":{"summary":"Delete user (?hard=true forgets)","responses":{"200":{"description":"Deleted"}}},"patch":{"summary":"Update user","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/usage":{"get":{"summary":"Usage summary by tenant/agent/installation","responses":{"200":{"description":"Summary"}}}},"/v1/usage/events":{"get":{"summary":"Attributed request rows (cursor)","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/usage/export":{"get":{"summary":"Invoice export (csv|json)","responses":{"200":{"description":"Export"}}}},"/v1/webhook-deliveries":{"get":{"summary":"Delivery log","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}},"/v1/webhook-deliveries/{deliveryId}/replay":{"post":{"summary":"Replay a delivery","responses":{"200":{"description":"Replayed"}}}},"/v1/webhooks":{"get":{"summary":"List webhook subscriptions","responses":{"200":{"description":"List"}}},"post":{"summary":"Create webhook subscription","responses":{"201":{"description":"Created"}}}},"/v1/webhooks/{webhookId}":{"patch":{"summary":"Update webhook subscription","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."},"delete":{"summary":"Delete webhook subscription","responses":{"200":{"description":"OK"}},"description":"Requires a secret project key (`secret_key_required` otherwise)."}}}}