{ "openapi": "3.1.1", "info": { "title": "Tracon HTTP API", "description": "The control plane Tracon maps into an ASP.NET Core application. Every path below is relative to the prefix passed to MapTracon, which is '/tracon' in this document. The Tracon packages do not generate this document themselves; it is produced by calling AddOpenApi in the host application, so the title, the version, and the server list in YOUR document come from YOUR application.", "version": "v1" }, "servers": [ { "url": "http://localhost:5081", "description": "The address the `dotnet new tracon-api` template listens on by default." } ], "paths": { "/tracon/api/meta": { "get": { "tags": [ "Tracon", "Meta" ], "summary": "Reports the Tracon version, authentication method, active stores, and role authorizations.", "description": "Requires no authentication. Contains no secret, tenant data, or agent information.", "operationId": "TraconMeta", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraconMetaResponse" } } } } }, "security": [] } }, "/tracon/api/agents": { "get": { "tags": [ "Tracon", "Agents" ], "summary": "Lists all agents defined in code and in the database.", "description": "The list merges every registered agent source into a single view, ordered by name. When two sources hold the same name, the source with the higher priority wins and the other one is dropped from the list — code definitions win over database definitions. The response is not paged; the number of agents is bounded by the control plane, not by traffic. Each entry carries the origin, so a client can tell an editable definition from a code-defined one.", "operationId": "TraconListAgents", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AgentDescriptor" } } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "AgentsRead" }, "post": { "tags": [ "Tracon", "Agents" ], "summary": "Creates a new agent definition.", "description": "The definition is fully validated before it is stored: the model binding, every tool, skill, and callable agent must already exist, and the call graph must be free of cycles. A failed check returns 400 and nothing is written. A name that another definition already uses returns 409; a name that a code-defined agent already uses also returns 409, because code wins name conflicts and the stored definition would never resolve. On success the response is 201 with the saved definition at version 1 and a Location header pointing at it.", "operationId": "TraconCreateAgent", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentDefinitionRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentDefinition" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "AgentsAdmin" } }, "/tracon/api/agents/{name}": { "get": { "tags": [ "Tracon", "Agents" ], "summary": "Returns an agent's catalog summary and its persisted definition, if any.", "description": "A code-defined agent has no STORED definition, so 'isEditable' is always false for it — code is changed by changing the application, not through this API. A code agent declared declaratively (AddAgent(AgentDefinition)) still returns its full in-memory definition in 'definition', including 'instructions'; only a code agent built from a factory (AddAgent(name, factory)) has 'definition' as null, since there is no AgentDefinition to return for one. For a factory agent whose concrete type exposes instructions (currently only Microsoft.Agents.AI.ChatClientAgent), 'factoryInstructions' carries a best-effort read of them instead; it is null when the type does not expose them or reading them failed. 'isEditable' is the single field a client checks before offering an edit form — it is true only when the agent's origin is the database.", "operationId": "TraconGetAgent", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentDetailResponse" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "AgentsRead" }, "put": { "tags": [ "Tracon", "Agents" ], "summary": "Updates an agent definition and produces a new version.", "description": "An agent's name is immutable: when the path name and the body name differ the response is 400. A code-defined name returns 409 — code definitions are validated at compile time and are changed by changing the application. The same existence and call-graph checks as create apply, and a failed check writes nothing. Every successful save appends a version rather than overwriting; the previous content stays readable through the version history.", "operationId": "TraconUpdateAgent", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentDefinitionRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentDefinition" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "AgentsAdmin" }, "delete": { "tags": [ "Tracon", "Agents" ], "summary": "Deletes an agent definition and its version history.", "description": "The delete removes the current definition together with every stored version; it is not a soft delete and there is no rollback afterwards. A code-defined name returns 409. A name with no stored definition returns 404, so the call is not idempotent across repeats. Runs already recorded for the agent are kept — the run history does not depend on the definition still existing.", "operationId": "TraconDeleteAgent", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "AgentsAdmin" } }, "/tracon/api/agents/validate": { "post": { "tags": [ "Tracon", "Agents" ], "summary": "Compiles a definition without saving it and without calling any model.", "description": "A validation failure is NOT an HTTP error. When the body is well-formed the response is always 200 and the outcome is carried in the report's 'valid' field, with one message per finding. 400 is returned only when the body itself cannot be read or the required name/model fields are missing — that is the single case a pipeline needs in order to tell a transport error from a rejected definition. No model provider is contacted and nothing is written.", "operationId": "TraconValidateAgent", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentDefinitionRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentValidationReport" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "AgentsAdmin" } }, "/tracon/api/agents/{name}/versions": { "get": { "tags": [ "Tracon", "Agents" ], "summary": "Lists a definition's version history, newest first.", "description": "Every entry is a full definition snapshot, not a delta, so a single entry is enough to inspect or restore a past state. The agent must have a current stored definition; a code-defined or deleted name returns 404. Code agents have no version history at all — their history is the application's source history.", "operationId": "TraconListAgentVersions", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AgentDefinition" } } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "AgentsRead" } }, "/tracon/api/agents/{name}/rollback": { "post": { "tags": [ "Tracon", "Agents" ], "summary": "Writes a definition as a new version with the content of a previous version.", "description": "A rollback moves forward, not backward: the old content is appended as a NEW version and the history is never rewritten, so the rollback itself stays auditable and can be rolled back in turn. An unknown version number returns 404; a code-defined name returns 409.", "operationId": "TraconRollbackAgent", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRollbackRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentDefinition" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "AgentsAdmin" } }, "/tracon/api/agents/{name}/versions/{a}/diff/{b}": { "get": { "tags": [ "Tracon", "Agents" ], "summary": "Returns two definition versions as raw JSON; the diff is computed in the UI.", "description": "The server does no diffing and takes no position on how a change should be displayed; it returns both snapshots verbatim as 'left' and 'right' so the client chooses the presentation. The two version numbers may be given in any order. When either version is missing the response is 404 and names the one that was not found.", "operationId": "TraconGetAgentVersionDiff", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "a", "in": "path", "required": true, "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": "integer", "format": "int32" } }, { "name": "b", "in": "path", "required": true, "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentVersionDiffResponse" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "AgentsRead" } }, "/tracon/api/agents/{name}/run": { "post": { "tags": [ "Tracon", "Agents" ], "summary": "Runs an agent for trial purposes and streams the response via SSE.", "description": "If the quota is exceeded, the run does not start and a 429 is returned; the ProblemDetails carries which quota was exceeded and when the counter resets. When the pre-flight context-window check is enabled (disabled by default) and the prompt is estimated to exceed the model's window, the run does not start and a 400 is returned with the estimated and allowed token counts; no call reaches the provider. A request carrying the 'Idempotency-Key' header runs with a single JSON response (non-streaming) instead of SSE, because a replayed response cannot be reconstructed from a stream. A request carrying the 'Prefer: respond-async' header queues the run and returns '202 Accepted' with a 'Location' header. If a registered IContentGuard blocks the content, the non-streaming response returns '422' and the run's error type becomes 'content_blocked'; in the STREAMING response the status code has already been sent, so the block arrives as an SSE 'error' event instead. If a registered IRunAuthorizationHandler denies the caller, the run does not start and a 403 is returned; this check runs before the quota check, so a denied run never consumes the tenant's quota.When session ownership is turned on, naming another user's session in 'sessionId' is also refused with 403, and opening a NEW session is refused the same way when no authenticated identity can be resolved to own it ('errorType': 'session_owner_required').", "operationId": "TraconRunAgent", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRunRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedRunResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "501": { "description": "Not Implemented", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "RunsWrite" } }, "/tracon/api/agents/{name}/estimate": { "post": { "tags": [ "Tracon", "Agents" ], "summary": "Estimates a prompt's token count against the agent's model, without calling the provider.", "description": "The diagnostic surface of the pre-flight context-window check: it returns the same numbers the check on 'POST /api/agents/{name}/run' would use, regardless of whether that check is enabled. No model provider is ever contacted. The estimate is approximate — it uses a fixed reference tokenizer, not the bound provider's own count. 'contextWindowTokens' and 'allowedPromptTokens' are null when the agent's model is not found in the catalog; in that case 'wouldBeRejected' is always false, since an unknown window can never be exceeded.", "operationId": "TraconEstimateContextWindow", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRunRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextWindowEstimate" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "RunsRead" } }, "/tracon/api/attachments": { "post": { "tags": [ "Tracon", "Attachments" ], "summary": "Uploads a new attachment.", "description": "The body must be 'multipart/form-data' and must carry a 'file' field. The type is validated by magic bytes, not by the Content-Type the client reports. If a registered IRunAuthorizationHandler denies the caller, the response is 403.", "operationId": "TraconUploadAttachment", "parameters": [ { "name": "sessionId", "in": "query", "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "type": "object", "properties": { "file": { "$ref": "#/components/schemas/IFormFile" } } } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentDescriptor" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "RunsWrite" }, "get": { "tags": [ "Tracon", "Attachments" ], "summary": "Lists attachments.", "description": "Only descriptors are returned — file name, media type, size, and content hash — never the bytes; fetch those from the download endpoint. 'sessionId' narrows the list to one session, and attachments uploaded without a session are reachable only without that filter. Paging is offset based: 'skip' defaults to 0, 'take' to 50, and 'take' is clamped to 1..200 instead of being rejected. If a registered IRunAuthorizationHandler denies the caller, the response is 403 — the list is REJECTED, never silently filtered.", "operationId": "TraconListAttachments", "parameters": [ { "name": "sessionId", "in": "query", "schema": { "type": "string" } }, { "name": "skip", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "take", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AttachmentDescriptor" } } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "RunsRead" } }, "/tracon/api/attachments/{id}": { "get": { "tags": [ "Tracon", "Attachments" ], "summary": "Streams the raw content of an attachment.", "description": "The response carries the attachment's own stored media type, an ETag holding the content's SHA-256, and 'Content-Disposition: attachment' together with 'X-Content-Type-Options: nosniff' — a browser therefore downloads the bytes instead of rendering them, so uploaded HTML can never execute in the console's origin. The token travels in the Authorization header, so a browser cannot use this URL directly as an image or audio element source; fetch the bytes and wrap them in an object URL instead. If a registered IRunAuthorizationHandler denies the caller, the response is 404, identical to an attachment that does not exist.", "operationId": "TraconDownloadAttachment", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/octet-stream": { "schema": { "$ref": "#/components/schemas/Stream" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "RunsRead" }, "delete": { "tags": [ "Tracon", "Attachments" ], "summary": "Deletes an attachment.", "description": "The bytes are removed immediately; there is no soft delete. Messages that already reference the attachment keep the reference and it stops resolving, so delete an attachment only when its conversation no longer needs to be replayed. Deleting the owning session removes its attachments as well, which is usually the call to reach for. An unknown id returns 404, and so does a denial by a registered IRunAuthorizationHandler.", "operationId": "TraconDeleteAttachment", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No Content" } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "RunsWrite" } }, "/tracon/api/skills": { "get": { "tags": [ "Tracon", "Skills" ], "summary": "Lists the tenant's skills.", "description": "Skills are scoped to the calling tenant; a skill defined for another tenant is never returned. Each entry is complete — instructions, resources, and scripts come with it, so a client does not need a second call per skill. The response is not paged.", "operationId": "TraconListSkills", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSkillDefinition" } } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "AgentsRead" } }, "/tracon/api/skills/{name}": { "get": { "tags": [ "Tracon", "Skills" ], "summary": "Returns a single skill and its resources.", "description": "The response carries the skill's instructions together with every resource and script attached to it, including their content. Names are compared exactly, case included; an unknown name returns 404.", "operationId": "TraconGetSkill", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSkillDefinition" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "AgentsRead" }, "put": { "tags": [ "Tracon", "Skills" ], "summary": "Creates or updates a skill.", "description": "The call replaces the whole skill: resources and scripts that the body omits are removed. A first save answers 201, a later one 200. The path name and the body name must be identical (400 otherwise). Name, description, and compatibility follow the skill frontmatter rules, and instructions, resources, and scripts are each bounded by the configured size limits. A script may be SAVED even when script execution is turned off — saving and running are separate permissions — but an extension with no registered interpreter is rejected, because such a script could never run and would leave dead data behind.", "operationId": "TraconSaveSkill", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSkillRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSkillDefinition" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSkillDefinition" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "AgentsAdmin" }, "delete": { "tags": [ "Tracon", "Skills" ], "summary": "Deletes a skill and its cascading resources.", "description": "Resources and scripts are removed with the skill. Agent definitions that still name the skill are NOT rewritten, and they stop resolving: compiling such an agent fails with 'the skill was not found' until the reference is removed or the skill is recreated. Check the agents that use a skill before deleting it. An unknown name returns 404.", "operationId": "TraconDeleteSkill", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "AgentsAdmin" } }, "/tracon/api/skill-script-grants": { "get": { "tags": [ "Tracon", "Governance" ], "summary": "Lists the tenant's script run grants.", "description": "A grant is permission to execute code on the server, so this list is the authoritative answer to 'what may run here'. A grant with no script name covers every script in that skill; one with a script name covers only that script. Entries may carry an expiry, and an expired grant no longer authorizes a run. Grants are also a retention target, so old ones are cleaned up.", "operationId": "TraconListSkillScriptGrants", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkillScriptGrant" } } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "SecurityAdmin" }, "post": { "tags": [ "Tracon", "Governance" ], "summary": "Grants run permission to a skill script.", "description": "Granting while script execution is switched off returns 409 rather than succeeding: a grant that reads as active but never allows a run would be misleading. Omit 'scriptName' to cover every script in the skill. 'expiresAt' is optional but must be in the future when given (400 otherwise); without it the grant does not expire. Every change is written to the audit trail.", "operationId": "TraconGrantSkillScript", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillScriptGrantRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillScriptGrant" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "SecurityAdmin" } }, "/tracon/api/skill-script-grants/{skillName}": { "delete": { "tags": [ "Tracon", "Governance" ], "summary": "Revokes a script run grant.", "description": "Revoking takes effect on the next run; a script already executing is not stopped. The optional '?scriptName=' must match how the grant was created — revoking one script does not remove a skill-wide grant, and the skill-wide grant keeps authorizing that script until it too is revoked. When no matching active grant exists the response is 404.", "operationId": "TraconRevokeSkillScript", "parameters": [ { "name": "skillName", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "scriptName", "in": "query", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "SecurityAdmin" } }, "/tracon/api/sessions": { "get": { "tags": [ "Tracon", "Sessions" ], "summary": "Lists sessions from most recently updated to oldest.", "description": "Paging is offset based: 'skip' defaults to 0 and 'take' to 50, and 'take' is clamped to the 1..200 range rather than rejected, so an out-of-range value never fails the request. 'agentName' narrows the list to one agent. Because the order is by last update, a session that changes while a client pages can move between pages; use the session id, not the position, as the identity. If a registered IRunAuthorizationHandler denies the caller, the response is 403 — a denied list is REJECTED, never quietly shortened. When session ownership is turned on, the list is additionally narrowed to the calling user's own sessions before paging is applied, unless the caller satisfies the configured management policy; sessions written before ownership was turned on carry no owner and appear only in that management listing.", "operationId": "TraconListSessions", "parameters": [ { "name": "agentName", "in": "query", "schema": { "type": "string" } }, { "name": "skip", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "take", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SessionRecord" } } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "RunsRead" } }, "/tracon/api/sessions/{sessionId}": { "get": { "tags": [ "Tracon", "Sessions" ], "summary": "Returns a session's metadata and chat history.", "description": "'messages' is the readable chat history and is null when the configured session storage cannot expose one — with an in-memory setup the history lives inside an opaque state blob. 'state' always carries that raw provider state. Messages come back in sequence order, so the index of a message is the sequence number the branch endpoint expects. If a registered IRunAuthorizationHandler denies the caller, the response is 404 — identical to a session that does not exist, so a denial never confirms the session's existence. With session ownership turned on, another user's session answers the same 404.", "operationId": "TraconGetSession", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionDetailResponse" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "RunsRead" }, "delete": { "tags": [ "Tracon", "Sessions" ], "summary": "Deletes a session.", "description": "Attachments linked to the session are deleted with it, and this call is the only way they are cleaned up: an attachment may be uploaded before any session exists, so the link is deliberately not a database foreign key. The attachments are removed only after the session itself is found, so a 404 leaves no side effect. Runs recorded under the session are kept — run history does not depend on the session still existing. If a registered IRunAuthorizationHandler denies the caller, the response is also 404, identical to a session that does not exist; with session ownership turned on, another user's session answers that same 404 and is left untouched.", "operationId": "TraconDeleteSession", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "RunsWrite" } }, "/tracon/api/sessions/{sessionId}/branch": { "post": { "tags": [ "Tracon", "Sessions" ], "summary": "Branches a conversation from a specific point and opens a new session.", "description": "Items up to and including 'upToSequence' are COPIED into a NEW conversation; the pointer is only provenance information. Writing to the branch does not change the parent conversation. Branching only works while a persistent SQL provider is enabled; in an in-memory setup, chat history lives in an opaque blob of session state and this returns 501. If a registered IRunAuthorizationHandler denies the caller, the response is 404, identical to a session that does not exist; with session ownership turned on, another user's session answers that same 404. The new session inherits the SOURCE session's owner, not the caller's — a branch is a copy, not a handover.", "operationId": "TraconBranchSession", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionBranchRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionBranchResult" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "501": { "description": "Not Implemented", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "RunsWrite" } }, "/tracon/api/runs": { "get": { "tags": [ "Tracon", "Runs" ], "summary": "Lists runs from newest to oldest.", "description": "By default, ONLY root runs are returned. To also see child runs, use 'includeChildren=true'; pass 'rootRunId' for an entire tree, or 'parentRunId' for the direct children of a run. 'userId' narrows the list to one user's runs, and 'label' takes a 'key:value' pair ('label=team:payments'); a bare 'label=team' matches any value of that key. Both dimensions are recorded from the server-side IRunAttributionContext, never from the run request body. If a registered IRunAuthorizationHandler denies the caller, the response is 403 — the list is REJECTED, never silently filtered.", "operationId": "TraconListRuns", "parameters": [ { "name": "agentName", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/RunStatus" } }, { "name": "kind", "in": "query", "schema": { "$ref": "#/components/schemas/RunKind" } }, { "name": "sessionId", "in": "query", "schema": { "type": "string" } }, { "name": "errorType", "in": "query", "schema": { "type": "string" } }, { "name": "userId", "in": "query", "schema": { "type": "string" } }, { "name": "label", "in": "query", "schema": { "type": "string" } }, { "name": "startedAfter", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "includeChildren", "in": "query", "schema": { "type": "boolean" } }, { "name": "parentRunId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "rootRunId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "skip", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "take", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RunRecord" } } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "RunsRead" } }, "/tracon/api/runs/{runId}/tree": { "get": { "tags": [ "Tracon", "Runs" ], "summary": "Returns the entire tree a run belongs to, starting from the root.", "description": "The tree is always resolved from the ROOT, whichever member is asked for: a request naming a child run still returns the whole tree, because without the sibling branches a client cannot tell where in the tree that run sits. Each entry carries its parent, so the shape is rebuilt on the client. At most 200 runs are returned; a tree larger than that is truncated rather than paged.", "operationId": "TraconGetRunTree", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RunRecord" } } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "RunsRead" } }, "/tracon/api/runs/{runId}": { "get": { "tags": [ "Tracon", "Runs" ], "summary": "Returns the summary of a single run.", "description": "The summary carries status, timings, token counts, and — when pricing is configured — cost; it does not carry the conversation. Read the messages from the events endpoint, and the recorded input from the input endpoint. A run row is written when the run starts, so a run that is still going is readable here with a non-terminal status.", "operationId": "TraconGetRun", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunRecord" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "RunsRead" } }, "/tracon/api/runs/{runId}/events": { "get": { "tags": [ "Tracon", "Runs" ], "summary": "Streams a run's events over SSE; live and historical use the same path.", "description": "If the connection drops, the client resumes from its last sequence number using the 'Last-Event-ID' header. If the run is still in progress, the stream stays open until it completes. This stream's frame names ('run.started', 'tool.invoking', ...) are a different, larger set than the direct run-agent stream's ('run', 'update', 'approvals', 'done', 'error') — the two are separate contracts, not one seen through two content types.", "operationId": "TraconStreamRunEvents", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "RunsRead" } }, "/tracon/api/runs/{runId}/cancel": { "post": { "tags": [ "Tracon", "Runs" ], "summary": "Requests cancellation of a running run.", "description": "202 only reports that cancellation was REQUESTED; the final status is read from 'GET /api/runs/{id}'. Returns 409 if the run is not executing on this instance (a different instance, or a restarted process). Canceling a root run also stops every child run in the tree; canceling a child run on its own does not affect the root.", "operationId": "TraconCancelRun", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunRecord" } } } } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "RunsWrite" } }, "/tracon/api/runs/{runId}/feedback": { "post": { "tags": [ "Tracon", "Runs" ], "summary": "Writes a score for a run or for a single message.", "description": "When the same author writes the same 'name' onto the same target (run or message) a second time, the row is UPDATED, not a new row opened; a different name opens a new row, so one reviewer can score a run for both 'helpfulness' and 'accuracy'. A blank 'name' becomes 'overall'. If 'messageId' is left blank, the score applies to the whole run. A 'categorical' score carries 'textValue' instead of 'value'; every other kind carries 'value'.", "operationId": "TraconSaveRunFeedback", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunFeedbackRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunScore" } } } } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "RunsWrite" }, "get": { "tags": [ "Tracon", "Runs" ], "summary": "Lists all scores for a run.", "description": "Both human scores and scores written by automatic evaluators appear in one list; the source is a field on each entry, not a separate endpoint. A run belonging to another tenant is reported as 404 rather than 403, so the API does not confirm that the run exists. A run with no scores returns an empty list, not 404.", "operationId": "TraconListRunFeedback", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RunScore" } } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "RunsRead" } }, "/tracon/api/runs/{runId}/feedback/{scoreId}": { "delete": { "tags": [ "Tracon", "Runs" ], "summary": "Deletes a score.", "description": "The deletion is recorded in the audit trail, so removing a score is itself traceable. The run must belong to the calling tenant; otherwise the response is 404. An unknown score id also returns 404, so repeating the call is not idempotent. Aggregate statistics computed from scores are recalculated on the next read rather than adjusted here.", "operationId": "TraconDeleteRunFeedback", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "scoreId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No Content" } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "RunsWrite" } }, "/tracon/api/runs/{runId}/input": { "get": { "tags": [ "Tracon", "Runs" ], "summary": "Returns the recorded input messages for a run.", "description": "Returns 404 for a run that started while input recording was disabled (Tracon:RunRecording:RecordRunInput = false), or that was deleted by a retention policy; such a run cannot be replayed.", "operationId": "TraconGetRunInput", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunInputResponse" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "RunsRead" } }, "/tracon/api/runs/{a}/compare/{b}": { "get": { "tags": [ "Tracon", "Runs" ], "summary": "Returns the summaries of two runs side by side.", "description": "The diff is NOT computed on the server; the endpoint returns the two summaries and the UI shows the comparison — the same pattern as the agent definition version diff.", "operationId": "TraconCompareRuns", "parameters": [ { "name": "a", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "b", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunComparisonResponse" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "RunsRead" } }, "/tracon/api/runs/{runId}/replay": { "post": { "tags": [ "Tracon", "Runs" ], "summary": "Starts a new run with recorded input.", "description": "The input is preserved, the conditions change: 'agentVersion', 'modelId', and 'toolMode'. The default 'toolMode' value is 'ReplayTools', and NO tool actually runs — recorded results are replayed. Replaying a call with no recorded result STOPS the replay and returns 422. 'LiveTools' ACTUALLY runs tools, produces side effects, requires the Admin role, and returns 409 if a tool requires approval. An agent carrying a client-side tool (AddClientTool) cannot be replayed in ANY tool mode and also returns 409 — its body runs in the caller's browser and no call to it was recorded. Replay is sessionless: if the source run belongs to a session, only that TURN's input is replayed; the conversation history is not carried over. Replay STARTS a run, so a registered IRunAuthorizationHandler is asked with the SOURCE run's id; a denial returns 403 before any run row is opened.", "operationId": "TraconReplayRun", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunReplayRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunReplayResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Bad Gateway", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "RunsWrite" } }, "/tracon/api/workflows": { "get": { "tags": [ "Tracon", "Workflows" ], "summary": "Lists workflows defined in code and stored in the database.", "description": "What the list contains depends on whether the workflow engine is registered. With the engine, both code-defined and stored workflows appear, because only the engine can see the ones built in code. Without it, only stored definitions are listed — managing definitions does not require the engine, but running them does.", "operationId": "TraconListWorkflows", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowDescriptor" } } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "WorkflowsRead" } }, "/tracon/api/workflows/functions": { "get": { "tags": [ "Tracon", "Workflows" ], "summary": "Lists function nodes registered in code.", "description": "Function nodes are defined only in code, with AddWorkflowFunction - the same code-only boundary AddTool draws for tools. This endpoint does not offer a write path; the UI lets users pick from this list when building a Sequential workflow's node list. An empty list means no function was registered, or the workflow engine was never turned on with UseWorkflows - either way, existing agent-only workflows are unaffected.", "operationId": "TraconListWorkflowFunctions", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowFunctionResponse" } } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "WorkflowsRead" } }, "/tracon/api/workflows/{name}": { "get": { "tags": [ "Tracon", "Workflows" ], "summary": "Returns a single workflow definition.", "description": "Only stored definitions are editable and only they are returned here. A code-defined workflow is listed and can be run but has no stored definition, so it answers 404 with a distinct 'No editable definition' title — different from the plain not-found title used for a name that does not exist at all. Read the structure of a code-defined workflow from the graph endpoint instead.", "operationId": "TraconGetWorkflow", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowDefinition" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "WorkflowsRead" }, "put": { "tags": [ "Tracon", "Workflows" ], "summary": "Creates or updates a workflow definition.", "description": "The definition is validated at save time with the same rules the compiler applies, so a shape that could not run is rejected with 400 instead of failing on the first run. Which fields are required depends on the kind — a manager driven workflow needs its manager agent, for example. The call replaces the whole definition: omitted fields are cleared, not merged. The name comes from the path and is not taken from the body.", "operationId": "TraconSaveWorkflow", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowSaveRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowDefinition" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "WorkflowsAdmin" }, "delete": { "tags": [ "Tracon", "Workflows" ], "summary": "Deletes a workflow definition.", "description": "Only a stored definition can be deleted; a code-defined workflow is removed by changing the application, and asking for one here returns 404. Runs and checkpoints already recorded are kept, so past executions stay readable, but a checkpoint cannot be resumed once the definition it needs is gone.", "operationId": "TraconDeleteWorkflow", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "WorkflowsAdmin" } }, "/tracon/api/workflows/{name}/graph": { "get": { "tags": [ "Tracon", "Workflows" ], "summary": "Returns the compiled graph of the workflow.", "description": "Node IDs are identical to the executor IDs in run events; this is how the UI colors nodes live. The response also carries the Mermaid text generated by Microsoft Agent Framework.", "operationId": "TraconGetWorkflowGraph", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowGraph" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "WorkflowsRead" } }, "/tracon/api/workflows/{name}/run": { "post": { "tags": [ "Tracon", "Workflows" ], "summary": "Runs the workflow and streams its events over SSE.", "description": "Each frame carries a RunEvent. The first frame reports the run ID; every agent invoked within the workflow opens its own runs row, viewable as a tree via GET /api/runs/{runId}/tree. If a registered IRunAuthorizationHandler denies the caller, the run does not start and a 403 is returned, before the quota check. When session ownership is turned on, naming another user's session in 'sessionId' is refused the same way, and so is opening a NEW session when no authenticated identity can be resolved to own it.", "operationId": "TraconRunWorkflow", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRunHttpRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "501": { "description": "Not Implemented", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "RunsWrite" } }, "/tracon/api/workflows/runs/{runId}/checkpoints": { "get": { "tags": [ "Tracon", "Workflows" ], "summary": "Lists the checkpoints of a workflow run.", "description": "Checkpoints are the points a run can be resumed from; each entry's id is what the resume endpoint takes. A run belonging to another tenant is reported as 404 rather than 403, so the API does not confirm that it exists. An empty list means the run wrote no checkpoint — checkpointing is a property of how the workflow was built, not something this endpoint can turn on. Checkpoints are subject to retention, so an old run may have none left. A denial by a registered IRunAuthorizationHandler produces the same 404.", "operationId": "TraconListWorkflowCheckpoints", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowCheckpointRecord" } } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "RunsRead" } }, "/tracon/api/workflows/runs/{runId}/resume": { "post": { "tags": [ "Tracon", "Workflows" ], "summary": "Resumes from a checkpoint and streams events over SSE.", "description": "Resuming opens a NEW run rather than continuing the old one: the original run row is never rewritten, and the first streamed frame reports the new run id. The body is optional — without a checkpoint id the run resumes from its latest checkpoint. The engine must be registered; otherwise the response is 501. Because the status code is sent before the stream begins, a failure after that point arrives as an SSE error frame rather than an HTTP error. Resuming STARTS a run, so a registered IRunAuthorizationHandler is asked with the SOURCE run's id; a denial returns 403 before any run row is opened.", "operationId": "TraconResumeWorkflow", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowResumeHttpRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "501": { "description": "Not Implemented", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "RunsWrite" } }, "/tracon/api/workflows/runs/{runId}/requests": { "get": { "tags": [ "Tracon", "Workflows" ], "summary": "Lists a run's pending human input requests.", "description": "Only a run in the 'AwaitingInput' state returns requests. Requests are read from the run's event stream; there is no separate table. A run belonging to another tenant, and a denial by a registered IRunAuthorizationHandler, both return the same 404.", "operationId": "TraconListWorkflowRequests", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowPendingRequest" } } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "RunsRead" } }, "/tracon/api/workflows/runs/{runId}/respond": { "post": { "tags": [ "Tracon", "Workflows" ], "summary": "Responds to a pending request and resumes the run.", "description": "The response is matched to the request re-published with the same ID in the execution resumed from the checkpoint. Resuming opens a NEW runs row; events stream over SSE — so this STARTS a run, and a registered IRunAuthorizationHandler is asked with the source run's id; a denial returns 403 before any run row is opened.", "operationId": "TraconRespondWorkflowRequest", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRespondHttpRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "501": { "description": "Not Implemented", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "RunsWrite" } }, "/tracon/api/schedules": { "get": { "tags": [ "Tracon", "Scheduling" ], "summary": "Lists a tenant's schedules.", "description": "Enabled and disabled schedules are returned together; 'enabled' tells them apart. Each entry carries 'nextRunAt' as computed at the last save and 'lastRunAt' from the last execution, which is the quickest way to see that a schedule has stopped firing. A schedule with no cron expression never fires on its own and exists only to be triggered by hand.", "operationId": "TraconListSchedules", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/JobSchedule" } } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "PlatformRead" } }, "/tracon/api/schedules/{name}": { "get": { "tags": [ "Tracon", "Scheduling" ], "summary": "Gets a single schedule.", "description": "The response is the definition, including the stored payload the schedule fires with; the jobs it produced are read from the job endpoints, filtered by this schedule's id. Names are scoped to the calling tenant, and an unknown name returns 404.", "operationId": "TraconGetSchedule", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobSchedule" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "PlatformRead" }, "put": { "tags": [ "Tracon", "Scheduling" ], "summary": "Creates or updates a schedule.", "description": "The cron expression, time zone, and lane are validated here; the next run time is computed at save time. The payload cannot exceed the MaxItemsPerJob limit. 'lane' defaults to 'default' and every job this schedule produces — cron-dispatched or manually triggered — inherits it.", "operationId": "TraconSaveSchedule", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobScheduleSaveRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobSchedule" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "PlatformAdmin" }, "delete": { "tags": [ "Tracon", "Scheduling" ], "summary": "Deletes a schedule.", "description": "The schedule stops firing, but jobs it already queued are not withdrawn — cancel those individually if they must not run. Job history keeps pointing at the deleted schedule's id, so past executions stay traceable. To pause a schedule instead, save it with 'enabled: false'. An unknown name returns 404.", "operationId": "TraconDeleteSchedule", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "PlatformAdmin" } }, "/tracon/api/schedules/handler-keys": { "get": { "tags": [ "Tracon", "Scheduling" ], "summary": "Lists the handler keys a schedule may be created for.", "description": "The allow-list PUT /api/schedules/{name} enforces, so a client can offer exactly the keys that will be accepted rather than guessing. It is Tracon's own built-in keys unless the host set TraconSchedulingOptions.HttpSchedulableHandlerKeys, and it is NOT the full set of registered handlers: a handler with no entry here runs jobs queued in process but cannot be scheduled from outside. Admin only — a consumer's key names are deployment detail, so this list is deliberately not on the unauthenticated meta endpoint.", "operationId": "TraconListSchedulableHandlerKeys", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "PlatformRead" } }, "/tracon/api/schedules/{name}/trigger": { "post": { "tags": [ "Tracon", "Scheduling" ], "summary": "Runs a schedule immediately, without waiting for the cron schedule.", "description": "The job is queued, not executed inline: the response is the queued job record, so poll the job endpoint for the outcome. The body is optional — without one the schedule's stored payload is used, and a body's payload overrides it for this run only without changing the schedule. A trigger fires even when the schedule is disabled, and it does not move 'nextRunAt'. The payload's item count is capped by the same limit that applies on save.", "operationId": "TraconTriggerSchedule", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobTriggerRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobRecord" } } } } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "RunsWrite" } }, "/tracon/api/jobs": { "get": { "tags": [ "Tracon", "Scheduling" ], "summary": "Lists jobs, filtered by handler key, status, lane, or schedule.", "description": "Every queued unit of work shares this queue — scheduled runs, retention cleanups, webhook deliveries, and queued agent runs — so filter by 'handlerKey' to narrow it. 'scheduleId' returns the executions of one schedule. 'lane' returns only the jobs queued under that lane — the way to see whether a lane nobody's worker subscribes to is quietly piling up. Job items are not included here; read them from the single-job endpoint. Paging is offset based, with 'skip' defaulting to 0 and 'take' to 50.", "operationId": "TraconListJobs", "parameters": [ { "name": "handlerKey", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/JobStatus" } }, { "name": "scheduleId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "lane", "in": "query", "schema": { "type": "string" } }, { "name": "skip", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "take", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/JobRecord" } } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "RunsRead" } }, "/tracon/api/jobs/{id}": { "get": { "tags": [ "Tracon", "Scheduling" ], "summary": "Gets a job and its items.", "description": "This is the endpoint to poll after queuing work: it carries the job's status and attempt count together with its items, each with its own status, so partial progress is visible while the job is still running. A failed job keeps its error text here rather than only in the logs. An unknown id, or one belonging to another tenant, returns 404.", "operationId": "TraconGetJob", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobDetailResponse" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "RunsRead" } }, "/tracon/api/jobs/{id}/cancel": { "post": { "tags": [ "Tracon", "Scheduling" ], "summary": "Cancels a job.", "description": "Only a job in the Pending, Leased, or Running status can be canceled. The executing worker checks the cancellation request between items and stops cooperatively.", "operationId": "TraconCancelJob", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No Content" } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "RunsWrite" } }, "/tracon/api/evals": { "get": { "tags": [ "Tracon", "Evals" ], "summary": "Lists a tenant's eval suites.", "description": "Each entry is a suite's definition — the agent under test and its check definitions — without the cases or the past runs; read those from the cases and runs endpoints. The response is not paged.", "operationId": "TraconListEvalSuites", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EvalSuite" } } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "EvalsRead" } }, "/tracon/api/evals/{name}": { "get": { "tags": [ "Tracon", "Evals" ], "summary": "Gets a single eval suite.", "description": "The suite carries its checks, which are stored together with it rather than as separate rows, because a suite's checks are always read and written as one unit. Cases and runs are separate endpoints. Suites are scoped to the calling tenant, and an unknown name returns 404.", "operationId": "TraconGetEvalSuite", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvalSuite" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "EvalsRead" }, "put": { "tags": [ "Tracon", "Evals" ], "summary": "Creates or updates an eval suite.", "description": "Check definitions are declarative; an unknown check type turns into an error at run time.", "operationId": "TraconSaveEvalSuite", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvalSuiteSaveRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvalSuite" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "EvalsAdmin" }, "delete": { "tags": [ "Tracon", "Evals" ], "summary": "Deletes an eval suite (together with its cases and runs).", "description": "The cases and every past eval run cascade with the suite, so the score history used to compare agent versions disappears with it — export it first if it matters. The agent runs those evals produced stay in the run history and are still readable there. An unknown name returns 404.", "operationId": "TraconDeleteEvalSuite", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "EvalsAdmin" } }, "/tracon/api/evals/{name}/cases": { "get": { "tags": [ "Tracon", "Evals" ], "summary": "Lists a suite's cases.", "description": "Cases come back in their stored order, and that order is their identity: a case is addressed by its sequence number, so reordering the list changes which case a past result refers to. An unknown suite name returns 404, while a suite with no cases returns an empty list.", "operationId": "TraconListEvalCases", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EvalCase" } } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "EvalsRead" }, "put": { "tags": [ "Tracon", "Evals" ], "summary": "Replaces all of a suite's cases with the given list.", "description": "This is a full replacement, not an append: cases missing from the body are removed, so send the complete list every time. Sequence numbers are assigned from the body's order, which means reordering the list re-numbers the cases and past results then line up with different cases. Every case needs a non-empty 'query'; one that does not fails the whole request with 400 and nothing is written. An unknown suite name returns 404.", "operationId": "TraconSaveEvalCases", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EvalCaseInput" } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EvalCase" } } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "EvalsAdmin" }, "delete": { "tags": [ "Tracon", "Evals" ], "summary": "Deletes all of a suite's cases.", "description": "The suite itself survives with its checks intact; only the cases go. Past eval runs and their per-case results are kept, but they then point at cases that no longer exist. The call is idempotent — clearing an already empty suite still answers 204. An unknown suite name returns 404.", "operationId": "TraconClearEvalCases", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "EvalsAdmin" } }, "/tracon/api/evals/{name}/cases/from-run/{runId}": { "post": { "tags": [ "Tracon", "Evals" ], "summary": "Promotes a run to an eval case in a single request.", "description": "The query is read from the run's own session; runs without a session cannot be promoted. If the same run is promoted a second time, the existing case is returned (200, not 201).", "operationId": "TraconPromoteRunToEvalCase", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvalCasePromotionRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvalCase" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvalCase" } } } } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "EvalsAdmin" } }, "/tracon/api/evals/{name}/run": { "post": { "tags": [ "Tracon", "Evals" ], "summary": "Runs an eval suite now.", "description": "Each case runs in a new session on the agent being evaluated and produces its own 'runs' row. The run is queued as a job; results are processed in the background.", "operationId": "TraconTriggerEvalRun", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvalRunTriggerRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvalRun" } } } } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "RunsWrite" } }, "/tracon/api/evals/{name}/runs": { "get": { "tags": [ "Tracon", "Evals" ], "summary": "Lists a suite's past runs.", "description": "Each entry is one execution of the whole suite with its aggregate outcome; the per-case results live behind the single eval-run endpoint. To find the regression between two of these entries, hand both to the eval-run diff endpoint: it aligns them case by case instead of leaving the comparison to the caller. Paging is offset based, with 'skip' defaulting to 0 and 'take' to 50. An unknown suite name returns 404.", "operationId": "TraconListEvalRuns", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "skip", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "take", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EvalRun" } } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "EvalsRead" } }, "/tracon/api/evals/runs/{id}": { "get": { "tags": [ "Tracon", "Evals" ], "summary": "Gets a single eval run and its per-case results.", "description": "This is the endpoint to poll after triggering a suite: the eval run is queued and processed in the background, and its results fill in as cases complete. Each result names the agent run it came from, so a failing check can be traced to the exact conversation. Per-case results are a retention target, so an old eval run may keep its summary while its details are gone. An unknown id, or one belonging to another tenant, returns 404.", "operationId": "TraconGetEvalRun", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvalRunDetailResponse" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "EvalsRead" } }, "/tracon/api/evals/runs/{id}/diff": { "get": { "tags": [ "Tracon", "Evals" ], "summary": "Compares two eval runs of the same suite, case by case.", "description": "The run in the path is the candidate; 'baseline' names the run it is judged against. Every case lands in exactly one bucket - Regressed, Fixed, StillFailing, Unchanged, Added or Removed - and each entry names both sides' agent run, so a regression is one click from the two conversations that produced it. Cases added to or dropped from the suite are their own buckets and are never counted as regressions. Paging is offset based over the aligned cases, regressions first; the counters always describe the whole comparison. Both runs must have completed and must measure the same suite, otherwise 400. If retention has removed either run's per-case results the answer is 409, never an empty diff: an empty diff would read as 'nothing changed'. An unknown id, or one belonging to another tenant, returns 404.", "operationId": "TraconDiffEvalRuns", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "baseline", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "skip", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "take", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvalRunDiff" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "EvalsRead" } }, "/tracon/api/evaluation/online": { "get": { "tags": [ "Tracon", "Evals" ], "summary": "Returns a summary of the online evaluation window.", "description": "Returns the average judge score, sample count, and judge cost within the window. The summary is in-memory (it resets when the process restarts); for an authoritative result that survives a restart, use 'GET /api/evaluation/scores/summary' instead.", "operationId": "TraconGetOnlineEvaluationSummary", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnlineEvaluationSummary" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "EvalsRead" } }, "/tracon/api/evaluation/scores/summary": { "get": { "tags": [ "Tracon", "Evals" ], "summary": "Aggregates run and message scores by name, author, source, and agent.", "description": "A query over the scores already written, not a counter -- unlike '/api/evaluation/online', the result survives a process restart. Each breakdown groups by (name, kind): a 1-5 star rating and a 0-100 numeric score sharing a name never average together. 'messageId' is never a breakdown dimension; use 'target' (run, message, or both) instead. 'bucket' (hour, day, or week, UTC) adds a trend series; omitting it costs nothing extra. A bucketed series with no 'from' defaults to the last 90 days, since a series has no other bound the way a breakdown does. Every breakdown, and the categories inside one categorical score's entry, is capped at 'maxRows'. 400 if 'from' is at or after 'to', or 'maxRows' is out of range.", "operationId": "TraconGetRunScoreSummary", "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "scoreName", "in": "query", "schema": { "type": "string" } }, { "name": "agentName", "in": "query", "schema": { "type": "string" } }, { "name": "source", "in": "query", "schema": { "type": "string" } }, { "name": "author", "in": "query", "schema": { "type": "string" } }, { "name": "target", "in": "query", "schema": { "$ref": "#/components/schemas/RunScoreTarget" } }, { "name": "bucket", "in": "query", "schema": { "$ref": "#/components/schemas/RunScoreBucket" } }, { "name": "maxRows", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunScoreSummary" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "EvalsRead" } }, "/tracon/api/runs/{runId}/judge": { "post": { "tags": [ "Tracon", "Evals" ], "summary": "Manually has judge(s) score a run.", "description": "This SKIPS the sampling decision; it is for calibration and debugging. If no IRunJudge is registered, or the run's input/output cannot be read, an empty list is returned. Judging both READS the run and WRITES a score for it, so a registered IRunAuthorizationHandler is asked for both; either denial returns 404, identical to a run that does not exist.", "operationId": "TraconJudgeRun", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JudgeRunResponse" } } } } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "RunsWrite" } }, "/tracon/api/experiments": { "get": { "tags": [ "Tracon", "Experiments" ], "summary": "Lists a tenant's A/B experiments.", "description": "Experiments in every state are returned — Draft, Running, and Stopped — because a stopped experiment is still the record its results are read from. At most one of them per agent can be Running. The entries carry the variant weights, so a client can show the traffic split without a second call.", "operationId": "TraconListExperiments", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Experiment" } } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "ExperimentsRead" } }, "/tracon/api/experiments/{name}": { "get": { "tags": [ "Tracon", "Experiments" ], "summary": "Gets a single A/B experiment.", "description": "The response is the experiment's definition — arms, weights, status — not its outcome; read the per-arm counts from the results endpoint and the canary rule from the canary endpoint. Experiments are scoped to the calling tenant, and a name that belongs to another tenant is reported as 404.", "operationId": "TraconGetExperiment", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experiment" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "ExperimentsRead" }, "put": { "tags": [ "Tracon", "Experiments" ], "summary": "Creates or updates an experiment.", "description": "An experiment can only be set up between versions of the same agent; code-sourced agents have no version history, so they are rejected. Variant weights must sum to 100.", "operationId": "TraconSaveExperiment", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperimentSaveRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experiment" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "ExperimentsAdmin" }, "delete": { "tags": [ "Tracon", "Experiments" ], "summary": "Deletes an experiment. A running experiment must be stopped first.", "description": "Deleting a Running experiment returns 409; stop it first, so traffic is never left splitting against a definition that no longer exists. Runs already assigned to an arm keep their assignment and stay readable, but the per-arm results endpoint disappears with the experiment — export the results before deleting. An unknown name returns 404.", "operationId": "TraconDeleteExperiment", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "ExperimentsAdmin" } }, "/tracon/api/experiments/{name}/start": { "post": { "tags": [ "Tracon", "Experiments" ], "summary": "Starts the experiment; traffic begins splitting according to the weights.", "description": "Only one experiment can run for the same agent at a time.", "operationId": "TraconStartExperiment", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experiment" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "ExperimentsAdmin" } }, "/tracon/api/experiments/{name}/stop": { "post": { "tags": [ "Tracon", "Experiments" ], "summary": "Stops the experiment; new runs go to the current version.", "description": "Stopping affects only new runs: a run already in flight keeps the arm it was assigned, and the recorded results stay intact and readable afterwards. Stopping an experiment that is not Running returns 409, and so does an unknown name — this endpoint does not distinguish the two. Once stopped, the agent's own current version serves all traffic again, and the same agent becomes free for another experiment.", "operationId": "TraconStopExperiment", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experiment" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "ExperimentsAdmin" } }, "/tracon/api/experiments/{name}/results": { "get": { "tags": [ "Tracon", "Experiments" ], "summary": "Gets a per-arm summary of count, error rate, tokens, and duration.", "description": "There is no statistical claim of a 'winner'; raw counts are shown.", "operationId": "TraconGetExperimentResults", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperimentResultsResponse" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "ExperimentsRead" } }, "/tracon/api/experiments/{name}/canary": { "put": { "tags": [ "Tracon", "Experiments" ], "summary": "Defines or removes the canary rule (a 'null' body removes it).", "description": "Can only be defined on two-arm experiments: canaryVariant is the canary, and the single remaining arm counts as control. Works regardless of the experiment's status (Draft or Running).", "operationId": "TraconSetExperimentCanary", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanaryPolicy" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experiment" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "ExperimentsAdmin" }, "get": { "tags": [ "Tracon", "Experiments" ], "summary": "Gets the canary rule and its current evaluation.", "description": "The evaluation is not persisted; it is recalculated on every call using current run results.", "operationId": "TraconGetExperimentCanary", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperimentCanaryResponse" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "ExperimentsRead" } }, "/tracon/api/tools": { "get": { "tags": [ "Tracon", "Agents" ], "summary": "Lists registered tools and their JSON schemas.", "description": "Tools are defined only in code. This endpoint does not offer a write path; the UI lets users pick from this list when defining an agent.", "operationId": "TraconListTools", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ToolDescriptor" } } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "AgentsRead" } }, "/tracon/api/models": { "get": { "tags": [ "Tracon", "Agents" ], "summary": "Lists registered model providers and their models.", "description": "The model catalog comes from configuration; Tracon does not ship a built-in model list. An empty list is not an error. The catalog is also not a validation list: a model name that is not listed here can still be used. The `status` field comes FROM THE CACHE, and this endpoint makes no network call to the provider; use /api/models/health for an up-to-date check.", "operationId": "TraconListModels", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ModelProviderDescriptor" } } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "AgentsRead" } }, "/tracon/api/stats": { "get": { "tags": [ "Tracon", "Agents" ], "summary": "Returns run counts, token totals, and the error rate.", "description": "The summary is computed in the store itself. Cost is populated only when pricing is configured (model catalog or Tracon:Pricing); the count of models with undefined pricing is counted separately in the RunsWithUnknownPricing field — it is not written as zero. Every breakdown (byAgent, byModel, byVersion, byUser, byLabel) is ALWAYS returned; there is no groupBy switch. 'userId' and 'label' ('key:value') narrow the whole summary rather than choosing a breakdown. byLabel rows do NOT sum to totalRuns: a run carrying three labels appears in three of them. cachedInputTokens and reasoningTokens are counted INSIDE inputTokens/outputTokens, so adding them double counts.", "operationId": "TraconStats", "parameters": [ { "name": "agentName", "in": "query", "schema": { "type": "string" } }, { "name": "userId", "in": "query", "schema": { "type": "string" } }, { "name": "label", "in": "query", "schema": { "type": "string" } }, { "name": "startedAfter", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "maxAgents", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunStatistics" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "RunsRead" } }, "/tracon/api/stats/timeseries": { "get": { "tags": [ "Tracon", "Agents" ], "summary": "Per-bucket time series of runs, errors, tokens, and cost.", "description": "Empty buckets are returned too. The default range is the last 24 hours, the default bucket is an hour. At most 500 buckets; exceeding that returns 400. Unlike /api/stats, this endpoint does NOT exclude Eval/Workflow runs by default; it can be filtered with ?kind=.", "operationId": "TraconStatsTimeSeries", "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "bucket", "in": "query", "schema": { "$ref": "#/components/schemas/TimeSeriesBucket" } }, { "name": "agentName", "in": "query", "schema": { "type": "string" } }, { "name": "modelId", "in": "query", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "schema": { "$ref": "#/components/schemas/RunKind" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TimeSeriesPoint" } } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "RunsRead" } }, "/tracon/api/stats/errors": { "get": { "tags": [ "Tracon", "Agents" ], "summary": "Returns the breakdown by error class and each class's top three clusters.", "description": "This is a narrow slice of /api/stats: it returns only the ByErrorClass field (that field is also present in the /api/stats response). The default range is the last 24 hours, changed with ?hours=. Rows written before error classification existed appear in the Unknown bucket; a high Unknown share means the taxonomy is incomplete.", "operationId": "TraconStatsErrors", "parameters": [ { "name": "agentName", "in": "query", "schema": { "type": "string" } }, { "name": "hours", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RunErrorStatistics" } } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "RunsRead" } }, "/tracon/api/stats/recalculate-costs": { "post": { "tags": [ "Tracon", "Agents" ], "summary": "Fills in the cost of runs whose price is still unknown.", "description": "This is a maintenance endpoint. It fills in the cost of runs whose price is still unknown (unpriced when they completed, typically because the model was not configured yet); a run's cost is a price snapshot and this endpoint never rewrites one that already has a known price, even if the price list changed since. A run written before the provider column existed resolves by model name alone; if the same model name is defined for more than one provider, the first alphabetical match wins. Requires Admin; the call is written to the audit trail.", "operationId": "TraconRecalculateCosts", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunCostRecalculationResult" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "RunsWrite" } }, "/tracon/api/quotas": { "get": { "tags": [ "Tracon", "Governance" ], "summary": "Lists a tenant's quota rules.", "description": "Rules are definitions, not counters — read the counters from the usage endpoint. A rule with no agent name applies to the whole tenant, and a tenant-wide rule and an agent-specific rule can both be in force at once. A rule with 'enabled: false' is kept but not enforced. An agent with no matching rule is unlimited.", "operationId": "TraconListQuotas", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/QuotaDefinition" } } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "PlatformRead" }, "put": { "tags": [ "Tracon", "Governance" ], "summary": "Creates or updates a quota rule.", "description": "The scope (tenant + agent + period) is unique: writing a second rule for the same scope overwrites the existing rule. Each limit can also be left empty; only the ones that are set are enforced.", "operationId": "TraconSaveQuota", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaSaveRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaDefinition" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "PlatformAdmin" } }, "/tracon/api/quotas/{id}": { "delete": { "tags": [ "Tracon", "Governance" ], "summary": "Deletes a quota rule.", "description": "Removing the last rule that covers an agent makes it unlimited, which is why the removal is written to the audit trail with the rule's previous values. Usage counters already recorded are not deleted; they simply stop being enforced. To keep the limits but stop enforcing them, save the rule with 'enabled: false' instead. An unknown id returns 404.", "operationId": "TraconDeleteQuota", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No Content" } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "PlatformAdmin" } }, "/tracon/api/quotas/usage": { "get": { "tags": [ "Tracon", "Governance" ], "summary": "Returns the current period's quota usage.", "description": "An empty 'agentName' value shows the tenant-wide counter. Counters are approximate: the check happens before a run starts, and consumption is written after it finishes.", "operationId": "TraconGetQuotaUsage", "parameters": [ { "name": "agentName", "in": "query", "schema": { "type": "string" } }, { "name": "period", "in": "query", "schema": { "$ref": "#/components/schemas/QuotaPeriod" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaUsageResponse" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "PlatformRead" } }, "/tracon/api/webhooks": { "get": { "tags": [ "Tracon", "Webhooks" ], "summary": "Lists a tenant's webhook subscriptions.", "description": "The response carries no secret; only the NAME of the signing key is returned.", "operationId": "TraconListWebhooks", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubscription" } } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "PlatformRead" } }, "/tracon/api/webhooks/{name}": { "get": { "tags": [ "Tracon", "Webhooks" ], "summary": "Gets a single subscription.", "description": "As in the list, no signing secret is returned — only the configuration key its value is read from at delivery time. A secret is never stored in the database and never leaves through this API. An unknown name returns 404.", "operationId": "TraconGetWebhook", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscription" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "PlatformRead" }, "put": { "tags": [ "Tracon", "Webhooks" ], "summary": "Creates or updates a webhook subscription.", "description": "The address passes an SSRF check: only https is accepted (http only when AllowInsecureHttp is enabled and only to loopback targets). Private network addresses are re-checked again at delivery time.", "operationId": "TraconSaveWebhook", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSaveRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscription" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "PlatformAdmin" }, "delete": { "tags": [ "Tracon", "Webhooks" ], "summary": "Deletes a subscription and its delivery history.", "description": "The delivery history cascades with the subscription, so export it first if it is needed for an audit; there is no way to recover it afterwards. Events raised after the delete match no subscription and are simply not delivered. An unknown name returns 404.", "operationId": "TraconDeleteWebhook", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "PlatformAdmin" } }, "/tracon/api/webhooks/{name}/test": { "post": { "tags": [ "Tracon", "Webhooks" ], "summary": "Sends a test event to the subscription's endpoint.", "description": "The event is written to the queue and delivered by a background worker; the response reports that it was queued, not the delivery outcome.", "operationId": "TraconTestWebhook", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTestResponse" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "PlatformAdmin" } }, "/tracon/api/webhooks/{name}/deliveries": { "get": { "tags": [ "Tracon", "Webhooks" ], "summary": "Lists a subscription's delivery history.", "description": "This is a history table, not a queue: scheduling and retry live in the job queue. There is one entry per event, carrying the latest status, the attempt count, and the endpoint's last response code — a retry updates that entry rather than adding another. Filter with '?status=' to find failures. Paging is offset based — 'skip' defaults to 0, 'take' to 50, and 'take' is clamped to 1..200 instead of being rejected. An unknown subscription name returns 404.", "operationId": "TraconListWebhookDeliveries", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/WebhookDeliveryStatus" } }, { "name": "skip", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "take", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "PlatformRead" } }, "/tracon/api/api-keys": { "get": { "tags": [ "Tracon", "ApiKeys" ], "summary": "Lists a tenant's API keys.", "description": "The response carries neither the raw value nor a hash.", "operationId": "TraconListApiKeys", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyRecord" } } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "SecurityAdmin" }, "post": { "tags": [ "Tracon", "ApiKeys" ], "summary": "Generates a new API key.", "description": "The raw value is returned in the response ONLY ON THIS CALL and cannot be produced again. The scope list is closed; an unknown scope is rejected. If the request was authenticated with an API key, a scope that key does NOT ITSELF CARRY cannot be requested (privilege extension/attenuation).", "operationId": "TraconCreateApiKey", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreateRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreationResult" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "SecurityAdmin" } }, "/tracon/api/api-keys/{id}": { "delete": { "tags": [ "Tracon", "ApiKeys" ], "summary": "Revokes a key.", "description": "The row is NOT deleted; a revocation timestamp is written and stays in the audit trail.", "operationId": "TraconRevokeApiKey", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No Content" } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "SecurityAdmin" } }, "/tracon/api/tenants/{tenantId}/providers": { "get": { "tags": [ "Tracon", "TenantProviders" ], "summary": "Lists a tenant's model provider bindings.", "description": "The response carries neither the credential value nor its configuration key's value — only the key's NAME and whether it currently resolves ('resolved'). This is the diagnosis path for 'I set the key but it does not work'.", "operationId": "TraconListTenantProviderBindings", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TenantProviderBindingResponse" } } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "SecurityAdmin" } }, "/tracon/api/tenants/{tenantId}/providers/{provider}": { "put": { "tags": [ "Tracon", "TenantProviders" ], "summary": "Creates or replaces a tenant's binding for a provider.", "description": "The body carries only the configuration key's NAME the value is read from at call time, never the value itself. The name must be under the configured allowed prefix (400 otherwise), and the provider must be allowed by the tenant's egress policy, if one is defined (400 otherwise).", "operationId": "TraconSaveTenantProviderBinding", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantProviderBindingRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantProviderBindingResponse" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "SecurityAdmin" }, "delete": { "tags": [ "Tracon", "TenantProviders" ], "summary": "Deletes a tenant's binding for a provider.", "description": "After deletion, calls for that provider use the setup-time global credential again.", "operationId": "TraconDeleteTenantProviderBinding", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "SecurityAdmin" } }, "/tracon/api/tenants/{tenantId}/egress": { "get": { "tags": [ "Tracon", "TenantProviders" ], "summary": "Returns a tenant's model provider egress policy.", "description": "'allowedProviders: null' means the tenant is UNRESTRICTED (no policy saved); an empty or populated array means the tenant may call only those providers.", "operationId": "TraconGetTenantEgressPolicy", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantEgressPolicyResponse" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "SecurityAdmin" }, "put": { "tags": [ "Tracon", "TenantProviders" ], "summary": "Creates or replaces a tenant's egress policy.", "description": "Saving a policy is an ADDITIVE restriction: a tenant with no policy is unrestricted, and this call is the only way that changes. An agent definition naming a provider outside the saved list is rejected at compile time, not only at call time. An empty 'allowedProviders' array allows NO provider — it is not the same as having no policy; use DELETE to return to unrestricted.", "operationId": "TraconSaveTenantEgressPolicy", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantEgressPolicyRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantEgressPolicyResponse" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "SecurityAdmin" }, "delete": { "tags": [ "Tracon", "TenantProviders" ], "summary": "Deletes a tenant's egress policy.", "description": "After deletion the tenant is unrestricted again — the same state as before any policy was ever saved.", "operationId": "TraconDeleteTenantEgressPolicy", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "SecurityAdmin" } }, "/tracon/api/triggers": { "get": { "tags": [ "Tracon", "Triggers" ], "summary": "Lists a tenant's inbound triggers.", "description": "The response carries no signing secret value, only the configuration key's NAME and whether it currently resolves ('resolved') — the diagnosis path for 'I set the secret but signatures still fail'.", "operationId": "TraconListInboundTriggers", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InboundTriggerResponse" } } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "PlatformRead" } }, "/tracon/api/triggers/{name}": { "get": { "tags": [ "Tracon", "Triggers" ], "summary": "Gets a single inbound trigger.", "description": "An unknown name returns 404.", "operationId": "TraconGetInboundTrigger", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboundTriggerResponse" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "PlatformRead" }, "put": { "tags": [ "Tracon", "Triggers" ], "summary": "Creates or updates an inbound trigger.", "description": "'signingSecretConfigurationName' carries only the configuration key's NAME, never its value; the name must be under the configured allowed prefix (400 otherwise). 'payloadPath' is required when 'payloadMode' is 'path'.", "operationId": "TraconSaveInboundTrigger", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboundTriggerSaveRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboundTriggerResponse" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "PlatformAdmin" }, "delete": { "tags": [ "Tracon", "Triggers" ], "summary": "Deletes an inbound trigger.", "description": "After deletion, the accept endpoint returns 404 for this name. An unknown name returns 404.", "operationId": "TraconDeleteInboundTrigger", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "PlatformAdmin" } }, "/tracon/api/approvals/pending": { "get": { "tags": [ "Tracon", "Approvals" ], "summary": "Lists the tenant's pending approval requests.", "description": "Only requests still awaiting a decision are returned; a decided request leaves the list and stays readable by id. A request appears here when a queued run ('Prefer: respond-async') stops on a tool call that needs approval — a run driven synchronously carries its approval in the response stream instead and never reaches this mailbox. Each entry carries an expiry, which is an absolute point in the future rather than an elapsed duration. If a registered IRunAuthorizationHandler denies the caller, the response is 403 — the list is REJECTED, never silently filtered.", "operationId": "TraconListPendingApprovals", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PendingApproval" } } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "RunsRead" } }, "/tracon/api/approvals/{id}": { "get": { "tags": [ "Tracon", "Approvals" ], "summary": "Returns a single pending approval request.", "description": "Unlike the list, this reads a request in any state, so it is how a client polls the outcome after deciding: the response then carries who decided, when, and which way. The request holds the tool call's arguments as recorded, which is what an approver reviews before deciding. An unknown id returns 404, and so does a denial by a registered IRunAuthorizationHandler.", "operationId": "TraconGetPendingApproval", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingApproval" } } } } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "RunsRead" } }, "/tracon/api/approvals/{id}/decide": { "post": { "tags": [ "Tracon", "Approvals" ], "summary": "Decides a pending approval request.", "description": "The decision enqueues a NEW run (same sessionId, new RunId); the old run stays AwaitingApproval. Do not start that run yourself. Repeating the SAME decision is safe and returns 200: the continuation run's identity is derived from the approval, so a repeat finishes a handoff that failed partway instead of creating a second run. A second decision asking for the OPPOSITE answer gets 409. If a registered IRunAuthorizationHandler denies the caller, the response is 404, identical to an approval request that does not exist — the 409 is never reached, so a denial cannot reveal that the request was already decided.", "operationId": "TraconDecideApproval", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalDecisionRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingApproval" } } } } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "RunsWrite" } }, "/tracon/api/retention": { "get": { "tags": [ "Tracon", "Retention" ], "summary": "Lists a tenant's retention policies.", "description": "Only targets that have an explicit policy appear here. A target missing from the list is not cleaned up at all — absence means 'keep forever', not 'use a default'. A policy is also kept while switched off, so 'enabled: false' is a configured-but-paused policy and is different from having none.", "operationId": "TraconListRetentionPolicies", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RetentionPolicy" } } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "PlatformRead" } }, "/tracon/api/retention/preview": { "get": { "tags": [ "Tracon", "Retention" ], "summary": "Shows how many rows would be deleted if run now. Does NOT delete.", "description": "Run this before every cleanup: it is the only way to see the size of a deletion before it happens. The counts are computed against the data as it is right now, so they are an estimate — rows written between the preview and the run are included by the run. Without '?target=' every configured target is previewed; an unknown target name returns 400. Nothing is written and no job is queued.", "operationId": "TraconPreviewRetention", "parameters": [ { "name": "target", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RetentionPreview" } } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "PlatformRead" } }, "/tracon/api/retention/run": { "post": { "tags": [ "Tracon", "Retention" ], "summary": "Runs the cleanup now.", "description": "Does not run synchronously: an tracon.retention job is enqueued and processed from the queue.", "operationId": "TraconRunRetention", "parameters": [ { "name": "target", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetentionRunTriggerResponse" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "PlatformAdmin" } }, "/tracon/api/retention/history": { "get": { "tags": [ "Tracon", "Retention" ], "summary": "Lists past cleanup runs.", "description": "Each entry records one executed cleanup — the target, when it ran, and how many rows it removed — which is how a deletion is accounted for after the fact. Filter to one target with '?target='. Paging is offset based: 'skip' defaults to 0, 'take' to 50, and 'take' is clamped to 1..200 instead of being rejected. This history is not itself cleaned up by any policy — it is the permanent record of what was deleted.", "operationId": "TraconRetentionHistory", "parameters": [ { "name": "target", "in": "query", "schema": { "type": "string" } }, { "name": "skip", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "take", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RetentionRun" } } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "PlatformRead" } }, "/tracon/api/retention/{target}": { "get": { "tags": [ "Tracon", "Retention" ], "summary": "Gets the retention policy for a single target.", "description": "Two different failures are reported differently: an unrecognized target name returns 400 and lists the valid targets, while a valid target with no policy configured returns 404. Read that 404 as 'this data is never cleaned up'.", "operationId": "TraconGetRetentionPolicy", "parameters": [ { "name": "target", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetentionPolicy" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "PlatformRead" }, "put": { "tags": [ "Tracon", "Retention" ], "summary": "Creates or updates the retention policy for a target.", "description": "'maxAgeDays' and 'maxRows' are independent limits and both may be set; each must be at least 1 when given, and leaving both unset means the policy removes nothing. Saving does not delete anything by itself — the cleanup runs from the queue, so preview first. Every save is written to the audit trail with the previous and the new values. An unrecognized target returns 400.", "operationId": "TraconSaveRetentionPolicy", "parameters": [ { "name": "target", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetentionPolicySaveRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetentionPolicy" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "PlatformAdmin" }, "delete": { "tags": [ "Tracon", "Retention" ], "summary": "Deletes the retention policy for a target.", "description": "Removing a policy stops the cleanup for that target; it deletes no data and restores none that was already deleted. To pause a cleanup while keeping the limits, save the policy with 'enabled: false' instead. The removal is written to the audit trail. An unrecognized target returns 400, a target with no policy returns 404.", "operationId": "TraconDeleteRetentionPolicy", "parameters": [ { "name": "target", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "PlatformAdmin" } }, "/tracon/api/knowledge/{collection}/documents": { "post": { "tags": [ "Tracon", "Knowledge" ], "summary": "Uploads a document to the knowledge base.", "description": "The body carries either 'text' (the server chunks and embeds it) or 'chunks' (pre-chunked). PostgreSQL only: UsePostgreSql and an IEmbeddingGenerator must be registered.", "operationId": "TraconUploadKnowledgeDocument", "parameters": [ { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadDocumentRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadDocumentResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "501": { "description": "Not Implemented", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "KnowledgeAdmin" }, "get": { "tags": [ "Tracon", "Knowledge" ], "summary": "Lists the sources in a collection.", "description": "The response is a flat list of source identifiers, not the chunks or their text: a source is the unit a document was uploaded and is deleted as. An unknown collection is not an error — it simply has no sources and returns an empty list. Knowledge storage requires PostgreSQL; without it the response is 501.", "operationId": "TraconListKnowledgeDocuments", "parameters": [ { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "501": { "description": "Not Implemented", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "KnowledgeRead" } }, "/tracon/api/knowledge/{collection}/documents/{sourceId}": { "delete": { "tags": [ "Tracon", "Knowledge" ], "summary": "Deletes all chunks of a source.", "description": "Every chunk and embedding produced from the source is removed; re-uploading the document is the only way back, and it costs a fresh round of embedding calls. The call is idempotent: an unknown source id still answers 204, because the requested end state — no such source — already holds. Knowledge storage requires PostgreSQL; without it the response is 501.", "operationId": "TraconDeleteKnowledgeDocument", "parameters": [ { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "501": { "description": "Not Implemented", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "KnowledgeAdmin" } }, "/tracon/api/knowledge/{collection}/search": { "post": { "tags": [ "Tracon", "Knowledge" ], "summary": "Performs a semantic search in a collection (for diagnostics and calibration).", "description": "This runs the same retrieval an agent performs, so it is how a retrieval problem is separated from a prompt problem: if the right chunk does not come back here, the agent was never going to see it. The query is embedded, which costs one embedding call per request. Each hit carries its distance — smaller is closer — along with the chunk text and its metadata, so a relevance threshold can be calibrated from real values. Knowledge storage requires PostgreSQL; without it the response is 501.", "operationId": "TraconSearchKnowledge", "parameters": [ { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchKnowledgeRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SearchKnowledgeHit" } } } } }, "501": { "description": "Not Implemented", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "KnowledgeRead" } }, "/tracon/api/models/health": { "get": { "tags": [ "Tracon", "Models" ], "summary": "Returns the cached health status of all registered providers.", "description": "If a provider does not implement IModelProviderHealthCheck, its status is Unknown; this is not an error. A provider whose circuit is open shows as Unhealthy. The error detail does NOT include an API key or endpoint address.", "operationId": "TraconModelsHealth", "parameters": [ { "name": "refresh", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ModelProviderHealth" } } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "PlatformRead" } }, "/tracon/api/models/health/{provider}": { "get": { "tags": [ "Tracon", "Models" ], "summary": "Returns the cached health status of a single provider.", "description": "The status is served from the cache; add '?refresh=true' to force a fresh check. A check reads the provider's model list and never runs a completion, so it costs nothing. An unregistered provider name returns 404 — which is different from a registered provider that reports Unknown because it implements no health check. Error details never carry an API key or an endpoint address.", "operationId": "TraconModelHealth", "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "refresh", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelProviderHealth" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "PlatformRead" } }, "/tracon/api/voice/health": { "get": { "tags": [ "Tracon", "Voice" ], "summary": "Checks the voice provider's availability.", "description": "The check does not incur cost: no speech is generated, only the available voices are read.", "operationId": "TraconVoiceHealth", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceHealth" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "PlatformRead" } }, "/tracon/api/voice/voices": { "get": { "tags": [ "Tracon", "Voice" ], "summary": "Lists the available voices.", "description": "The list comes from the configured speech provider, not from Tracon; the identifiers it returns are the values the speak endpoint and the agent's 'speak' tool accept. When the speech layer was never enabled with UseVoice, the response is 501 rather than 404, so a missing configuration is not mistaken for a wrong address.", "operationId": "TraconVoiceList", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VoiceDescriptor" } } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "AgentsRead" } }, "/tracon/api/voice/sessions": { "get": { "tags": [ "Tracon", "Voice" ], "summary": "Lists the summary record of real-time speech connections.", "description": "The record does NOT contain audio: it only carries duration, turn count, and metering. If the speech layer is not enabled, the list is empty.", "operationId": "TraconVoiceSessions", "parameters": [ { "name": "agentName", "in": "query", "schema": { "type": "string" } }, { "name": "sessionId", "in": "query", "schema": { "type": "string" } }, { "name": "skip", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "take", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VoiceSessionRecord" } } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "RunsRead" } }, "/tracon/api/voice/speak": { "post": { "tags": [ "Tracon", "Voice" ], "summary": "Synthesizes speech from text and saves it as an attachment.", "description": "This is an operator action and is NOT tied to a run; the metering is not written to tool_invocations, it is returned in the response. If persistent metering is required, use the agent's `speak` tool.", "operationId": "TraconVoiceSpeak", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpeakRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpeakResponse" } } } } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "RunsWrite" } }, "/tracon/api/voice/live/sessions": { "post": { "tags": [ "Tracon", "Voice" ], "summary": "Creates a provider-hosted live voice session.", "description": "Relays the media peer's SDP offer to the provider and returns its answer, so the raw API key never reaches the browser. Tracon attaches a server-side control connection to the same session and turns the work the model delegates into ordinary runs. Returns 501 when no live voice provider is registered.", "operationId": "TraconLiveVoiceCreate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveVoiceSessionCreateRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveVoiceSessionCreateResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "501": { "description": "Not Implemented", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Bad Gateway", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "RunsWrite" } }, "/tracon/api/voice/live/sessions/{voiceSessionId}": { "delete": { "tags": [ "Tracon", "Voice" ], "summary": "Closes a live voice session and writes its record.", "description": "Cancels any delegation still running, writes the session record with its measured duration and cost, and drops the provider connection. A session another tenant owns answers 404, byte for byte the answer a session that does not exist gets.", "operationId": "TraconLiveVoiceClose", "parameters": [ { "name": "voiceSessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No Content" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "RunsWrite" }, "get": { "tags": [ "Tracon", "Voice" ], "summary": "Reports a live voice session's state and measurement.", "description": "The state is 'pending' until media is observed, then 'active', then 'ended'. The duration is the provider's own number: Tracon does not carry a live session's media and does not invent a duration.", "operationId": "TraconLiveVoiceStatus", "parameters": [ { "name": "voiceSessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveVoiceSessionStatusResponse" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "PlatformRead" } }, "/tracon/api/images/generate": { "post": { "tags": [ "Tracon", "Images" ], "summary": "Generates images and saves them as attachments.", "description": "This is an operator action outside a run. Generated images are saved as attachments and the response returns their descriptors and configured cost. To record usage in tool_invocations, use the agent's generate_image tool instead.", "operationId": "TraconGenerateImage", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageGenerationOperatorRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageGenerationOperatorResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Bad Gateway", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "RunsWrite" } }, "/tracon/api/runs/{runId}/trace": { "get": { "tags": [ "Tracon", "Runs" ], "summary": "Returns a run's span tree.", "description": "Spans are written with sampling. Spans for failed runs are always recorded by default; successes are recorded at a configurable rate.", "operationId": "TraconGetRunTrace", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunTrace" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "RunsRead" } }, "/tracon/api/runs/{runId}/tools": { "get": { "tags": [ "Tracon", "Runs" ], "summary": "Lists a run's tool calls in chronological order.", "description": "Duration is measured only for streaming runs: in a non-streaming run all messages arrive at once, so the true duration between call and result cannot be read. A run that does not exist, belongs to another tenant, or is denied by a registered IRunAuthorizationHandler returns the same 404.", "operationId": "TraconListRunToolInvocations", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ToolInvocationRecord" } } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "RunsRead" } }, "/tracon/api/tools/usage": { "get": { "tags": [ "Tracon", "Runs" ], "summary": "Returns call count, error rate, and average duration per tool.", "description": "The summary is computed by the store itself; it is not a paginated subset.", "operationId": "TraconToolUsage", "parameters": [ { "name": "startedAfter", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "maxTools", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ToolUsage" } } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "RunsRead" } }, "/tracon/api/tenants/current": { "get": { "tags": [ "Tracon", "Governance" ], "summary": "Returns the current request's tenant.", "description": "The tenant is resolved from the request. In a single-tenant setup, it always returns the default tenant. This endpoint is in the protected group; /api/meta does not carry tenant information.", "operationId": "TraconCurrentTenant", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentTenantResponse" } } } } }, "x-tracon-role": "Reader" } }, "/tracon/api/tenants": { "get": { "tags": [ "Tracon", "Governance" ], "summary": "Lists registered tenants.", "description": "A tenant record is NOT REQUIRED. The tenant_id in other tables is the same text as this record's slug value, but it is not connected by a foreign key; a tenant with no record does not produce an error at runtime.", "operationId": "TraconListTenants", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TenantDescriptor" } } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "PlatformAdmin" } }, "/tracon/api/tenants/{slug}": { "put": { "tags": [ "Tracon", "Governance" ], "summary": "Adds or updates a tenant record.", "description": "The record is a display name for a tenant key that already works without it; creating one does not create the tenant and deleting one does not remove its data. The slug comes from the path and must be at most 64 characters of letters, digits, dots, underscores, and hyphens (400 otherwise) — it is the same text stored as 'tenant_id' on every other row. An empty display name falls back to the slug.", "operationId": "TraconSaveTenant", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantDescriptor" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "PlatformAdmin" }, "delete": { "tags": [ "Tracon", "Governance" ], "summary": "Deletes a tenant record.", "description": "Only the record is deleted; the tenant's agents, sessions, and runs remain.", "operationId": "TraconDeleteTenant", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "PlatformAdmin" } }, "/tracon/api/mcp-servers": { "get": { "tags": [ "Tracon", "Governance" ], "summary": "Lists registered remote MCP servers.", "description": "The response CARRIES NO SECRETS: the authentication value is not stored; only the name of the configuration key from which the value will be read is returned.", "operationId": "TraconListMcpServers", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/McpServerDefinition" } } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "AgentsRead" } }, "/tracon/api/mcp-servers/{name}": { "put": { "tags": [ "Tracon", "Governance" ], "summary": "Adds or updates a remote MCP server.", "description": "SECURITY BOUNDARY. Adding an MCP server means accepting tool definitions from an external source. Only http/https addresses are accepted; local process (stdio) transport is not supported. Tools require approval by default.", "operationId": "TraconSaveMcpServer", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerDefinition" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "AgentsAdmin" }, "delete": { "tags": [ "Tracon", "Governance" ], "summary": "Deletes a remote MCP server.", "description": "The registration is removed, so the tools it contributed stop being offered to agents. Agent definitions that name those tools are not rewritten and will fail validation on their next save — check which agents use the server before removing it. No request is made to the remote server itself. An unknown name returns 404.", "operationId": "TraconDeleteMcpServer", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "AgentsAdmin" } }, "/tracon/api/mcp-servers/refresh": { "post": { "tags": [ "Tracon", "Governance" ], "summary": "Refreshes the tool list of remote MCP servers now.", "description": "The refresh normally happens in the background at fixed intervals. This endpoint lets the tools of a newly added server appear without waiting for the next scheduled refresh.", "operationId": "TraconRefreshMcpTools", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/IMcpToolRefresher" } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpRefreshResponse" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "AgentsAdmin" } }, "/tracon/api/mcp-servers/{name}/prompts": { "get": { "tags": [ "Tracon", "Governance" ], "summary": "Gets an MCP server's prompt list.", "description": "If the server does not advertise the 'prompts' capability, the request is never sent.", "operationId": "TraconListMcpPrompts", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/McpPromptSummary" } } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "AgentsRead" } }, "/tracon/api/mcp-servers/{name}/prompts/{prompt}": { "post": { "tags": [ "Tracon", "Governance" ], "summary": "Resolves an MCP prompt's content with arguments.", "description": "The returned content is a SNAPSHOT: it must be copied into the agent's instructions; it is not re-fetched at runtime. The 'hash' field is for tracking changes on the server.", "operationId": "TraconGetMcpPrompt", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "prompt", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpPromptArgumentsRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpPromptContent" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "AgentsRead" } }, "/tracon/api/mcp-servers/{name}/resources": { "get": { "tags": [ "Tracon", "Governance" ], "summary": "Gets an MCP server's resource list.", "description": "If the server does not advertise the 'resources' capability, the request is never sent.", "operationId": "TraconListMcpResources", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/McpResourceSummary" } } } } } }, "x-tracon-role": "Reader", "x-tracon-api-key-scope": "AgentsRead" } }, "/tracon/api/mcp-servers/{name}/resources/read": { "get": { "tags": [ "Tracon", "Governance" ], "summary": "Reads an MCP resource.", "description": "Only URIs advertised by the server's ListResourcesAsync are accepted; an arbitrary URI is rejected because it carries an SSRF risk.", "operationId": "TraconReadMcpResource", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "uri", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpResourceContent" } } } } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "AgentsRead" } }, "/tracon/api/mcp-servers/{name}/oauth/start": { "post": { "tags": [ "Tracon", "Governance" ], "summary": "Starts the OAuth authorization flow for an MCP server.", "description": "The administrator is redirected to the returned 'authorizationUri'. After approval, the provider redirects back to the '/oauth/callback' endpoint; that endpoint uses the 'state' value for CSRF protection.", "operationId": "TraconStartMcpOAuth", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpOAuthStartResponse" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "SecurityAdmin" } }, "/tracon/api/approvals/rules": { "get": { "tags": [ "Tracon", "Governance" ], "summary": "Lists persistent 'don't ask again' approval rules.", "description": "Each rule pre-approves a tool call so it never reaches the approval mailbox again, which makes this list a standing grant worth reviewing. A rule with no agent name applies to every agent in the tenant. When it carries an arguments hash the rule matches only that exact call; without one it matches every call to that tool. Rules do not expire — remove one to start asking again.", "operationId": "TraconListApprovalRules", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ToolApprovalRule" } } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "RunsRead" }, "post": { "tags": [ "Tracon", "Governance" ], "summary": "Creates a persistent, argument-conditioned approval rule.", "description": "Writes a standing 'don't ask again' rule with an admin-authored comparison (for example \"amount <= 100\"), evaluated on every call. There is no free-text expression field: the operator is a closed set and conditions combine with AND only. A code-defined policy (ITraconBuilder.AddToolApprovalPolicy) always runs first and can override this rule in both directions.", "operationId": "TraconCreateApprovalRule", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolApprovalRuleRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolApprovalRule" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "SecurityAdmin" } }, "/tracon/api/approvals/rules/{ruleId}": { "delete": { "tags": [ "Tracon", "Governance" ], "summary": "Revokes a persistent approval rule.", "description": "After the rule is deleted, approval is asked again for that tool.", "operationId": "TraconDeleteApprovalRule", "parameters": [ { "name": "ruleId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No Content" } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "RunsWrite" } }, "/tracon/api/audit": { "get": { "tags": [ "Tracon", "Governance" ], "summary": "Lists audit entries, filterable by actor, action, entity, and date range.", "description": "Filterable by actor, action, entity, and date range. Runs (an agent processing a message) are not written to this log; the runs table already keeps the full record. The one exception is the 'content.blocked' action: an IContentGuard's block decision is a GOVERNANCE decision, not a run detail, and must remain traceable even after the run record is deleted by retention policy. The entry carries only the guard and rule name, never the blocked TEXT.", "operationId": "TraconListAudit", "parameters": [ { "name": "actor", "in": "query", "schema": { "type": "string" } }, { "name": "action", "in": "query", "schema": { "type": "string" } }, { "name": "entity", "in": "query", "schema": { "type": "string" } }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEntry" } } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "AuditRead" } }, "/tracon/api/audit/{entity}": { "get": { "tags": [ "Tracon", "Governance" ], "summary": "Returns a single entity's change history, newest first.", "description": "The path segment is the full entity key as it was recorded, in the form ':' — for example 'quota:' or 'retention:runs'. It is matched as written, not as a prefix. Entries carry the before and the after state, so one request answers 'who changed this and to what'. There is no paging: '?limit=' defaults to 100 and is clamped to 1..500, and only the newest entries are returned. An entity with no history returns an empty list, not 404.", "operationId": "TraconGetEntityAudit", "parameters": [ { "name": "entity", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEntry" } } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "AuditRead" } }, "/tracon/api/audit/verify": { "get": { "tags": [ "Tracon", "Governance" ], "summary": "Walks the tenant's audit trail hash chain and reports whether it is intact.", "description": "'Valid' means every entry's hash matches its content and links to the one before it. 'Broken' means an entry's stored hash no longer matches its content — it was altered after it was written. 'Gap' means a link between two entries is missing — a row was deleted, or a write never completed; 'firstFailingEntryId' names where. An entry written before this feature shipped carries no hash and is excluded from the walk, not misreported as broken. Without '?after='/'?before=' the whole tenant history is walked; a narrower range is cheaper but cannot judge a break exactly at its own edge, because the entry just before the range is not read.", "operationId": "TraconVerifyAuditChain", "parameters": [ { "name": "after", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditChainVerification" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "AuditRead" } }, "/tracon/api/data-subjects/{id}/export": { "get": { "tags": [ "Tracon", "Governance" ], "summary": "Exports a data subject's content as one JSON document.", "description": "'{id}' is resolved through IDataSubjectResolver, which is registered by the consumer — Tracon does not store personal identity. Without a registered resolver this returns 409, never an empty document. The document holds every column of every matching row, keyed by target table (session state, runs, run inputs, attachment METADATA only — no file bytes, voice session summaries, run scores, conversations, conversation items, and responses); a target with no matching rows is present as an empty array, not omitted.", "operationId": "TraconExportDataSubject", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "SecurityAdmin" } }, "/tracon/api/data-subjects/{id}": { "delete": { "tags": [ "Tracon", "Governance" ], "summary": "Deletes a data subject's content.", "description": "'{id}' is resolved through IDataSubjectResolver; without one this returns 409, never a silent no-op that could be read as 'already erased'. '?dryRun=' DEFAULTS TO TRUE: a bare call previews the row counts and deletes nothing; '?dryRun=false' deletes for real. The audit trail (audit_log) is never touched — it is deliberately outside a data subject's erasable content (by design: an audit record is 'who did what', not the subject's own data) — but the erasure ITSELF is written there, with the row count per target; if that write fails, every delete is rolled back and this call fails, the same rule Approval decisions follow.", "operationId": "TraconEraseDataSubject", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dryRun", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSubjectErasureResult" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "SecurityAdmin" } }, "/tracon/api/diagnostics": { "get": { "tags": [ "Tracon", "Diagnostics" ], "summary": "Returns the setup's self-diagnosing summary report.", "description": "Disabled by default (TraconEndpointOptions.EnableDiagnosticsEndpoint); a deployment that has not turned it on answers 404. Never carries any secret value. Model provider status is read from the cache; it makes no model call and applies no migration.", "operationId": "TraconDiagnostics", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraconDiagnosticsReport" } } } } }, "x-tracon-role": "Admin", "x-tracon-api-key-scope": "PlatformRead" } }, "/tracon/v1/responses": { "post": { "tags": [ "Tracon", "OpenAI" ], "summary": "Run endpoint compatible with the OpenAI Responses API.", "description": "The agent is selected from the 'model' field; if not found, 'metadata.entity_id' is tried. If 'conversation' is given the session is stored under that identifier; if not, under the generated response identifier, so chaining with 'previous_response_id' works. If a registered IRunAuthorizationHandler denies the caller, the response is 403. When session ownership is turned on, a 'conversation' or 'previous_response_id' that belongs to another user is refused the same way, and so is opening a NEW conversation when no authenticated identity can be resolved to own it.", "operationId": "TraconOpenAIResponses", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonElement" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonElement" } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/JsonElement" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } } } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "RunsWrite" } }, "/tracon/v1/chat/completions": { "post": { "tags": [ "Tracon", "OpenAI" ], "summary": "Run endpoint compatible with the OpenAI Chat Completions API.", "description": "Stateless: the client carries history. The agent is selected from the 'model' field; if not found, 'metadata.entity_id' is tried. If a registered IRunAuthorizationHandler denies the caller, the response is 403 on BOTH the streaming and the non-streaming path.", "operationId": "TraconOpenAIChatCompletions", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonElement" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletion" } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/ChatCompletion" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } } } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "RunsWrite" } }, "/tracon/v1/conversations": { "post": { "tags": [ "Tracon", "OpenAI" ], "summary": "Generates a new conversation identifier.", "description": "An identifier reservation: the session is born on the first /v1/responses call. The returned identifier is used directly in the 'conversation' field.", "operationId": "TraconOpenAICreateConversation", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationResource" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } } } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "RunsWrite" } }, "/tracon/v1/conversations/{conversationId}": { "get": { "tags": [ "Tracon", "OpenAI" ], "summary": "Returns a conversation's metadata.", "description": "A conversation identifier is a reservation, so an id that has never carried a call is still valid and answers 200 with the current time as its creation time. 404 therefore means 'not yours', not 'never used': an identifier owned by another tenant is reported as missing rather than forbidden, so the API does not confirm that it exists.", "operationId": "TraconOpenAIGetConversation", "parameters": [ { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationResource" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } } } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "RunsRead" }, "delete": { "tags": [ "Tracon", "OpenAI" ], "summary": "Deletes a conversation and the session underneath it.", "description": "Following the OpenAI shape, the response is 200 with a 'deleted' flag rather than 204: the flag is false when the identifier was valid but no session had been created for it yet, so a client can tell a real deletion from a no-op. An identifier owned by another tenant returns 404.", "operationId": "TraconOpenAIDeleteConversation", "parameters": [ { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResource" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } } } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "RunsWrite" } }, "/tracon/v1/conversations/{conversationId}/items": { "get": { "tags": [ "Tracon", "OpenAI" ], "summary": "Lists a conversation's messages in the OpenAI item format.", "description": "Items come back oldest first, and one stored message can expand into several items — a reply plus its tool calls, for example. '?limit=' trims the list from the end and sets 'has_more' to true, which is computed from the real total before trimming, so a truncated list never looks complete. There is no cursor paging: 'first_id' and 'last_id' describe the returned window only. A conversation with no history returns an empty list, and an identifier owned by another tenant returns 404.", "operationId": "TraconOpenAIListConversationItems", "parameters": [ { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemListResource" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } } } }, "x-tracon-role": "Operator", "x-tracon-api-key-scope": "RunsRead" } }, "/tracon/api/mcp-servers/{name}/oauth/callback": { "get": { "tags": [ "Tracon", "Governance" ], "summary": "Processes the OAuth provider's callback request.", "description": "This endpoint is outside the access layers: the browser redirected by the provider cannot carry our bearer token. Security relies on the single-use 'state' value.", "operationId": "TraconMcpOAuthCallback", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "code", "in": "query", "schema": { "type": "string" } }, { "name": "state", "in": "query", "schema": { "type": "string" } }, { "name": "iss", "in": "query", "schema": { "type": "string" } }, { "name": "error", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } }, "security": [] } }, "/tracon/api/triggers/{tenantId}/{name}": { "post": { "tags": [ "Tracon", "Triggers" ], "summary": "Accepts a signed external event and queues a run.", "description": "No bearer token: the caller authenticates with an HMAC signature over the raw body ('X-Tracon-Timestamp' + 'X-Tracon-Signature', the same headers outbound webhooks send, in the reverse direction). The event is ALWAYS queued and this ALWAYS returns 202 — there is no synchronous mode; a long model call would otherwise fail the caller's own webhook timeout. A missing or wrong signature, an unknown trigger, and a disabled trigger all return the SAME generic response so a caller cannot enumerate trigger names. If a registered IRunAuthorizationHandler denies the target run, the response is 403, before the quota check.", "operationId": "TraconAcceptInboundTrigger", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboundTriggerAcceptedResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "description": "Payload Too Large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [] } } }, "components": { "schemas": { "AcceptedRunResponse": { "required": [ "runId", "jobId", "location", "eventsLocation" ], "type": "object", "properties": { "runId": { "type": "string", "description": "Run identifier.", "format": "uuid" }, "jobId": { "type": "string", "description": "Identifier of the queue record carrying the work.", "format": "uuid" }, "location": { "type": "string", "description": "Address of the run record. Same as the `Location` header." }, "eventsLocation": { "type": "string", "description": "Address of the event stream." } }, "description": "`202 Accepted` response for a queued run." }, "AgentDefinition": { "required": [ "name", "model" ], "type": "object", "properties": { "name": { "type": "string", "description": "Gets the unique name of the agent, used as the key in the catalog and in API routes." }, "displayName": { "type": [ "null", "string" ], "description": "Gets the name shown in the user interface. `Name` is used when it is empty." }, "description": { "type": [ "null", "string" ], "description": "Gets a short description of what the agent does." }, "instructions": { "type": [ "null", "string" ], "description": "Gets the system instructions passed to the model." }, "instructionsByCulture": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "Gets culture-keyed instructions. The key is a BCP-47 tag (`\"en\"`, `\"tr\"`);\na region subtag (`\"tr-TR\"`) falls back to its parent (`\"tr\"`). A run's\nrequested culture that matches neither falls back to `Instructions` -\nresolution never fails." }, "model": { "description": "Gets the provider and model binding to use.", "$ref": "#/components/schemas/ModelBinding" }, "toolNames": { "type": "array", "items": { "type": "string" }, "description": "Gets the names of the tools this agent may use. Every name must match a tool\nregistered in code; otherwise building the agent fails." }, "skillNames": { "type": "array", "items": { "type": "string" }, "description": "Gets the names of the skills this agent may load at run time. Every name must\nmatch an enabled skill found in code or in the skill store." }, "callableAgentNames": { "type": "array", "items": { "type": "string" }, "description": "Gets the names of the other agents this agent may call." }, "subAgents": { "oneOf": [ { "type": "null" }, { "description": "Gets how long this agent waits for the agents it calls. When\n`null`, `TraconAgentGraphOptions.ChildDeadline`\nand `WaitTimeout` apply instead. Ignored when\nIReadOnlyList<string> AgentDefinition.CallableAgentNames is empty.", "$ref": "#/components/schemas/SubAgentSettings" } ] }, "mcpResourceUris": { "type": "array", "items": { "type": "string" }, "description": "Gets the MCP resources added to the run context (mode A). Each item has the\nform `\"{server}:{uri}\"`. They are read at the start of the run and are\npredictable; every run receives the same resources." }, "harness": { "oneOf": [ { "type": "null" }, { "description": "Gets the harness settings. When `null` a plain chat agent is\nproduced; when populated, harness capabilities such as context compaction and\ntodo tracking are enabled.", "$ref": "#/components/schemas/HarnessSettings" } ] }, "compaction": { "oneOf": [ { "type": "null" }, { "description": "Gets the context compaction settings. When `null` no compaction\nis applied.", "$ref": "#/components/schemas/CompactionSettings" } ] }, "memory": { "oneOf": [ { "type": "null" }, { "description": "Gets the memory provider settings. When `null` no memory provider\nis added.", "$ref": "#/components/schemas/MemorySettings" } ] }, "origin": { "description": "Gets the origin of the definition: code or database.", "$ref": "#/components/schemas/AgentDefinitionOrigin" }, "version": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Gets the definition version. Every save increments this value and so naturally\ninvalidates the compiled agent cache.", "format": "int32" }, "tenantId": { "type": [ "null", "string" ], "description": "Gets the tenant this definition belongs to. A single-tenant setup uses the default value." }, "updatedAt": { "type": [ "null", "string" ], "description": "Gets the time the definition last changed (UTC).", "format": "date-time" }, "metadata": { "type": "object", "description": "Gets free-form, application-specific metadata." }, "parameters": { "type": "array", "items": { "$ref": "#/components/schemas/AgentParameter" }, "description": "Gets the schema of named placeholders (`{{name}}`) this definition's\ninstructions may reference." }, "sharedInstructionsName": { "type": [ "null", "string" ], "description": "Gets the name of another definition whose `Instructions` text is\nprepended to this definition's own resolved instructions at compile time." } }, "description": "The full definition of an agent. The same type is used whether the agent is\ndeclared in code or stored in the database; AgentDefinitionOrigin AgentDefinition.Origin tells the two apart." }, "AgentDefinitionOrigin": { "enum": [ "Code", "Database", "Custom" ], "description": "Tells where an agent definition came from." }, "AgentDefinitionRequest": { "required": [ "name", "model" ], "type": "object", "properties": { "name": { "type": "string", "description": "Agent name. Unique within the catalog." }, "displayName": { "type": [ "null", "string" ], "description": "Name shown in the UI." }, "description": { "type": [ "null", "string" ], "description": "Short description." }, "instructions": { "type": [ "null", "string" ], "description": "System instructions." }, "instructionsByCulture": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "Culture-keyed instructions. See IReadOnlyDictionary<string, string>? AgentDefinition.InstructionsByCulture." }, "model": { "description": "Model binding: provider, model, and sampling settings.", "$ref": "#/components/schemas/ModelBinding" }, "toolNames": { "type": "array", "items": { "type": "string" }, "description": "Names of tools to use. Tools are defined only in code; only the name of\nan already registered tool may be given here." }, "skillNames": { "type": "array", "items": { "type": "string" }, "description": "Names of skills that can be loaded at runtime." }, "callableAgentNames": { "type": "array", "items": { "type": "string" }, "description": "Names of other agents this agent may call." }, "subAgents": { "oneOf": [ { "type": "null" }, { "description": "How long this agent waits for the agents it calls. See\n`AgentDefinition.SubAgents`. Ignored when\nIReadOnlyList<string> AgentDefinitionRequest.CallableAgentNames is empty.", "$ref": "#/components/schemas/SubAgentSettings" } ] }, "mcpResourceUris": { "type": "array", "items": { "type": "string" }, "description": "MCP resources added to the run context, each of the form\n`\"{server}:{uri}\"`. See `AgentDefinition.McpResourceUris`." }, "harness": { "oneOf": [ { "type": "null" }, { "description": "Harness settings. If left empty, a plain chat agent is compiled.", "$ref": "#/components/schemas/HarnessSettings" } ] }, "compaction": { "oneOf": [ { "type": "null" }, { "description": "Context compaction settings. If left empty, no compaction is applied.", "$ref": "#/components/schemas/CompactionSettings" } ] }, "memory": { "oneOf": [ { "type": "null" }, { "description": "Memory provider settings. If left empty, no memory provider is added.", "$ref": "#/components/schemas/MemorySettings" } ] }, "metadata": { "type": "object", "description": "Free-form, application-specific metadata. See `AgentDefinition.Metadata`." }, "parameters": { "type": "array", "items": { "$ref": "#/components/schemas/AgentParameter" }, "description": "The parameter schema. See IReadOnlyList<AgentParameter> AgentDefinition.Parameters." }, "sharedInstructionsName": { "type": [ "null", "string" ], "description": "The referenced shared instructions block. See `AgentDefinition.SharedInstructionsName`." } }, "description": "Request to create or update an agent definition." }, "AgentDescriptor": { "required": [ "name", "origin", "sourceName" ], "type": "object", "properties": { "name": { "type": "string", "description": "Gets the unique name of the agent." }, "displayName": { "type": [ "null", "string" ], "description": "Gets the name shown in the user interface." }, "description": { "type": [ "null", "string" ], "description": "Gets the short description." }, "origin": { "description": "Gets the origin of the definition.", "$ref": "#/components/schemas/AgentDefinitionOrigin" }, "sourceName": { "type": "string", "description": "Gets the name of the source that supplies this agent, for example `code`\nor `database`. Several sources can share the same AgentDefinitionOrigin AgentDescriptor.Origin value." }, "version": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Gets the definition version. It is always 1 for code agents.", "format": "int32" }, "model": { "oneOf": [ { "type": "null" }, { "description": "Gets the bound model. It can be unknown for code agents.", "$ref": "#/components/schemas/ModelBinding" } ] }, "toolNames": { "type": "array", "items": { "type": "string" }, "description": "Gets the names of the tools this agent may use." }, "skillNames": { "type": "array", "items": { "type": "string" }, "description": "Gets the names of the skills this agent may load at run time." }, "callableAgentNames": { "type": "array", "items": { "type": "string" }, "description": "Gets the names of the other agents this agent may call." }, "usesHarness": { "type": "boolean", "description": "Gets whether the harness capabilities are enabled." }, "updatedAt": { "type": [ "null", "string" ], "description": "Gets the time of the last change (UTC).", "format": "date-time" } }, "description": "A summary view of an agent listed in the catalog. It carries everything the user\ninterface needs to draw the agent list, without having to build the agent. A source\nmust not mutate a descriptor or its nested collections after returning it." }, "AgentDetailResponse": { "required": [ "descriptor", "isEditable" ], "type": "object", "properties": { "descriptor": { "description": "Catalog summary.", "$ref": "#/components/schemas/AgentDescriptor" }, "definition": { "oneOf": [ { "type": "null" }, { "description": "The agent's definition. `null` only for a code agent built\nfrom a factory (`AddAgent(name, factory)`), which carries no\n`AgentDefinition` at all. A code agent declared with\n`AddAgent(AgentDefinition)` returns its in-memory definition here\ndespite never being written to the database.", "$ref": "#/components/schemas/AgentDefinition" } ] }, "factoryInstructions": { "type": [ "null", "string" ], "description": "Best-effort instructions read directly from the resolved agent when\n`Definition` is `null` because the agent is\nbuilt from a factory (`AddAgent(name, factory)`) and its concrete\ntype exposes them (currently only `Microsoft.Agents.AI.ChatClientAgent`).\n`null` when `Definition` is populated instead\n(read `Definition.Instructions` there), when the factory's concrete\ntype does not expose instructions, or when invoking the factory to check\nfailed — this field is diagnostic only and never blocks the response." }, "isEditable": { "type": "boolean", "description": "Whether this agent can be modified through the management API." } }, "description": "Detailed view of a single agent." }, "AgentParameter": { "required": [ "name", "kind" ], "type": "object", "properties": { "name": { "type": "string", "description": "Gets the parameter name, as referenced by `{{name}}` in the instructions text." }, "kind": { "description": "Gets the parameter's data kind.", "$ref": "#/components/schemas/AgentParameterKind" }, "required": { "type": "boolean", "description": "Gets whether a run must supply this parameter. A run missing a required\nparameter with no `DefaultValue` does not start." }, "defaultValue": { "type": [ "null", "string" ], "description": "Gets the value used when a run does not supply this parameter. Applies\nwhether or not `Required` is set." }, "description": { "type": [ "null", "string" ], "description": "Gets a short description shown to the person authoring a run." } }, "description": "A single named placeholder an AgentDefinition's instructions can\nreference as `{{name}}`." }, "AgentParameterKind": { "enum": [ "Text", "Number", "Boolean" ], "description": "The data kind of an AgentParameter." }, "AgentResponseFormat": { "required": [ "kind" ], "type": "object", "properties": { "kind": { "description": "Gets the requested format.", "$ref": "#/components/schemas/AgentResponseFormatKind" }, "schema": { "oneOf": [ { "type": "null" }, { "description": "Gets the JSON schema. It is populated only for\nAgentResponseFormatKind.JsonSchema and must be a JSON\nobject.", "$ref": "#/components/schemas/JsonElement" } ] }, "schemaName": { "type": [ "null", "string" ], "description": "Gets the name of the schema. The provider can pass it on to the model." }, "schemaDescription": { "type": [ "null", "string" ], "description": "Gets the description of the schema." } }, "description": "The definition of a structured output." }, "AgentResponseFormatKind": { "enum": [ "Text", "Json", "JsonSchema" ], "description": "The requested format of an agent response." }, "AgentRollbackRequest": { "required": [ "version" ], "type": "object", "properties": { "version": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Version number to roll back to.", "format": "int32" } }, "description": "Request to roll back a definition to a previous version." }, "AgentRunDocument": { "required": [ "name", "content" ], "type": "object", "properties": { "name": { "type": "string", "description": "Gets the document's name, shown to the model inside the delimiter." }, "content": { "type": "string", "description": "Gets the document's text. Never treated as instructions." } }, "description": "A piece of reference text attached to a single run, kept apart from the\nmodel's instructions." }, "AgentRunRequest": { "type": "object", "properties": { "message": { "type": [ "null", "string" ], "description": "User message. May be left empty only if IReadOnlyList<ToolApprovalDecision> AgentRunRequest.Approvals is sent." }, "sessionId": { "type": [ "null", "string" ], "description": "Session identifier. If not given, the run is sessionless and no history\nis carried." }, "lane": { "type": [ "null", "string" ], "description": "The lane a queued run (`Prefer: respond-async`) is queued under.\nSee `JobLanes`. Ignored for a synchronous run — nothing is\nqueued. Left empty, the run uses `JobLanes.Default` (or whatever\n`TraconSchedulingOptions.LaneByHandlerKey` maps\n`JobHandlerKeys.AgentRun` to)." }, "culture": { "type": [ "null", "string" ], "description": "The culture to resolve the agent's instructions with (see\n`AgentDefinition.InstructionsByCulture`). `null` uses the\nagent's default instructions." }, "approvals": { "type": "array", "items": { "$ref": "#/components/schemas/ToolApprovalDecision" }, "description": "Approval decisions for pending tool calls." }, "toolResults": { "type": "array", "items": { "$ref": "#/components/schemas/ClientToolResult" }, "description": "Results of client-side tool calls." }, "attachmentIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Identifiers of attachments previously uploaded via `POST /api/attachments`." }, "parameters": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "Values for the target agent's IReadOnlyList<AgentParameter> AgentDefinition.Parameters schema." }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/AgentRunDocument" }, "description": "Reference text attached to this run, kept apart from the agent's instructions." } }, "description": "Request for a trial run made from the UI." }, "AgentSkillDefinition": { "required": [ "tenantId", "name", "description", "instructions" ], "type": "object", "properties": { "id": { "type": "string", "description": "The skill's unique identifier.", "format": "uuid" }, "tenantId": { "type": "string", "description": "The tenant the skill belongs to." }, "name": { "type": "string", "description": "The skill name. Agent definitions bind to the skill with this name." }, "description": { "type": "string", "description": "The skill's short description." }, "instructions": { "type": "string", "description": "The markdown instructions given to the model." }, "compatibility": { "type": [ "null", "string" ], "description": "The skill's compatibility statement." }, "license": { "type": [ "null", "string" ], "description": "The skill license." }, "allowedTools": { "type": [ "null", "string" ], "description": "The allowed-tools declaration in the MAF frontmatter." }, "metadata": { "type": "object", "description": "Application-specific free-form metadata." }, "enabled": { "type": "boolean", "description": "Whether the skill is included in compilation." }, "version": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The skill record's version.", "format": "int32" }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSkillResourceDefinition" }, "description": "The skill's resources." }, "scripts": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSkillScriptDefinition" }, "description": "The skill's scripts stored in the database." }, "createdAt": { "type": "string", "description": "The skill's creation time.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "The skill's last-updated time.", "format": "date-time" } }, "description": "A markdown-based skill definition that can be loaded into an agent at run time." }, "AgentSkillRequest": { "required": [ "name", "description", "instructions" ], "type": "object", "properties": { "name": { "type": "string", "description": "Skill name." }, "description": { "type": "string", "description": "Skill description." }, "instructions": { "type": "string", "description": "Markdown instructions." }, "compatibility": { "type": [ "null", "string" ], "description": "Compatibility statement." }, "license": { "type": [ "null", "string" ], "description": "Skill license." }, "allowedTools": { "type": [ "null", "string" ], "description": "Allowed-tools declaration from the MAF frontmatter." }, "metadata": { "type": "object", "description": "Application-specific metadata." }, "enabled": { "type": "boolean", "description": "Whether the skill is enabled." }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSkillResourceDefinition" }, "description": "Skill resources." }, "scripts": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSkillScriptDefinition" }, "description": "Skill scripts." } }, "description": "Request to create or update a skill." }, "AgentSkillResourceDefinition": { "required": [ "name", "content" ], "type": "object", "properties": { "name": { "type": "string", "description": "The resource name, unique within the skill." }, "description": { "type": [ "null", "string" ], "description": "The resource description." }, "mediaType": { "type": "string", "description": "The resource media type." }, "content": { "type": "string", "description": "The resource's text content." } }, "description": "A readable resource carried with an AgentSkillDefinition." }, "AgentSkillScriptDefinition": { "required": [ "name", "extension", "content" ], "type": "object", "properties": { "name": { "type": "string", "description": "The script name, unique within the skill." }, "description": { "type": [ "null", "string" ], "description": "A description telling the model what the script does." }, "extension": { "type": "string", "description": "The file extension (without the dot, for example `py`). The\ninterpreter is selected from the allowlist through this value." }, "content": { "type": "string", "description": "The script's source text." }, "parametersSchema": { "type": [ "null", "string" ], "description": "The argument schema reported to the model. Must be a valid JSON Schema\nobject; if `null`, the script is called with no arguments." } }, "description": "A server-executable script stored together with an AgentSkillDefinition." }, "AgentSourceDiagnostic": { "required": [ "name", "priority", "implementation" ], "type": "object", "properties": { "name": { "type": "string", "description": "Gets the source name." }, "priority": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Gets the source priority.", "format": "int32" }, "implementation": { "type": "string", "description": "Gets the implementation type name." } }, "description": "Describes one agent source registered in the catalog." }, "AgentValidationReport": { "required": [ "valid", "inconclusive", "messages" ], "type": "object", "properties": { "valid": { "type": "boolean", "description": "Gets a value that is `true` when the definition carries no ValidationSeverity.Error." }, "inconclusive": { "type": "boolean", "description": "Gets a value that tells whether a check could not finish because a resource was\nunreachable, an MCP server for example. It does not affect `Valid`." }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationMessage" }, "description": "Gets every message found. Validation does not stop at the first error." } }, "description": "The result of a validation that builds an agent definition without saving it and\nwithout calling any model." }, "AgentVersionDiffResponse": { "required": [ "left", "right" ], "type": "object", "properties": { "left": { "description": "Left (usually older) side of the comparison.", "$ref": "#/components/schemas/AgentDefinition" }, "right": { "description": "Right (usually newer) side of the comparison.", "$ref": "#/components/schemas/AgentDefinition" } }, "description": "Raw JSON response for comparing two definition versions. The\ndiff is not computed on the server; the client compares the two raw\ndefinitions field by field." }, "AIAnnotation": { "type": "object", "anyOf": [ { "$ref": "#/components/schemas/AIAnnotationCitationAnnotation" }, { "$ref": "#/components/schemas/AIAnnotationBase" } ] }, "AIAnnotationBase": { "properties": { "annotatedRegions": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AnnotatedRegion" } }, "additionalProperties": { "type": [ "null", "object" ] } } }, "AIAnnotationCitationAnnotation": { "required": [ "$type" ], "properties": { "$type": { "enum": [ "citation" ], "type": "string" }, "title": { "type": [ "null", "string" ] }, "url": { "type": [ "null", "string" ], "format": "uri" }, "fileId": { "type": [ "null", "string" ] }, "toolName": { "type": [ "null", "string" ] }, "snippet": { "type": [ "null", "string" ] }, "annotatedRegions": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AnnotatedRegion" } }, "additionalProperties": { "type": [ "null", "object" ] } } }, "AIContent": { "type": "object", "anyOf": [ { "$ref": "#/components/schemas/AIContentDataContent" }, { "$ref": "#/components/schemas/AIContentErrorContent" }, { "$ref": "#/components/schemas/AIContentFunctionCallContent" }, { "$ref": "#/components/schemas/AIContentFunctionResultContent" }, { "$ref": "#/components/schemas/AIContentHostedFileContent" }, { "$ref": "#/components/schemas/AIContentHostedVectorStoreContent" }, { "$ref": "#/components/schemas/AIContentTextContent" }, { "$ref": "#/components/schemas/AIContentTextReasoningContent" }, { "$ref": "#/components/schemas/AIContentUriContent" }, { "$ref": "#/components/schemas/AIContentUsageContent" }, { "$ref": "#/components/schemas/AIContentToolCallContent" }, { "$ref": "#/components/schemas/AIContentToolResultContent" }, { "$ref": "#/components/schemas/AIContentInputRequestContent" }, { "$ref": "#/components/schemas/AIContentInputResponseContent" }, { "$ref": "#/components/schemas/AIContentToolApprovalRequestContent" }, { "$ref": "#/components/schemas/AIContentToolApprovalResponseContent" }, { "$ref": "#/components/schemas/AIContentMcpServerToolCallContent" }, { "$ref": "#/components/schemas/AIContentMcpServerToolResultContent" }, { "$ref": "#/components/schemas/AIContentImageGenerationToolCallContent" }, { "$ref": "#/components/schemas/AIContentImageGenerationToolResultContent" }, { "$ref": "#/components/schemas/AIContentCodeInterpreterToolCallContent" }, { "$ref": "#/components/schemas/AIContentCodeInterpreterToolResultContent" }, { "$ref": "#/components/schemas/AIContentWebSearchToolCallContent" }, { "$ref": "#/components/schemas/AIContentWebSearchToolResultContent" }, { "$ref": "#/components/schemas/AIContentBase" } ] }, "AIContentBase": { "properties": { "annotations": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AIAnnotation" } }, "additionalProperties": { "type": [ "null", "object" ] } } }, "AIContentCodeInterpreterToolCallContent": { "required": [ "$type", "callId" ], "properties": { "$type": { "enum": [ "codeInterpreterToolCall" ], "type": "string" }, "inputs": {}, "callId": { "type": "string" }, "annotations": {}, "additionalProperties": {} } }, "AIContentCodeInterpreterToolResultContent": { "required": [ "$type", "callId" ], "properties": { "$type": { "enum": [ "codeInterpreterToolResult" ], "type": "string" }, "outputs": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AIContent" } }, "callId": { "type": "string" }, "annotations": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AIAnnotation" } }, "additionalProperties": { "type": [ "null", "object" ] } } }, "AIContentDataContent": { "required": [ "$type", "uri" ], "properties": { "$type": { "enum": [ "data" ], "type": "string" }, "uri": { "type": "string", "description": "A data URI representing the content." }, "name": { "type": [ "null", "string" ] }, "annotations": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AIAnnotation" } }, "additionalProperties": { "type": [ "null", "object" ] } } }, "AIContentErrorContent": { "required": [ "$type", "message" ], "properties": { "$type": { "enum": [ "error" ], "type": "string" }, "message": { "type": [ "null", "string" ] }, "errorCode": { "type": [ "null", "string" ] }, "details": { "type": [ "null", "string" ] }, "annotations": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AIAnnotation" } }, "additionalProperties": { "type": [ "null", "object" ] } } }, "AIContentFunctionCallContent": { "required": [ "$type", "name", "callId" ], "properties": { "$type": { "enum": [ "functionCall" ], "type": "string" }, "name": { "type": "string" }, "arguments": { "type": [ "null", "object" ] }, "informationalOnly": { "type": "boolean" }, "callId": { "type": "string" }, "annotations": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AIAnnotation" } }, "additionalProperties": { "type": [ "null", "object" ] } } }, "AIContentFunctionResultContent": { "required": [ "$type", "result", "callId" ], "properties": { "$type": { "enum": [ "functionResult" ], "type": "string" }, "result": {}, "callId": { "type": "string" }, "annotations": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AIAnnotation" } }, "additionalProperties": { "type": [ "null", "object" ] } } }, "AIContentHostedFileContent": { "required": [ "$type", "fileId" ], "properties": { "$type": { "enum": [ "hostedFile" ], "type": "string" }, "fileId": { "type": "string" }, "mediaType": { "type": [ "null", "string" ] }, "name": { "type": [ "null", "string" ] }, "sizeInBytes": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int64" }, "createdAt": { "type": [ "null", "string" ], "format": "date-time" }, "purpose": { "type": [ "null", "string" ] }, "scope": { "type": [ "null", "string" ] }, "annotations": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AIAnnotation" } }, "additionalProperties": { "type": [ "null", "object" ] } } }, "AIContentHostedVectorStoreContent": { "required": [ "$type", "vectorStoreId" ], "properties": { "$type": { "enum": [ "hostedVectorStore" ], "type": "string" }, "vectorStoreId": { "type": "string" }, "annotations": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AIAnnotation" } }, "additionalProperties": { "type": [ "null", "object" ] } } }, "AIContentImageGenerationToolCallContent": { "required": [ "$type", "callId" ], "properties": { "$type": { "enum": [ "imageGenerationToolCall" ], "type": "string" }, "callId": { "type": "string" }, "annotations": {}, "additionalProperties": {} } }, "AIContentImageGenerationToolResultContent": { "required": [ "$type", "callId" ], "properties": { "$type": { "enum": [ "imageGenerationToolResult" ], "type": "string" }, "outputs": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AIContent" } }, "callId": { "type": "string" }, "annotations": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AIAnnotation" } }, "additionalProperties": { "type": [ "null", "object" ] } } }, "AIContentInputRequestContent": { "required": [ "$type" ], "properties": { "$type": { "enum": [ "inputRequest" ], "type": "string" }, "requestId": { "type": [ "null", "string" ] }, "annotations": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AIAnnotation" } }, "additionalProperties": { "type": [ "null", "object" ] } } }, "AIContentInputResponseContent": { "required": [ "$type" ], "properties": { "$type": { "enum": [ "inputResponse" ], "type": "string" }, "requestId": { "type": [ "null", "string" ] }, "annotations": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AIAnnotation" } }, "additionalProperties": { "type": [ "null", "object" ] } } }, "AIContentMcpServerToolCallContent": { "required": [ "$type", "name", "serverName", "callId" ], "properties": { "$type": { "enum": [ "mcpServerToolCall" ], "type": "string" }, "name": { "type": "string" }, "serverName": { "type": [ "null", "string" ] }, "arguments": {}, "callId": { "type": "string" }, "annotations": {}, "additionalProperties": {} } }, "AIContentMcpServerToolResultContent": { "required": [ "$type", "callId" ], "properties": { "$type": { "enum": [ "mcpServerToolResult" ], "type": "string" }, "outputs": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AIContent" } }, "callId": { "type": "string" }, "annotations": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AIAnnotation" } }, "additionalProperties": { "type": [ "null", "object" ] } } }, "AIContentTextContent": { "required": [ "$type", "text" ], "properties": { "$type": { "enum": [ "text" ], "type": "string" }, "text": { "type": [ "null", "string" ] }, "annotations": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AIAnnotation" } }, "additionalProperties": { "type": [ "null", "object" ] } } }, "AIContentTextReasoningContent": { "required": [ "$type", "text" ], "properties": { "$type": { "enum": [ "reasoning" ], "type": "string" }, "text": { "type": [ "null", "string" ] }, "protectedData": { "type": [ "null", "string" ] }, "annotations": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AIAnnotation" } }, "additionalProperties": { "type": [ "null", "object" ] } } }, "AIContentToolApprovalRequestContent": { "required": [ "$type", "toolCall", "requestId" ], "properties": { "$type": { "enum": [ "toolApprovalRequest" ], "type": "string" }, "toolCall": { "$ref": "#/components/schemas/ToolCallContent" }, "requiresConfirmation": { "type": "boolean" }, "requestId": { "type": "string" }, "annotations": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AIAnnotation" } }, "additionalProperties": { "type": [ "null", "object" ] } } }, "AIContentToolApprovalResponseContent": { "required": [ "$type", "approved", "toolCall", "requestId" ], "properties": { "$type": { "enum": [ "toolApprovalResponse" ], "type": "string" }, "approved": { "type": "boolean" }, "toolCall": { "$ref": "#/components/schemas/ToolCallContent" }, "reason": { "type": [ "null", "string" ] }, "requestId": { "type": "string" }, "annotations": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AIAnnotation" } }, "additionalProperties": { "type": [ "null", "object" ] } } }, "AIContentToolCallContent": { "required": [ "$type", "callId" ], "properties": { "$type": { "enum": [ "toolCall" ], "type": "string" }, "callId": { "type": "string" }, "annotations": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AIAnnotation" } }, "additionalProperties": { "type": [ "null", "object" ] } } }, "AIContentToolResultContent": { "required": [ "$type", "callId" ], "properties": { "$type": { "enum": [ "toolResult" ], "type": "string" }, "callId": { "type": "string" }, "annotations": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AIAnnotation" } }, "additionalProperties": { "type": [ "null", "object" ] } } }, "AIContentUriContent": { "required": [ "$type", "uri" ], "properties": { "$type": { "enum": [ "uri" ], "type": "string" }, "uri": { "type": "string", "format": "uri" }, "mediaType": { "type": [ "null", "string" ] }, "annotations": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AIAnnotation" } }, "additionalProperties": { "type": [ "null", "object" ] } } }, "AIContentUsageContent": { "required": [ "$type", "details" ], "properties": { "$type": { "enum": [ "usage" ], "type": "string" }, "details": { "$ref": "#/components/schemas/UsageDetails" }, "annotations": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AIAnnotation" } }, "additionalProperties": { "type": [ "null", "object" ] } } }, "AIContentWebSearchToolCallContent": { "required": [ "$type", "callId" ], "properties": { "$type": { "enum": [ "webSearchToolCall" ], "type": "string" }, "queries": {}, "callId": { "type": "string" }, "annotations": {}, "additionalProperties": {} } }, "AIContentWebSearchToolResultContent": { "required": [ "$type", "callId" ], "properties": { "$type": { "enum": [ "webSearchToolResult" ], "type": "string" }, "outputs": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AIContent" } }, "callId": { "type": "string" }, "annotations": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AIAnnotation" } }, "additionalProperties": { "type": [ "null", "object" ] } } }, "AnnotatedRegion": { "type": "object" }, "ApiKeyCreateRequest": { "type": "object", "properties": { "name": { "type": [ "null", "string" ], "description": "Gets the name that lets the operator identify the key." }, "scopes": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/ApiKeyScope" }, "description": "Gets the set of scopes. Cannot be empty; an unknown value is rejected." }, "expiresAt": { "type": [ "null", "string" ], "description": "Gets the expiration time. If not given, the key never expires.", "format": "date-time" } }, "description": "The request body for creating an API key." }, "ApiKeyCreationResult": { "required": [ "record", "plaintextKey" ], "type": "object", "properties": { "record": { "description": "The saved view, which carries no raw value.", "$ref": "#/components/schemas/ApiKeyRecord" }, "plaintextKey": { "type": "string", "description": "The raw key value. Cannot be produced again after this call; the\nconsumer must show it immediately and not store it." } }, "description": "The result of a key creation operation." }, "ApiKeyRecord": { "required": [ "id", "tenantId", "name", "keyPrefix", "scopes", "createdAt" ], "type": "object", "properties": { "id": { "type": "string", "description": "The key identifier.", "format": "uuid" }, "tenantId": { "type": "string", "description": "The tenant the key is bound to. On authentication, the tenant is resolved FROM HERE." }, "name": { "type": "string", "description": "The name for the operator to recognize the key by." }, "keyPrefix": { "type": "string", "description": "The raw value's first characters; used to distinguish the key in a list." }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyScope" }, "description": "The scope set. The effective authority is `role ∩ scope`." }, "expiresAt": { "type": [ "null", "string" ], "description": "The expiration. Never expires if `null`.", "format": "date-time" }, "revokedAt": { "type": [ "null", "string" ], "description": "The revocation timestamp. The row is NOT DELETED; the audit trail is preserved through this field.", "format": "date-time" }, "lastUsedAt": { "type": [ "null", "string" ], "description": "The last-used time. Used to spot an unused key.", "format": "date-time" }, "createdAt": { "type": "string", "description": "The creation time (UTC).", "format": "date-time" }, "isActive": { "type": "boolean", "description": "`true` if the key is not revoked and has not expired." } }, "description": "An API key's database-stored view, WHICH CARRIES NO RAW VALUE." }, "ApiKeyScope": { "enum": [ "RunsRead", "RunsWrite", "AgentsRead", "AgentsAdmin", "ExternalInvoke", "KnowledgeRead", "KnowledgeAdmin", "WorkflowsRead", "WorkflowsAdmin", "EvalsRead", "EvalsAdmin", "ExperimentsRead", "ExperimentsAdmin", "PlatformRead", "PlatformAdmin", "SecurityAdmin", "AuditRead" ], "description": "An authority scope an API key may open." }, "ApprovalDecisionRequest": { "required": [ "approved" ], "type": "object", "properties": { "approved": { "type": "boolean", "description": "Gets whether the request was approved." } }, "description": "Request body for deciding a pending approval request." }, "ApprovalStatus": { "enum": [ "Pending", "Approved", "Rejected", "Expired" ], "description": "The status of a pending approval request." }, "AttachmentDescriptor": { "required": [ "id", "tenantId", "fileName", "mediaType", "byteSize", "sha256", "createdAt" ], "type": "object", "properties": { "id": { "type": "string", "description": "Gets the attachment id.", "format": "uuid" }, "tenantId": { "type": "string", "description": "Gets the tenant the attachment belongs to." }, "sessionId": { "type": [ "null", "string" ], "description": "Gets the session the attachment was uploaded to. `null` for an\nupload without a session." }, "runId": { "type": [ "null", "string" ], "description": "Gets the run that produced the attachment. `null` for a user upload.", "format": "uuid" }, "fileName": { "type": "string", "description": "Gets the original file name." }, "mediaType": { "type": "string", "description": "Gets the validated MIME type. It is the result of the magic-byte check, not the\n`Content-Type` the client sent." }, "byteSize": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Gets the size of the content in bytes.", "format": "int64" }, "sha256": { "type": "string", "description": "Gets the SHA-256 digest of the content (hexadecimal, upper case)." }, "createdBy": { "type": [ "null", "string" ], "description": "Gets the actor that uploaded it, or `null` when it is unknown." }, "createdAt": { "type": "string", "description": "Gets the upload time.", "format": "date-time" } }, "description": "The metadata of an uploaded attachment." }, "AuditChainStatus": { "enum": [ "Valid", "Broken", "Gap" ], "description": "The result of walking a tenant's audit trail hash chain." }, "AuditChainVerification": { "required": [ "status", "entriesChecked" ], "type": "object", "properties": { "status": { "description": "Gets the overall chain status.", "$ref": "#/components/schemas/AuditChainStatus" }, "entriesChecked": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Gets the number of entries walked.", "format": "int32" }, "firstFailingEntryId": { "type": [ "null", "string" ], "description": "Gets the id of the first entry where the chain fails; `null`\nwhen AuditChainStatus AuditChainVerification.Status is `AuditChainStatus.Valid`.", "format": "uuid" } }, "description": "The result of verifying one tenant's audit trail hash chain." }, "AuditEntry": { "required": [ "id", "tenantId", "action", "entity", "createdAt" ], "type": "object", "properties": { "id": { "type": "string", "description": "Gets the record id. A time-ordered UUID (v7).", "format": "uuid" }, "tenantId": { "type": "string", "description": "Gets the tenant the change belongs to." }, "actor": { "type": [ "null", "string" ], "description": "Gets the actor that made the change. It is `null` when there is no\nauthentication or the actor cannot be resolved; that state is not hidden." }, "action": { "type": "string", "description": "Gets the action name, for example `agent.update`." }, "entity": { "type": "string", "description": "Gets the affected entity, for example `agent:support`." }, "before": { "type": [ "null", "string" ], "description": "Gets the state before the change, as JSON text. It has passed the secret filter." }, "after": { "type": [ "null", "string" ], "description": "Gets the state after the change, as JSON text. It has passed the secret filter." }, "createdAt": { "type": "string", "description": "Gets the time the record was written (UTC).", "format": "date-time" }, "previousHash": { "type": [ "null", "string" ], "description": "Gets the hash of the previous entry of the same tenant.\n`null` for the first entry of a tenant." }, "hash": { "type": [ "null", "string" ], "description": "Gets the hash of this entry, derived from its canonical form\n(see `AuditChainHasher` in `Tracon.Core`). The write path\ncomputes this value; a caller-supplied value is ignored." } }, "description": "A row in the audit trail that records who changed which entity and when." }, "CanaryDecisionKind": { "enum": [ "InsufficientData", "Healthy", "RollBack" ], "description": "Defines the outcome of a canary evaluation." }, "CanaryEvaluation": { "required": [ "decision", "reason", "evaluatedAt" ], "type": "object", "properties": { "decision": { "description": "Gets the evaluation outcome.", "$ref": "#/components/schemas/CanaryDecisionKind" }, "reason": { "type": "string", "description": "Gets the human-readable reason for the decision." }, "canary": { "oneOf": [ { "type": "null" }, { "description": "Gets the current canary variant results. Returns `null` when no runs exist.", "$ref": "#/components/schemas/ExperimentVariantResult" } ] }, "control": { "oneOf": [ { "type": "null" }, { "description": "Gets the current control variant results. Returns `null` when no runs exist.", "$ref": "#/components/schemas/ExperimentVariantResult" } ] }, "evaluatedAt": { "type": "string", "description": "Gets the UTC time when the evaluation occurred.", "format": "date-time" } }, "description": "Represents the result of evaluating a canary policy against the current results\nof the canary and control variants." }, "CanaryPolicy": { "required": [ "canaryVariant" ], "type": "object", "properties": { "canaryVariant": { "type": "string", "description": "Gets the canary variant name. It must exist in the experiment `Variants` list." }, "maxErrorRateDelta": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "description": "Gets the maximum absolute error-rate difference from the control, from 0.0\nthrough 1.0. The canary rolls back when its rate is higher. No error-rate\ncheck runs when this value is `null`.", "format": "double" }, "minScore": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Gets the minimum average canary score from 0 through 100. The canary rolls\nback below this threshold. No score check runs when this value is\n`null`.", "format": "int32" }, "minSampleSize": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Gets the minimum completed run count that both the canary and control\nvariants must reach before a decision is made.", "format": "int32" }, "rampSteps": { "type": "array", "items": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "description": "Gets the canary-weight steps that increase over time, for example\n`[5, 25, 50, 100]`. An empty list disables gradual increases. The\ncanary weight stays at the value set through `SaveAsync` and only\nrollback is evaluated." }, "rampInterval": { "pattern": "^-?(\\d+\\.)?\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,7})?$", "type": "string", "description": "Gets the minimum time between steps." } }, "description": "Defines automatic rollback and gradual traffic-increase rules for an experiment canary variant." }, "ChatChoice": { "required": [ "index", "message", "finish_reason" ], "type": "object", "properties": { "index": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "message": { "$ref": "#/components/schemas/ChatMessagePayload" }, "finish_reason": { "type": [ "null", "string" ] } } }, "ChatCompletion": { "required": [ "id", "object", "created", "model", "choices", "usage" ], "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "created": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "model": { "type": "string" }, "choices": { "type": "array", "items": { "$ref": "#/components/schemas/ChatChoice" } }, "usage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ChatUsage" } ] } } }, "ChatMessage": { "type": "object", "properties": { "authorName": { "type": [ "null", "string" ] }, "createdAt": { "type": [ "null", "string" ], "format": "date-time" }, "role": { "$ref": "#/components/schemas/ChatRole" }, "contents": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AIContent" } }, "messageId": { "type": [ "null", "string" ] }, "additionalProperties": { "type": [ "null", "object" ] } } }, "ChatMessagePayload": { "required": [ "role", "content" ], "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": [ "null", "string" ] } } }, "ChatRole": {}, "ChatUsage": { "required": [ "prompt_tokens", "completion_tokens", "total_tokens" ], "type": "object", "properties": { "prompt_tokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "completion_tokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "total_tokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" } } }, "ClientToolResult": { "required": [ "callId" ], "type": "object", "properties": { "callId": { "type": "string", "description": "Identifier of the pending call this result answers. Matches the\n`FunctionCallContent.CallId` the run response carried." }, "result": { "type": [ "null", "string" ], "description": "The tool's result, given to the model as plain text. Required unless\n`ErrorMessage` is given." }, "errorMessage": { "type": [ "null", "string" ], "description": "A message describing why the client-side call failed, given to the\nmodel instead of `Result`." } }, "description": "The result of a single client-side tool call, sent back so the run can\ncontinue." }, "CompactionSettings": { "type": "object", "properties": { "strategy": { "description": "Gets the strategy to apply.", "$ref": "#/components/schemas/CompactionStrategyKind" }, "triggerTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Gets the token count above which compaction is triggered.", "format": "int32" }, "triggerMessages": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Gets the message count above which compaction is triggered.", "format": "int32" }, "triggerTurns": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Gets the turn count above which compaction is triggered.", "format": "int32" }, "minimumPreservedTurns": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Gets the minimum number of turns kept for\nCompactionStrategyKind.SlidingWindow. 2 is used when it is not given.", "format": "int32" }, "minimumPreservedGroups": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Gets the minimum number of groups kept for CompactionStrategyKind.Truncation,\nCompactionStrategyKind.ToolResult and\nCompactionStrategyKind.Summarization. 4 is used when it is not given.", "format": "int32" }, "maxContextWindowTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Gets the context window size. It is required for\nCompactionStrategyKind.ContextWindow and ignored by the other strategies.", "format": "int32" }, "maxOutputTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Gets the upper output token limit for CompactionStrategyKind.ContextWindow.\nWhen it is not given, `ModelBinding.MaxOutputTokens` from the agent's own\nmodel binding is used, and 4096 when that is missing too.", "format": "int32" }, "summarizationPrompt": { "type": [ "null", "string" ], "description": "Gets the extra instruction added to the summarization prompt for\nCompactionStrategyKind.Summarization and\nCompactionStrategyKind.Pipeline. When `null` the\ndefault prompt of MAF is used." }, "summarizationModel": { "oneOf": [ { "type": "null" }, { "description": "Gets the model used for the summarization call. When it is empty the order is\nfollowed: the application-wide helper model setting, and the agent's own model\nwhen that is missing.", "$ref": "#/components/schemas/ModelBinding" } ] } }, "description": "Determines how an agent compacts its conversation history." }, "CompactionStrategyKind": { "enum": [ "None", "SlidingWindow", "Truncation", "ToolResult", "Summarization", "ContextWindow", "Pipeline" ], "description": "The kind of context compaction strategy that can be bound to an agent definition." }, "ConfigurationDiagnostic": { "required": [ "key", "resolved" ], "type": "object", "properties": { "key": { "type": "string", "description": "Gets the full configuration key path, for example `Tracon:Providers:OpenAI:ApiKey`." }, "resolved": { "type": "boolean", "description": "Gets whether the key resolves to a non-empty value." }, "hint": { "type": [ "null", "string" ], "description": "Gets guidance for configuring an unresolved key. The server provides it and the\nUI does not translate it." } }, "description": "Reports whether a configuration key resolves. It does not carry the value." }, "ContextWindowEstimate": { "required": [ "promptTokens", "contextWindowTokens", "allowedPromptTokens", "wouldBeRejected" ], "type": "object", "properties": { "promptTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Gets the estimated token count of the prompt. The estimate is approximate.", "format": "int32" }, "contextWindowTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Gets the model's context window size, taken from the model catalog's\n`ModelDescriptor.ContextWindowTokens`.\n`null` when the model is not found in the catalog.", "format": "int32" }, "allowedPromptTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Gets the token budget kept for the prompt after\n`TraconPreflightOptions.ReserveRatio` is set aside for\nthe answer. `null` when `ContextWindowTokens` is unknown.", "format": "int32" }, "wouldBeRejected": { "type": "boolean", "description": "Gets whether a real run with this prompt would be rejected by the\npre-flight check. Always `false` when\n`ContextWindowTokens` is unknown — an unknown window can never\nbe exceeded." } }, "description": "The result of a pre-flight context-window check, computed without calling\nthe model provider." }, "ConversationResource": { "required": [ "id", "object", "created_at", "metadata" ], "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "created_at": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "metadata": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" } } } }, "CurrentTenantResponse": { "required": [ "tenantId" ], "type": "object", "properties": { "tenantId": { "type": "string", "description": "Tenant identifier." } }, "description": "Tenant of the current request." }, "DataSubjectErasureResult": { "required": [ "dryRun", "rowsByTarget" ], "type": "object", "properties": { "dryRun": { "type": "boolean", "description": "Gets whether this was a preview: `true` means\nIReadOnlyDictionary<string, int> DataSubjectErasureResult.RowsByTarget shows what WOULD be deleted and nothing was\nactually removed." }, "rowsByTarget": { "type": "object", "additionalProperties": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "description": "Gets the number of rows removed (or, for a preview, that would be removed), by target table." } }, "description": "The outcome of a data subject erasure request." }, "DeletedResource": { "required": [ "id", "object", "deleted" ], "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "deleted": { "type": "boolean" } } }, "EvalCase": { "required": [ "suiteId", "seq", "query" ], "type": "object", "properties": { "id": { "type": "string", "description": "The case identifier.", "format": "uuid" }, "suiteId": { "type": "string", "description": "The identifier of the suite this case belongs to.", "format": "uuid" }, "seq": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The sequence number within the suite (starts at 0).", "format": "int32" }, "query": { "type": "string", "description": "The query text sent to the agent." }, "expectedOutput": { "type": [ "null", "string" ], "description": "The expected output. Referenced by the `containsExpected` check." }, "expectedTools": { "type": "array", "items": { "type": "string" }, "description": "The tool names this case is expected to exercise, recorded for reference." }, "context": { "type": [ "null", "string" ], "description": "Text given to the model as extra context." }, "sourceRunId": { "type": [ "null", "string" ], "description": "The run the case was generated from. `null` when hand-written.", "format": "uuid" }, "sourceKind": { "oneOf": [ { "type": "null" }, { "description": "The reason for promotion. `null` when hand-written.", "$ref": "#/components/schemas/EvalCaseSource" } ] }, "promotedAt": { "type": [ "null", "string" ], "description": "The promotion time. `null` when hand-written.", "format": "date-time" }, "parameters": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "Values for the target agent's IReadOnlyList<AgentParameter> AgentDefinition.Parameters\nschema. `null` for an agent that declares no parameters." } }, "description": "A single test case inside an EvalSuite." }, "EvalCaseDiff": { "required": [ "caseId", "kind" ], "type": "object", "properties": { "caseId": { "type": "string", "description": "The identifier of the case being compared.", "format": "uuid" }, "kind": { "description": "Which bucket this case falls into.", "$ref": "#/components/schemas/EvalCaseDiffKind" }, "baselinePassed": { "type": [ "null", "boolean" ], "description": "Whether the case passed on the baseline side.\n`null` when the case is EvalCaseDiffKind.Added." }, "candidatePassed": { "type": [ "null", "boolean" ], "description": "Whether the case passed on the candidate side.\n`null` when the case is EvalCaseDiffKind.Removed." }, "baselineRunId": { "type": [ "null", "string" ], "description": "The identifier of the agent run the baseline result came from, so a\nregression can be traced to the exact conversation.", "format": "uuid" }, "candidateRunId": { "type": [ "null", "string" ], "description": "The identifier of the agent run the candidate result came from.", "format": "uuid" }, "baselineFailureReason": { "type": [ "null", "string" ], "description": "The baseline side's failure reason, when it failed." }, "candidateFailureReason": { "type": [ "null", "string" ], "description": "The candidate side's failure reason, when it failed." } }, "description": "One case's outcome on both sides of an EvalRunDiff." }, "EvalCaseDiffKind": { "enum": [ "Unchanged", "Fixed", "Regressed", "StillFailing", "Added", "Removed" ], "description": "The bucket an aligned case falls into within an EvalRunDiff." }, "EvalCaseInput": { "required": [ "query" ], "type": "object", "properties": { "query": { "type": "string", "description": "Query text to send to the agent." }, "expectedOutput": { "type": [ "null", "string" ], "description": "Expected output." }, "expectedTools": { "type": "array", "items": { "type": "string" }, "description": "Tool names looked for by the `toolCalled` check." }, "context": { "type": [ "null", "string" ], "description": "Text to give the model as extra context." } }, "description": "Input shape of an eval case (in a request)." }, "EvalCasePromotionRequest": { "type": "object", "properties": { "sourceKind": { "oneOf": [ { "type": "null" }, { "description": "Overrides the promotion reason. If not given, it is derived\nautomatically from the run's status and score.", "$ref": "#/components/schemas/EvalCaseSource" } ] } }, "description": "Request to promote a run to a case." }, "EvalCaseResult": { "required": [ "evalRunId", "caseId", "passed" ], "type": "object", "properties": { "id": { "type": "string", "description": "The result record identifier.", "format": "uuid" }, "evalRunId": { "type": "string", "description": "The identifier of the run this result belongs to.", "format": "uuid" }, "caseId": { "type": "string", "description": "The identifier of the case being measured.", "format": "uuid" }, "runId": { "type": [ "null", "string" ], "description": "The identifier of the run record created while processing this case.\nThis lets an eval failure jump straight to its transcript and span tree.", "format": "uuid" }, "passed": { "type": "boolean", "description": "Reports whether the case passed all of its checks." }, "output": { "type": [ "null", "string" ], "description": "The text output produced by the agent." }, "scores": { "description": "Per-check score list (free-form JSON).", "$ref": "#/components/schemas/JsonElement" }, "failureReason": { "type": [ "null", "string" ], "description": "The failure reason. Populated only when `Passed` is `false`." } }, "description": "The result of a single EvalCase within an EvalRun." }, "EvalCaseSource": { "enum": [ "FailedRun", "NegativeScore", "ReferenceRun", null ] }, "EvalRun": { "required": [ "id", "tenantId", "suiteId", "status", "startedAt" ], "type": "object", "properties": { "id": { "type": "string", "description": "The run identifier.", "format": "uuid" }, "tenantId": { "type": "string", "description": "The tenant the run belongs to." }, "suiteId": { "type": "string", "description": "The identifier of the suite being measured.", "format": "uuid" }, "jobId": { "type": [ "null", "string" ], "description": "The identifier of the job record responsible for executing this run. The\nrun is executed through the job queue (IJobStore).", "format": "uuid" }, "agentVersion": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "The agent definition version being measured. `null` before the run starts.", "format": "int32" }, "modelId": { "type": [ "null", "string" ], "description": "The model identifier being measured. `null` before the run starts." }, "status": { "description": "The current status of the run.", "$ref": "#/components/schemas/EvalRunStatus" }, "total": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The total number of cases.", "format": "int32" }, "passed": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of cases that passed.", "format": "int32" }, "failed": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of remaining (failed) cases.", "format": "int32" }, "inputTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "The total input token count.", "format": "int64" }, "outputTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "The total output token count.", "format": "int64" }, "startedAt": { "type": "string", "description": "The start time (UTC).", "format": "date-time" }, "completedAt": { "type": [ "null", "string" ], "description": "The completion time (UTC). `null` while the run is in progress.", "format": "date-time" } }, "description": "A single execution record and summary of an EvalSuite." }, "EvalRunDetailResponse": { "required": [ "run", "results" ], "type": "object", "properties": { "run": { "description": "Run summary.", "$ref": "#/components/schemas/EvalRun" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/EvalCaseResult" }, "description": "Per-case results." } }, "description": "Detailed view of a single eval run: summary and case results together." }, "EvalRunDiff": { "required": [ "baseline", "candidate", "cases", "totalCases", "unchangedCount", "fixedCount", "regressedCount", "stillFailingCount", "addedCount", "removedCount" ], "type": "object", "properties": { "baseline": { "description": "The run being compared against (the older, known-good side).", "$ref": "#/components/schemas/EvalRun" }, "candidate": { "description": "The run being judged.", "$ref": "#/components/schemas/EvalRun" }, "cases": { "type": "array", "items": { "$ref": "#/components/schemas/EvalCaseDiff" }, "description": "The requested page of aligned cases, ordered so that the buckets an\nengineer looks for come first: EvalCaseDiffKind.Regressed,\nEvalCaseDiffKind.StillFailing,\nEvalCaseDiffKind.Added, EvalCaseDiffKind.Fixed,\nEvalCaseDiffKind.Removed, then\nEvalCaseDiffKind.Unchanged; within a bucket by case\nidentifier." }, "totalCases": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of aligned cases across both runs, ignoring paging.", "format": "int32" }, "unchangedCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of cases that passed on both sides.", "format": "int32" }, "fixedCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of cases that failed on the baseline and pass now.", "format": "int32" }, "regressedCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of cases that passed on the baseline and fail now.", "format": "int32" }, "stillFailingCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of cases that failed on both sides.", "format": "int32" }, "addedCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of cases present only in the candidate run.", "format": "int32" }, "removedCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of cases present only in the baseline run.", "format": "int32" } }, "description": "The case-by-case difference between two completed EvalRun\nrecords of the same suite." }, "EvalRunStatus": { "enum": [ "Pending", "Running", "Completed", "Failed", "Cancelled" ], "description": "The status of an eval run." }, "EvalRunTriggerRequest": { "type": "object", "properties": { "modelId": { "type": [ "null", "string" ], "description": "Model identifier to record for this run. If not given, the model in\nthe agent's current definition is used." }, "numRepetitions": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Number of times to repeat each case to measure its stability. If not\ngiven, 1.", "format": "int32" }, "agentVersion": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Definition version to measure for this run. If not given, the agent's\ncurrent version is used. Rejected with 400 for code-sourced agents (no\nversion history).", "format": "int32" } }, "description": "Request to trigger an eval run immediately." }, "EvalSuite": { "required": [ "tenantId", "name", "agentName" ], "type": "object", "properties": { "id": { "type": "string", "description": "The suite identifier.", "format": "uuid" }, "tenantId": { "type": "string", "description": "The tenant the suite belongs to." }, "name": { "type": "string", "description": "The suite name. Unique within the tenant." }, "description": { "type": [ "null", "string" ], "description": "A short description." }, "agentName": { "type": "string", "description": "The name of the agent this suite measures." }, "checks": { "description": "The check definitions. Example: `[{\"kind\":\"nonEmpty\",\"minLength\":10}]`.", "$ref": "#/components/schemas/JsonElement" }, "createdAt": { "type": "string", "description": "The creation time (UTC).", "format": "date-time" }, "updatedAt": { "type": "string", "description": "The last-updated time (UTC).", "format": "date-time" } }, "description": "An evaluation (eval) suite defined for an agent: carries which agent is\nmeasured, with which checks." }, "EvalSuiteSaveRequest": { "required": [ "agentName" ], "type": "object", "properties": { "description": { "type": [ "null", "string" ], "description": "Short description." }, "agentName": { "type": "string", "description": "Name of the agent this suite measures." }, "checks": { "description": "Check definitions. See `EvalSuite.Checks`.", "$ref": "#/components/schemas/JsonElement" } }, "description": "Request to create/update an eval suite." }, "Experiment": { "required": [ "id", "tenantId", "name", "agentName", "variants" ], "type": "object", "properties": { "id": { "type": "string", "description": "Gets the experiment identifier.", "format": "uuid" }, "tenantId": { "type": "string", "description": "Gets the tenant that owns the experiment." }, "name": { "type": "string", "description": "Gets the experiment name. It is unique within the tenant and is used as an API route key." }, "agentName": { "type": "string", "description": "Gets the name of the agent whose traffic is split." }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/ExperimentVariant" }, "description": "Gets the experiment variants. Their weights must total 100." }, "status": { "description": "Gets the current experiment status.", "$ref": "#/components/schemas/ExperimentStatus" }, "assignmentKey": { "type": [ "null", "string" ], "description": "Gets a reserved value. Runtime assignment does not read it:\nthe assignment key is always the session identifier, or the run identifier\nwhen no session exists. The property is reserved for future strategies that\nassign outside a session, and setting it today changes nothing." }, "startedAt": { "type": [ "null", "string" ], "description": "Gets the time when the experiment entered ExperimentStatus.Running. Returns `null` while it is a\ndraft.", "format": "date-time" }, "endedAt": { "type": [ "null", "string" ], "description": "Gets the time when the experiment stopped. Returns `null` when\nit runs or never started.", "format": "date-time" }, "updatedAt": { "type": [ "null", "string" ], "description": "Gets the UTC time of the last update.", "format": "date-time" }, "canary": { "oneOf": [ { "type": "null" }, { "description": "Gets the canary policy. `null` disables automatic decisions,\nso no background service evaluates this experiment.", "$ref": "#/components/schemas/CanaryPolicy" } ] }, "rollbackReason": { "type": [ "null", "string" ], "description": "Gets the reason for an automatic rollback. Returns `null`\nwhen the experiment was stopped manually or was never stopped." } }, "description": "Represents an A/B experiment that splits traffic between two or more definition versions of the same agent." }, "ExperimentCanaryResponse": { "type": "object", "properties": { "policy": { "oneOf": [ { "type": "null" }, { "description": "The defined canary rule. `null` if none has been defined.", "$ref": "#/components/schemas/CanaryPolicy" } ] }, "evaluation": { "oneOf": [ { "type": "null" }, { "description": "Current evaluation of the rule. `null` if `Policy` is `null`.", "$ref": "#/components/schemas/CanaryEvaluation" } ] } }, "description": "Response for `GET /api/experiments/{name}/canary` — the rule AND its\ncurrent evaluation together." }, "ExperimentResultsResponse": { "required": [ "experiment", "results" ], "type": "object", "properties": { "experiment": { "description": "The experiment itself.", "$ref": "#/components/schemas/Experiment" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ExperimentVariantResult" }, "description": "Per-arm results." } }, "description": "Per-variant results view of an experiment." }, "ExperimentSaveRequest": { "required": [ "agentName", "variants" ], "type": "object", "properties": { "agentName": { "type": "string", "description": "Name of the agent whose traffic is split." }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/ExperimentVariant" }, "description": "The experiment's arms. Weights must sum to 100." } }, "description": "Request to create/update an experiment. The name comes from the path." }, "ExperimentStatus": { "enum": [ "Draft", "Running", "Stopped" ], "description": "Defines the lifecycle status of an A/B experiment." }, "ExperimentVariant": { "required": [ "name", "version", "weight" ], "type": "object", "properties": { "name": { "type": "string", "description": "Gets the variant name, for example `\"control\"` or `\"v3\"`. It must be\nunique within the experiment." }, "version": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Gets the `AgentDefinition.Version` number to serve.", "format": "int32" }, "weight": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Gets the traffic weight from 0 through 100. The weights of all experiment\nvariants must total exactly 100 or saving is rejected. See Experiment.", "format": "int32" } }, "description": "Defines one experiment variant: its definition version and traffic weight." }, "ExperimentVariantResult": { "required": [ "variant", "version", "totalRuns", "completedRuns", "failedRuns", "canceledRuns" ], "type": "object", "properties": { "variant": { "type": "string", "description": "Gets the variant name." }, "version": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Gets the definition version served by the variant.", "format": "int32" }, "totalRuns": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Gets the total number of runs assigned to this variant.", "format": "int64" }, "completedRuns": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Gets the number of successfully completed runs.", "format": "int64" }, "failedRuns": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Gets the number of runs that ended with an error.", "format": "int64" }, "canceledRuns": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Gets the number of cancelled runs.", "format": "int64" }, "inputTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Gets the total input tokens.", "format": "int64" }, "outputTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Gets the total output tokens.", "format": "int64" }, "totalTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Gets the total tokens.", "format": "int64" }, "totalCost": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "description": "Gets the total cost for this variant. Returns `null` when pricing is undefined.", "format": "double" }, "currency": { "type": [ "null", "string" ], "description": "Gets the currency. It is populated when `TotalCost` is populated." }, "averageDurationMs": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "description": "Gets the average duration of settled runs in milliseconds. Returns\n`null` when no run is settled.", "format": "double" }, "errorRate": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "description": "Gets the error rate among settled runs, from 0 through 1. It uses the same\ncalculation as `RunStatistics.ErrorRate`.", "format": "double" }, "averageScore": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "description": "Gets the average numeric score from 0 through 100 for runs assigned to this\nvariant. It uses the `RunScoreKind.Numeric` scores written by online evaluation.\nReturns `null` when no run is scored. This is not\n`0`; it means unknown, consistent with the existing `RunCost`\ncontract.", "format": "double" } }, "description": "Summarizes run results for an experiment variant (calculated in the store)." }, "ExtensionPointDiagnostic": { "required": [ "contract", "implementation", "isBuiltInDefault" ], "type": "object", "properties": { "contract": { "type": "string", "description": "Gets the contract's name, for example `ITenantContext`." }, "implementation": { "type": "string", "description": "Gets the registered implementation's type name." }, "isBuiltInDefault": { "type": "boolean", "description": "Gets whether the registration is Tracon's built-in default." } }, "description": "One host-bound extension point and whether the host replaced its built-in default." }, "HarnessSettings": { "type": "object", "properties": { "maxContextWindowTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Gets the token limit of the context window. Compaction starts once it is exceeded.", "format": "int32" }, "maxOutputTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Gets the upper token limit produced in a single response.", "format": "int32" }, "maximumIterationsPerRequest": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Gets the upper number of iterations allowed within a single request.", "format": "int32" }, "harnessInstructions": { "type": [ "null", "string" ], "description": "Gets the extra instructions passed to the harness." }, "disableCompaction": { "type": "boolean", "description": "Gets a value that turns off context compaction." }, "disableTodoProvider": { "type": "boolean", "description": "Gets a value that turns off todo tracking." }, "disableFileMemory": { "type": "boolean", "description": "Gets a value that turns off file memory." }, "disableWebSearch": { "type": "boolean", "description": "Gets a value that turns off web search." }, "disableToolAutoApproval": { "type": "boolean", "description": "Gets a value that turns off automatic tool approval. Once turned off, every tool\ncall waits for an explicit approval." }, "disableAgentSkillsProvider": { "type": "boolean", "description": "Gets a value that turns off the agent skills provider." }, "disableAgentModeProvider": { "type": "boolean", "description": "Gets a value that turns off the agent mode provider." }, "loop": { "oneOf": [ { "type": "null" }, { "description": "Gets the loop (run-until-done) settings. `null`, the\ndefault, leaves the loop off.", "$ref": "#/components/schemas/LoopSettings" } ] } }, "description": "Settings for the harness capabilities. It mirrors a safe subset of the\n`HarnessAgentOptions` structure of Microsoft Agent Framework." }, "IFormFile": { "type": "string", "format": "binary" }, "ImageGenerationOperatorRequest": { "type": "object", "properties": { "prompt": { "type": [ "null", "string" ], "description": "Gets the image prompt." }, "count": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Gets the number of images to generate. Defaults to one.", "format": "int32" }, "size": { "type": [ "null", "string" ], "description": "Gets the optional image size in WIDTHxHEIGHT form." }, "sessionId": { "type": [ "null", "string" ], "description": "Gets the session to which generated attachments belong." } }, "description": "The request body for an operator image-generation action." }, "ImageGenerationOperatorResponse": { "required": [ "attachments", "usage" ], "type": "object", "properties": { "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/AttachmentDescriptor" }, "description": "Gets the generated image attachments." }, "usage": { "description": "Gets the observed generation quantity and configured cost.", "$ref": "#/components/schemas/ToolCallUsage" } }, "description": "The result of an operator image-generation action." }, "IMcpToolRefresher": { "type": "object", "description": "Refreshes the tool list of remote MCP servers on demand." }, "InboundTriggerAcceptedResponse": { "required": [ "jobId", "location" ], "type": "object", "properties": { "runId": { "type": [ "null", "string" ], "description": "Gets the identifier of the queued run, when the trigger targets an\nagent. `null` for a workflow target — a workflow job\nis not tied to a single run id until it is picked up from the queue.", "format": "uuid" }, "jobId": { "type": "string", "description": "Gets the identifier of the queued job.", "format": "uuid" }, "location": { "type": "string", "description": "Gets the address to poll for the outcome. Same as the `Location` header." }, "eventsLocation": { "type": [ "null", "string" ], "description": "Gets the address of the run's event stream. `null` for a workflow target." } }, "description": "The response for a successfully accepted inbound trigger event." }, "InboundTriggerPayloadMode": { "enum": [ "WholeBody", "Path" ], "description": "How an inbound trigger's request body becomes the agent/workflow message." }, "InboundTriggerResponse": { "required": [ "name", "targetKind", "targetName", "signingSecretConfigurationName", "resolved", "payloadMode", "enabled", "createdAt", "updatedAt" ], "type": "object", "properties": { "name": { "type": "string", "description": "Gets the trigger name." }, "targetKind": { "description": "Gets the kind of target the trigger starts.", "$ref": "#/components/schemas/InboundTriggerTargetKind" }, "targetName": { "type": "string", "description": "Gets the agent or workflow name the trigger starts." }, "signingSecretConfigurationName": { "type": "string", "description": "Gets the configuration key name the signing secret is read from." }, "resolved": { "type": "boolean", "description": "Gets whether `SigningSecretConfigurationName` currently resolves to a value." }, "payloadMode": { "description": "Gets how the request body becomes the run's message.", "$ref": "#/components/schemas/InboundTriggerPayloadMode" }, "payloadPath": { "type": [ "null", "string" ], "description": "Gets the dotted path used when InboundTriggerPayloadMode InboundTriggerResponse.PayloadMode is InboundTriggerPayloadMode.Path." }, "enabled": { "type": "boolean", "description": "Gets whether the trigger accepts requests." }, "createdAt": { "type": "string", "description": "Gets the creation time (UTC).", "format": "date-time" }, "updatedAt": { "type": "string", "description": "Gets the last-updated time (UTC).", "format": "date-time" } }, "description": "The response describing an inbound trigger definition." }, "InboundTriggerSaveRequest": { "type": "object", "properties": { "targetKind": { "description": "Gets the kind of target the trigger starts. Default InboundTriggerTargetKind.Agent.", "$ref": "#/components/schemas/InboundTriggerTargetKind" }, "targetName": { "type": [ "null", "string" ], "description": "Gets the agent or workflow name to run." }, "signingSecretConfigurationName": { "type": [ "null", "string" ], "description": "Gets the configuration key name the signing secret is read from. Never a value." }, "payloadMode": { "description": "Gets how the request body becomes the run's message. Default InboundTriggerPayloadMode.WholeBody.", "$ref": "#/components/schemas/InboundTriggerPayloadMode" }, "payloadPath": { "type": [ "null", "string" ], "description": "Gets the dotted path used when InboundTriggerPayloadMode InboundTriggerSaveRequest.PayloadMode is InboundTriggerPayloadMode.Path." }, "enabled": { "type": "boolean", "description": "Gets whether the trigger accepts requests. Default `true`." } }, "description": "The request body for creating or replacing an inbound trigger." }, "InboundTriggerTargetKind": { "enum": [ "Agent", "Workflow" ], "description": "What kind of target an inbound trigger fires." }, "ItemContent": { "required": [ "type", "text" ], "type": "object", "properties": { "type": { "type": "string" }, "text": { "type": "string" } } }, "ItemListResource": { "required": [ "object", "data", "first_id", "last_id", "has_more" ], "type": "object", "properties": { "object": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ItemResource" } }, "first_id": { "type": [ "null", "string" ] }, "last_id": { "type": [ "null", "string" ] }, "has_more": { "type": "boolean" } } }, "ItemResource": { "required": [ "id", "type", "status", "role", "content", "call_id", "name", "arguments", "output" ], "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "status": { "type": [ "null", "string" ] }, "role": { "type": [ "null", "string" ] }, "content": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/ItemContent" } }, "call_id": { "type": [ "null", "string" ] }, "name": { "type": [ "null", "string" ] }, "arguments": { "type": [ "null", "string" ] }, "output": { "type": [ "null", "string" ] } } }, "JobDetailResponse": { "required": [ "job", "items" ], "type": "object", "properties": { "job": { "description": "Job record.", "$ref": "#/components/schemas/JobRecord" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/JobItemRecord" }, "description": "The job's items, in sequence order." } }, "description": "Detailed view of a single job: record and items together." }, "JobItemRecord": { "required": [ "id", "jobId", "seq", "input", "status" ], "type": "object", "properties": { "id": { "type": "string", "description": "The item identifier.", "format": "uuid" }, "jobId": { "type": "string", "description": "The identifier of the job it belongs to.", "format": "uuid" }, "seq": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The sequence number within the job (starts at 0).", "format": "int32" }, "input": { "type": "string", "description": "This item's input text." }, "runId": { "type": [ "null", "string" ], "description": "The identifier of the run record created while processing this item.\n`null` if the item has not been processed yet.", "format": "uuid" }, "status": { "description": "The item's processing status.", "$ref": "#/components/schemas/JobItemStatus" }, "error": { "type": [ "null", "string" ], "description": "The failure message. Populated only for JobItemStatus.Failed." } }, "description": "A single input of a batch job and that input's processing result." }, "JobItemStatus": { "enum": [ "Pending", "Completed", "Failed" ], "description": "The status of a batch job item." }, "JobRecord": { "required": [ "id", "tenantId", "handlerKey", "targetName", "status", "scheduledFor", "createdAt" ], "type": "object", "properties": { "id": { "type": "string", "description": "The job identifier.", "format": "uuid" }, "tenantId": { "type": "string", "description": "The tenant the job belongs to." }, "scheduleId": { "type": [ "null", "string" ], "description": "The identifier of the schedule that produced this job.\n`null` for manually created (one-off) jobs.", "format": "uuid" }, "handlerKey": { "type": "string", "description": "The key of the IJobHandler that executes this job. See\nJobHandlerKeys." }, "lane": { "type": "string", "description": "The lane this job runs in. See JobLanes. A worker only\nleases jobs from the lanes it subscribes to\n(`TraconSchedulingOptions.Lanes`)." }, "targetName": { "type": "string", "description": "The agent or workflow name to run." }, "status": { "description": "The job's current status.", "$ref": "#/components/schemas/JobStatus" }, "payload": { "description": "The input set or parameters.", "$ref": "#/components/schemas/JsonElement" }, "totalItems": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The total number of items.", "format": "int32" }, "doneItems": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of items that completed successfully.", "format": "int32" }, "failedItems": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of items that failed.", "format": "int32" }, "attempt": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of lease attempts. Increments on every ValueTask<JobRecord?> IJobStore.LeaseAsync(string owner, TimeSpan leaseDuration, IReadOnlyList<string>? lanes, CancellationToken cancellationToken = default(CancellationToken)) call.", "format": "int32" }, "maxAttempts": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "The maximum number of attempts specific to this job. If\n`null`, `TraconSchedulingOptions.MaxAttempts` applies.", "format": "int32" }, "leaseOwner": { "type": [ "null", "string" ], "description": "The identifier of the worker currently leasing the job. `null` if not leased." }, "leaseUntil": { "type": [ "null", "string" ], "description": "The time the current lease expires (UTC). The job may be re-leased once it expires.", "format": "date-time" }, "scheduledFor": { "type": "string", "description": "The earliest time the job is eligible to run (UTC).", "format": "date-time" }, "startedAt": { "type": [ "null", "string" ], "description": "The time the first lease happened (UTC).", "format": "date-time" }, "completedAt": { "type": [ "null", "string" ], "description": "The completion time (UTC). `null` while the job is in progress.", "format": "date-time" }, "errorMessage": { "type": [ "null", "string" ], "description": "The failure message. Populated only for JobStatus.Failed." }, "createdAt": { "type": "string", "description": "The creation time (UTC).", "format": "date-time" } }, "description": "The summary of a queued job. The header of its items (JobItemRecord)." }, "JobSchedule": { "required": [ "tenantId", "name", "handlerKey", "targetName", "createdAt", "updatedAt" ], "type": "object", "properties": { "id": { "type": "string", "description": "The schedule identifier.", "format": "uuid" }, "tenantId": { "type": "string", "description": "The tenant the schedule belongs to." }, "name": { "type": "string", "description": "The schedule name, unique within the tenant." }, "handlerKey": { "type": "string", "description": "The key of the IJobHandler the jobs this schedule\nproduces are dispatched to. See JobHandlerKeys." }, "lane": { "type": "string", "description": "The lane the jobs this schedule produces run in. See\nJobLanes. Both a cron-dispatched run and a manual\n`POST .../trigger` inherit this value." }, "targetName": { "type": "string", "description": "The agent or workflow name to run." }, "cron": { "type": [ "null", "string" ], "description": "The five-field cron expression (`minute hour day-of-month month\nday-of-week`). If `null`, the schedule is triggered only manually." }, "timeZone": { "type": "string", "description": "The time zone the `Cron` expression is interpreted in." }, "payload": { "description": "The input set or parameters. Interpreted by the job's handler.", "$ref": "#/components/schemas/JsonElement" }, "enabled": { "type": "boolean", "description": "Whether the schedule is enabled. If disabled, it is not triggered automatically." }, "nextRunAt": { "type": [ "null", "string" ], "description": "The next automatic run time (UTC). `null` if there is no cron.", "format": "date-time" }, "lastRunAt": { "type": [ "null", "string" ], "description": "The last run time (UTC). `null` if it never ran.", "format": "date-time" }, "createdBy": { "type": [ "null", "string" ], "description": "The identifier of the user/service that created the schedule." }, "createdAt": { "type": "string", "description": "The creation time (UTC).", "format": "date-time" }, "updatedAt": { "type": "string", "description": "The last-updated time (UTC).", "format": "date-time" } }, "description": "The schedule record defining when and how a job runs." }, "JobScheduleSaveRequest": { "required": [ "handlerKey", "targetName" ], "type": "object", "properties": { "handlerKey": { "type": "string", "description": "Key of the handler the jobs this schedule produces run on. See\n`JobHandlerKeys`." }, "targetName": { "type": "string", "description": "Name of the agent or workflow to run." }, "cron": { "type": [ "null", "string" ], "description": "Five-field cron expression. If left empty, the schedule can only be\ntriggered manually (`POST .../trigger`)." }, "timeZone": { "type": "string", "description": "Time zone the `Cron` expression is interpreted in." }, "lane": { "type": [ "null", "string" ], "description": "The lane the jobs this schedule produces run in. See\n`JobLanes`. Left empty, the jobs run in `JobLanes.Default`\n(or whatever `TraconSchedulingOptions.LaneByHandlerKey` maps\nstring JobScheduleSaveRequest.HandlerKey to)." }, "payload": { "description": "Input set or parameters.", "$ref": "#/components/schemas/JsonElement" }, "enabled": { "type": "boolean", "description": "Whether the schedule is enabled." } }, "description": "Request to create/update a schedule." }, "JobStatus": { "enum": [ "Pending", "Leased", "Running", "Completed", "Failed", "Cancelled" ], "description": "The status of a queued job." }, "JobTriggerRequest": { "type": "object", "properties": { "payload": { "oneOf": [ { "type": "null" }, { "description": "Payload to use for this run. If left empty, the schedule's own payload\nis used.", "$ref": "#/components/schemas/JsonElement" } ] } }, "description": "Request to trigger a schedule immediately." }, "JsonElement": {}, "JudgeFailure": { "required": [ "judgeName", "errorType", "isRetryable" ], "type": "object", "properties": { "judgeName": { "type": "string", "description": "The judge that failed." }, "errorType": { "type": "string", "description": "The stable failure code." }, "isRetryable": { "type": "boolean", "description": "Whether retrying the job can help." } }, "description": "A normalized judge failure returned by manual scoring." }, "JudgeRunResponse": { "type": "object", "properties": { "scores": { "type": "array", "items": { "$ref": "#/components/schemas/RunScore" }, "description": "The score rows that were written." }, "failures": { "type": "array", "items": { "$ref": "#/components/schemas/JudgeFailure" }, "description": "The normalized failures reported by judges." } }, "description": "The result of manually scoring a run." }, "LiveVoiceSessionCreateRequest": { "required": [ "sessionId", "agent", "sdp" ], "type": "object", "properties": { "sessionId": { "type": "string", "description": "Gets the agent session the conversation runs in." }, "agent": { "type": "string", "description": "Gets the agent to talk to." }, "sdp": { "type": "string", "description": "Gets the media peer's SDP offer." }, "voice": { "type": [ "null", "string" ], "description": "Gets the requested output voice; `null` leaves the configured default." } }, "description": "The request that opens a provider-hosted live voice session." }, "LiveVoiceSessionCreateResponse": { "required": [ "voiceSessionId", "sdp", "persistTranscript" ], "type": "object", "properties": { "voiceSessionId": { "type": "string", "description": "Gets Tracon's identifier for the session.", "format": "uuid" }, "sdp": { "type": "string", "description": "Gets the SDP answer to hand to the media peer." }, "model": { "type": [ "null", "string" ], "description": "Gets the model the session is bound to." }, "persistTranscript": { "type": "boolean", "description": "Gets whether the conversation's transcript will be written to the session's\ndurable history." } }, "description": "The answer that opens a provider-hosted live voice session." }, "LiveVoiceSessionStatusResponse": { "required": [ "voiceSessionId", "state", "startedAt", "turns" ], "type": "object", "properties": { "voiceSessionId": { "type": "string", "description": "Gets Tracon's identifier for the session.", "format": "uuid" }, "state": { "type": "string", "description": "Gets the lifecycle state: `pending`, `active` or `ended`." }, "model": { "type": [ "null", "string" ], "description": "Gets the model the session is bound to." }, "startedAt": { "type": "string", "description": "Gets when the session was created.", "format": "date-time" }, "liveSeconds": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "description": "Gets the billable duration the provider has reported so far.", "format": "double" }, "turns": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Gets how many delegations have become runs.", "format": "int32" } }, "description": "The status of a provider-hosted live voice session." }, "LoopCriterion": { "required": [ "kind" ], "type": "object", "properties": { "kind": { "type": "string", "description": "Gets the criterion kind: `completionMarker`, `todoCompletion`,\n`aiJudge`, `backgroundTaskCompletion`, or a kind registered in\ncode with `AddLoopEvaluator`." }, "marker": { "type": [ "null", "string" ], "description": "Gets the completion marker text. Read by `completionMarker` only,\nwhere it is required." }, "judgeCriteria": { "type": "array", "items": { "type": "string" }, "description": "Gets the criteria the judge model scores the answer against. Read by\n`aiJudge` only, where at least one entry is required." }, "judgeInstructions": { "type": [ "null", "string" ], "description": "Gets the extra instructions handed to the judge model. Read by\n`aiJudge` only." }, "modes": { "type": "array", "items": { "type": "string" }, "description": "Gets the agent modes the criterion applies to. Read by\n`todoCompletion` only." } }, "description": "One declarative stop criterion of the harness loop (see `LoopSettings`)." }, "LoopSettings": { "required": [ "criteria" ], "type": "object", "properties": { "criteria": { "type": "array", "items": { "$ref": "#/components/schemas/LoopCriterion" }, "description": "Gets the stop criteria, evaluated in order. At least one is required." }, "maxIterations": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Gets the upper number of loop iterations. `null` takes\n`DefaultMaxIterations`. Must be greater than zero.", "format": "int32" }, "freshContextPerIteration": { "type": "boolean", "description": "Gets a value that starts every iteration from a fresh context instead of\ncarrying the previous iterations' messages forward." } }, "description": "Turns the harness loop on: the agent is re-invoked until a stop criterion\nsays the work is finished." }, "McpOAuthAuthorizationMode": { "enum": [ "AuthorizationCode" ], "description": "The MCP OAuth authorization flow." }, "McpOAuthStartResponse": { "required": [ "authorizationUri", "state" ], "type": "object", "properties": { "authorizationUri": { "type": "string", "description": "Authorization address the admin is redirected to." }, "state": { "type": "string", "description": "Single-use state value generated for CSRF protection." } }, "description": "Response for starting OAuth Mode 1." }, "McpPromptArgumentsRequest": { "type": "object", "properties": { "arguments": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "Prompt arguments." } }, "description": "Request to resolve an MCP prompt with arguments." }, "McpPromptArgumentSummary": { "required": [ "name" ], "type": "object", "properties": { "name": { "type": "string", "description": "The argument name." }, "description": { "type": [ "null", "string" ], "description": "The description." }, "required": { "type": "boolean", "description": "Whether the argument is required." } }, "description": "The summary of an MCP prompt argument." }, "McpPromptContent": { "required": [ "text", "hash" ], "type": "object", "properties": { "text": { "type": "string", "description": "The text concatenated from the prompt's messages." }, "hash": { "type": "string", "description": "The content's SHA-256 digest (hex). The snapshot is stored in\n`AgentDefinition.Metadata` under the `mcp.prompt.hash` key;\nwhen the server's content changes, the UI compares this digest and\nshows a badge." } }, "description": "The resolved content of a prompt." }, "McpPromptSummary": { "required": [ "name" ], "type": "object", "properties": { "name": { "type": "string", "description": "The prompt name." }, "title": { "type": [ "null", "string" ], "description": "The title shown in the UI." }, "description": { "type": [ "null", "string" ], "description": "The description." }, "arguments": { "type": "array", "items": { "$ref": "#/components/schemas/McpPromptArgumentSummary" }, "description": "The arguments the prompt accepts." } }, "description": "The summary of an MCP prompt." }, "McpRefreshResponse": { "required": [ "toolCount" ], "type": "object", "properties": { "toolCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Total number of tools available after the refresh.", "format": "int32" } }, "description": "Result of an MCP tool refresh." }, "McpResourceContent": { "required": [ "uri" ], "type": "object", "properties": { "uri": { "type": "string", "description": "The resource URI." }, "mimeType": { "type": [ "null", "string" ], "description": "The MIME type." }, "text": { "type": [ "null", "string" ], "description": "The text content. `null` for binary resources." }, "isBinary": { "type": "boolean", "description": "Whether the resource is binary (a blob)." }, "byteSize": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The byte size of the raw content (before truncation).", "format": "int32" }, "truncated": { "type": "boolean", "description": "Whether the content was truncated because it exceeded the size limit." } }, "description": "The content of a resource that was read." }, "McpResourceSummary": { "required": [ "uri", "name" ], "type": "object", "properties": { "uri": { "type": "string", "description": "The resource URI." }, "name": { "type": "string", "description": "The resource name." }, "mimeType": { "type": [ "null", "string" ], "description": "The MIME type." }, "description": { "type": [ "null", "string" ], "description": "The description." } }, "description": "The summary of an MCP resource." }, "McpServerDefinition": { "required": [ "id", "tenantId", "name", "endpoint" ], "type": "object", "properties": { "id": { "type": "string", "description": "The server identifier. A time-ordered UUID (v7).", "format": "uuid" }, "tenantId": { "type": "string", "description": "The tenant the server belongs to." }, "name": { "type": "string", "description": "The server name. Discovered tools are named as `{name}.{tool}`, so\ntools with the same name on two servers never collide." }, "description": { "type": [ "null", "string" ], "description": "The description." }, "endpoint": { "type": "string", "description": "The server address. Only `http` and `https` are accepted.", "format": "uri" }, "transport": { "description": "The transport format.", "$ref": "#/components/schemas/McpTransportMode" }, "authorizationConfigurationKey": { "type": [ "null", "string" ], "description": "The configuration key the `Authorization` header's value is read\nfrom. Example: `Tracon:McpSecrets:GithubToken`. If left empty, the\nheader is not sent." }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Extra request headers. Must not carry a secret — these\nvalues are stored as-is and shown in the UI." }, "enabled": { "type": "boolean", "description": "Whether the server is enabled. Its tools are not discovered while disabled." }, "oauthEnabled": { "type": "boolean", "description": "Whether OAuth authentication is on. When on, it cannot be used at the\nsame time as `AuthorizationConfigurationKey` — both would\ntry to manage the `Authorization` header." }, "oauthClientId": { "type": [ "null", "string" ], "description": "The OAuth client identifier. Not a secret, stored as-is." }, "oauthClientSecretConfigurationKey": { "type": [ "null", "string" ], "description": "The configuration key the OAuth client secret's value is read from.\nThe value is never written to the database, under the same rule\n as `AuthorizationConfigurationKey`." }, "oauthScopes": { "type": [ "null", "string" ], "description": "The space-separated OAuth scope list. Example: `\"repo read:user\"`." }, "oauthAuthorizationMode": { "description": "The OAuth authorization flow.", "$ref": "#/components/schemas/McpOAuthAuthorizationMode" }, "requiresApproval": { "type": "boolean", "description": "Whether this server's tools require explicit approval before each call.\nDefaults to `true`: the tool definition\ncomes from outside and is treated as untrusted." }, "createdAt": { "type": "string", "description": "The creation time (UTC).", "format": "date-time" }, "updatedAt": { "type": "string", "description": "The last-updated time (UTC).", "format": "date-time" } }, "description": "A registered remote MCP server. Its tools are discovered at connection time and\nlisted alongside the tools registered in code." }, "McpServerRequest": { "required": [ "endpoint" ], "type": "object", "properties": { "description": { "type": [ "null", "string" ], "description": "Description." }, "endpoint": { "type": "string", "description": "Server address. Only `http` and `https` are accepted." }, "transport": { "description": "Transport mode.", "$ref": "#/components/schemas/McpTransportMode" }, "authorizationConfigurationKey": { "type": [ "null", "string" ], "description": "Configuration key the `Authorization` header's value is read from.\nExample: `Tracon:McpSecrets:GithubToken`." }, "headers": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "Extra request headers. Must not carry secrets — these\nvalues are stored as-is and appear in the listing endpoint." }, "enabled": { "type": "boolean", "description": "Whether the server is enabled." }, "requiresApproval": { "type": "boolean", "description": "Whether this server's tools require approval. Default `true`." }, "oauthEnabled": { "type": "boolean", "description": "Whether OAuth authentication is enabled. While on,\n`AuthorizationConfigurationKey` must be empty." }, "oauthClientId": { "type": [ "null", "string" ], "description": "OAuth client identifier." }, "oauthClientSecretConfigurationKey": { "type": [ "null", "string" ], "description": "Configuration key the OAuth client secret's value is read from. The\nvalue itself is not sent; only the key's name is." }, "oauthScopes": { "type": [ "null", "string" ], "description": "Space-separated list of OAuth scopes." }, "oauthAuthorizationMode": { "description": "OAuth authorization flow.", "$ref": "#/components/schemas/McpOAuthAuthorizationMode" } }, "description": "Request to create/update an MCP server." }, "McpTransportMode": { "enum": [ "StreamableHttp", "Sse" ], "description": "The way a connection to an MCP server is made." }, "MemorySettings": { "type": "object", "properties": { "enableFileMemory": { "type": "boolean", "description": "Gets a value that turns on file-based memory. It reads whichever\n`AgentFileStore` is registered; the built-in store keeps files in\nmemory, so they do not survive a restart unless you register your own." }, "enableTodo": { "type": "boolean", "description": "Gets a value that turns on todo tracking." }, "enableTextSearch": { "type": "boolean", "description": "Gets a value that turns on text search over the file store. The search runs over\nthe registered `AgentFileStore`, which is the in-memory store unless you\nregister another one." }, "enableVectorSearch": { "type": "boolean", "description": "Gets a value that turns on the `search_knowledge` tool.\nPostgreSQL only: the single concrete implementation of\nIVectorSearchStore lives in `Tracon.PostgreSql`. When this\nflag is turned on while another provider is registered, the build stops with\nTraconCompilationException; it does not silently return an\nempty result." }, "vectorCollection": { "type": [ "null", "string" ], "description": "Gets the name of the collection to search. The agent name is used when it is empty." } }, "description": "Determines the memory providers bound to an agent." }, "ModelBinding": { "required": [ "provider", "model" ], "type": "object", "properties": { "provider": { "type": "string", "description": "Gets the provider name, for example `openai`." }, "model": { "type": "string", "description": "Gets the model name, for example `gpt-5.4-mini`." }, "temperature": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "description": "Gets the sampling temperature. The provider default is used when it is `null`.", "format": "float" }, "maxOutputTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Gets the upper output token limit. The provider default is used when it is `null`.", "format": "int32" }, "topP": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "description": "Gets the nucleus sampling threshold. The provider default is used when it is `null`.", "format": "float" }, "reasoningEffort": { "type": [ "null", "string" ], "description": "Gets the reasoning effort level. Models that support it use the value; the other\nproviders ignore it." }, "providerSettings": { "type": "object", "description": "Gets the provider-specific extra settings. A key has the form `{provider}.{setting}`." }, "responseFormat": { "oneOf": [ { "type": "null" }, { "description": "Gets the requested output format. When it is `null` today's\nbehaviour does not change: no format constraint is sent to the provider.", "$ref": "#/components/schemas/AgentResponseFormat" } ] }, "fallbacks": { "type": "array", "items": { "$ref": "#/components/schemas/ModelFallback" }, "description": "Gets the ordered fallback chain tried when the primary provider is\nunavailable. Empty by default." }, "responseCache": { "oneOf": [ { "type": "null" }, { "description": "Gets the response caching settings. Disabled when `null`.", "$ref": "#/components/schemas/ResponseCacheSettings" } ] }, "allowConcurrentToolCalls": { "type": "boolean", "description": "Gets whether independent tool calls within one turn may run at the\nsame time." } }, "description": "Determines the provider and the model an agent runs with. It carries\nno credentials; the API key is resolved from configuration." }, "ModelDescriptor": { "required": [ "name" ], "type": "object", "properties": { "name": { "type": "string", "description": "The model name. `ModelBinding.Model` matches this value." }, "displayName": { "type": [ "null", "string" ], "description": "The name shown in the UI." }, "contextWindowTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "The context window's token capacity.", "format": "int32" }, "maxOutputTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "The maximum number of tokens producible in a single response.", "format": "int32" }, "supportsStreaming": { "type": "boolean", "description": "Whether streaming responses are supported." }, "supportsTools": { "type": "boolean", "description": "Whether tool calling is supported." }, "supportsReasoning": { "type": "boolean", "description": "Whether the reasoning-effort setting is supported." }, "supportsStructuredOutput": { "type": "boolean", "description": "Whether output conforming to a JSON schema can be produced." }, "inputCostPerMillionTokens": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "description": "The cost per million input tokens. For reporting only.", "format": "double" }, "outputCostPerMillionTokens": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "description": "The cost per million output tokens. For reporting only.", "format": "double" }, "cachedInputCostPerMillionTokens": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "description": "The cost per million input tokens that were served from the provider's\nprompt cache. For reporting only.", "format": "double" } }, "description": "A model's capabilities and limits." }, "ModelFallback": { "required": [ "provider", "model" ], "type": "object", "properties": { "provider": { "type": "string", "description": "Gets the provider name, for example `anthropic`." }, "model": { "type": "string", "description": "Gets the model name, for example `claude-opus-5`." } }, "description": "One link of a IReadOnlyList<ModelFallback> ModelBinding.Fallbacks chain." }, "ModelProviderDescriptor": { "required": [ "name" ], "type": "object", "properties": { "name": { "type": "string", "description": "The provider name." }, "displayName": { "type": [ "null", "string" ], "description": "The name shown in the UI." }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/ModelDescriptor" }, "description": "The models this provider offers." }, "status": { "description": "The provider's last known health status.", "$ref": "#/components/schemas/ModelProviderHealthStatus" } }, "description": "A provider's definition as shown in the UI." }, "ModelProviderHealth": { "required": [ "providerName", "status" ], "type": "object", "properties": { "providerName": { "type": "string", "description": "The provider name." }, "status": { "description": "The check result.", "$ref": "#/components/schemas/ModelProviderHealthStatus" }, "detail": { "type": [ "null", "string" ], "description": "A short failure reason. Carries no secret: the\nresponse body, headers, or API key are never written here under any\ncondition — only the HTTP status code and a short description." }, "latency": { "pattern": "^-?(\\d+\\.)?\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,7})?$", "type": [ "null", "string" ], "description": "How long the check request took." }, "checkedAt": { "type": "string", "description": "The time the check was performed.", "format": "date-time" }, "models": { "type": "array", "items": { "type": "string" }, "description": "The model names the server reported. Empty if the check failed." } }, "description": "A model provider's status at the last check." }, "ModelProviderHealthStatus": { "enum": [ "Unknown", "Healthy", "Degraded", "Unhealthy" ], "description": "A provider's checked reachability status." }, "OnlineEvaluationSummary": { "required": [ "windowStart", "windowEnd", "sampleCount", "lowScoreThreshold", "minSampleSize", "belowThreshold" ], "type": "object", "properties": { "windowStart": { "type": "string", "description": "Gets the window start in UTC.", "format": "date-time" }, "windowEnd": { "type": "string", "description": "Gets the window end in UTC.", "format": "date-time" }, "sampleCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Gets the sample count, which is the number of scored runs in the window.", "format": "int64" }, "averageScore": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "description": "Gets the average score in the window, from 0 to 100, or `null` with no samples.", "format": "double" }, "lowScoreThreshold": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Gets the configured low-score threshold.", "format": "int32" }, "minSampleSize": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Gets the minimum sample count required for an alarm.", "format": "int32" }, "belowThreshold": { "type": "boolean", "description": "Gets `true` when the average is below the threshold and\nthe sample count meets the minimum." }, "judgeCost": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "description": "Gets the total judge cost in the window, or `null` when unknown.", "format": "double" }, "judgeCostCurrency": { "type": [ "null", "string" ], "description": "Gets the judge-cost currency." } }, "description": "Summarizes the online evaluation window (`GET /api/evaluation/online`)." }, "OpenAIErrorBody": { "required": [ "message", "type" ], "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string" } } }, "OpenAIErrorEnvelope": { "required": [ "error" ], "type": "object", "properties": { "error": { "$ref": "#/components/schemas/OpenAIErrorBody" } } }, "PendingApproval": { "required": [ "id", "tenantId", "runId", "sessionId", "requestId", "toolName", "status", "expiresAt", "createdAt" ], "type": "object", "properties": { "id": { "type": "string", "description": "Gets the record id.", "format": "uuid" }, "tenantId": { "type": "string", "description": "Gets the tenant id." }, "runId": { "type": "string", "description": "Gets the run that produced this request and closed with RunStatus.AwaitingApproval.", "format": "uuid" }, "sessionId": { "type": "string", "description": "Gets the session of the run. While the decision is applied, the continuing run is\nput on the queue with this session." }, "requestId": { "type": "string", "description": "Gets the `ToolApprovalRequestContent.RequestId` value produced by MAF." }, "toolName": { "type": "string", "description": "Gets the name of the tool that asks for approval." }, "arguments": { "type": [ "null", "string" ], "description": "Gets the arguments of the tool call as `key=value` pairs (reflection-based\nJSON serialization is NOT USED, to stay AOT compatible). It stays\n`null` when `RecordToolPayloads` is turned off in the\nrecording settings." }, "presentation": { "oneOf": [ { "type": "null" }, { "description": "Gets the human-readable presentation an IToolApprovalPresenter\nresolved for this request, or `null` when no presenter is\nregistered, none resolved anything, or the resolution failed or timed out.", "$ref": "#/components/schemas/ToolApprovalPresentation" } ] }, "status": { "description": "Gets the status of the request.", "$ref": "#/components/schemas/ApprovalStatus" }, "decidedBy": { "type": [ "null", "string" ], "description": "Gets the actor that made the decision, or `null` when no decision was made." }, "decidedAt": { "type": [ "null", "string" ], "description": "Gets the time of the decision, or `null` when no decision was made.", "format": "date-time" }, "expiresAt": { "type": "string", "description": "Gets the time after which the request counts as ApprovalStatus.Expired.", "format": "date-time" }, "createdAt": { "type": "string", "description": "Gets the creation time.", "format": "date-time" } }, "description": "The pending tool approval request of a run that executes from the queue." }, "PricingSource": { "enum": [ "Catalog", "Configuration", "Unknown" ], "description": "Reports where a run's cost pricing came from." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": [ "null", "string" ] }, "title": { "type": [ "null", "string" ] }, "status": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "detail": { "type": [ "null", "string" ] }, "instance": { "type": [ "null", "string" ] } } }, "ProviderDiagnostic": { "required": [ "name", "status", "circuitOpen" ], "type": "object", "properties": { "name": { "type": "string", "description": "Gets the provider name." }, "status": { "type": "string", "description": "Gets the last known model provider health cache status as a\nModelProviderHealthStatus value in text form. Returns\n`\"Unknown\"` when the cache is empty." }, "circuitOpen": { "type": "boolean", "description": "Gets whether the circuit breaker is open for this provider." } }, "description": "Summarizes diagnostics for a model provider." }, "QuotaDefinition": { "required": [ "id", "tenantId", "period", "createdAt", "updatedAt" ], "type": "object", "properties": { "id": { "type": "string", "description": "The rule identifier.", "format": "uuid" }, "tenantId": { "type": "string", "description": "The tenant the rule belongs to." }, "agentName": { "type": [ "null", "string" ], "description": "The agent the rule is bound to. If `null`, the rule\napplies to all of the tenant's runs." }, "period": { "description": "The counter's reset interval.", "$ref": "#/components/schemas/QuotaPeriod" }, "maxRuns": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "The maximum number of runs per period. Unlimited if `null`.", "format": "int64" }, "maxTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "The maximum tokens per period. Unlimited if `null`.", "format": "int64" }, "maxCost": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "description": "The maximum monetary amount per period. Unlimited if `null`.", "format": "double" }, "enabled": { "type": "boolean", "description": "Whether the rule is enabled." }, "createdAt": { "type": "string", "description": "The creation time (UTC).", "format": "date-time" }, "updatedAt": { "type": "string", "description": "The last-updated time (UTC).", "format": "date-time" } }, "description": "A quota rule defined for a tenant or an agent." }, "QuotaPeriod": { "enum": [ "Daily", "Monthly" ], "description": "The interval at which a quota's counter resets." }, "QuotaSaveRequest": { "type": "object", "properties": { "agentName": { "type": [ "null", "string" ], "description": "Gets the agent the rule is bound to. If left empty, the rule applies to all\nof the tenant's runs." }, "period": { "description": "Gets the counter's reset interval.", "$ref": "#/components/schemas/QuotaPeriod" }, "maxRuns": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Gets the maximum number of runs per period.", "format": "int64" }, "maxTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Gets the maximum number of tokens per period.", "format": "int64" }, "maxCost": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "description": "Gets the maximum monetary amount per period.", "format": "double" }, "enabled": { "type": "boolean", "description": "Gets whether the rule is enabled." } }, "description": "Request body for saving a quota rule." }, "QuotaUsageRecord": { "required": [ "tenantId", "agentName", "period", "periodStart", "updatedAt" ], "type": "object", "properties": { "tenantId": { "type": "string", "description": "The tenant identifier." }, "agentName": { "type": "string", "description": "The agent name. An empty string (`\"\"`) means the tenant-wide counter." }, "period": { "description": "The counter's interval.", "$ref": "#/components/schemas/QuotaPeriod" }, "periodStart": { "type": "string", "description": "The first day of the period (in local time).", "format": "date" }, "runs": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of runs completed in the period.", "format": "int64" }, "tokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The total tokens spent in the period.", "format": "int64" }, "cost": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "description": "The total amount spent in the period. Runs with undefined pricing are\nnot included in this total (not even added as zero).", "format": "double" }, "updatedAt": { "type": "string", "description": "The last-updated time (UTC).", "format": "date-time" } }, "description": "A scope's consumption in the current period." }, "QuotaUsageResponse": { "required": [ "tenantId", "timeZone", "usage", "definitions", "dailyResetsAt", "monthlyResetsAt" ], "type": "object", "properties": { "tenantId": { "type": "string", "description": "Gets the tenant identifier." }, "timeZone": { "type": "string", "description": "Gets the time zone the period boundaries are computed in." }, "usage": { "type": "array", "items": { "$ref": "#/components/schemas/QuotaUsageRecord" }, "description": "Gets the current period's counters." }, "definitions": { "type": "array", "items": { "$ref": "#/components/schemas/QuotaDefinition" }, "description": "Gets the defined quota rules. The UI computes the percentage from these." }, "dailyResetsAt": { "type": "string", "description": "Gets the moment (UTC) the daily counters reset.", "format": "date-time" }, "monthlyResetsAt": { "type": "string", "description": "Gets the moment (UTC) the monthly counters reset.", "format": "date-time" } }, "description": "Response for the quota usage endpoint." }, "ReplayToolMode": { "enum": [ "NoTools", "ReplayTools", "LiveTools" ], "description": "How tools are handled during replay." }, "ResponseCacheSettings": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Gets whether the cache ring is added to the pipeline." }, "lifetime": { "pattern": "^-?(\\d+\\.)?\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,7})?$", "type": "string", "description": "Gets how long a cached response stays valid." } }, "description": "Response caching settings for a ModelBinding." }, "RetentionPolicy": { "required": [ "id", "tenantId", "target", "createdAt", "updatedAt" ], "type": "object", "properties": { "id": { "type": "string", "description": "The policy identifier.", "format": "uuid" }, "tenantId": { "type": "string", "description": "The tenant identifier. `\"*\"` means the default for all tenants." }, "target": { "type": "string", "description": "The target table name. See RetentionTargets." }, "maxAgeDays": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Rows older than this age are candidates for deletion. If\n`null`, age-based deletion does not apply (only\n`MaxRows`, if set, applies).", "format": "int32" }, "maxRows": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "The maximum number of rows to keep in the target table. The oldest\nrows over the limit are deleted. If `null`,\nvolume-based deletion does not apply (only `MaxAgeDays`,\nif set, applies).", "format": "int64" }, "archive": { "type": "boolean", "description": "Whether to archive with `IArchiveSink` before deleting. If no\nsink is registered, no row is deleted even if this field is\n`true`." }, "enabled": { "type": "boolean", "description": "Whether the policy is enabled." }, "createdAt": { "type": "string", "description": "The creation time (UTC).", "format": "date-time" }, "updatedAt": { "type": "string", "description": "The last-updated time (UTC).", "format": "date-time" } }, "description": "An age- and volume-based retention rule for a target." }, "RetentionPolicySaveRequest": { "type": "object", "properties": { "maxAgeDays": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Rows older than this age are candidates for deletion.", "format": "int32" }, "maxRows": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "The maximum number of rows to keep for the target. The oldest rows are deleted.", "format": "int64" }, "archive": { "type": "boolean", "description": "Whether to archive rows before deleting them." }, "enabled": { "type": "boolean", "description": "Whether the policy is enabled." } }, "description": "Request body for saving a retention policy." }, "RetentionPreview": { "required": [ "target" ], "type": "object", "properties": { "target": { "type": "string", "description": "The previewed target." }, "maxAgeDays": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "`null` if no policy was found (nothing would be deleted).", "format": "int32" }, "enabled": { "type": "boolean", "description": "Whether the policy is enabled." }, "cutoff": { "type": [ "null", "string" ], "description": "The computed cutoff date (UTC). `null` if there is no policy.", "format": "date-time" }, "matchingRows": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of rows currently older than the cutoff date.", "format": "int64" } }, "description": "A preview of \"how many rows would be deleted if run now\" for a target." }, "RetentionRun": { "required": [ "id", "tenantId", "target", "startedAt" ], "type": "object", "properties": { "id": { "type": "string", "description": "The run identifier.", "format": "uuid" }, "tenantId": { "type": "string", "description": "The tenant identifier." }, "target": { "type": "string", "description": "The target processed." }, "deletedRows": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of rows deleted so far.", "format": "int64" }, "archivedRows": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of rows archived so far.", "format": "int64" }, "startedAt": { "type": "string", "description": "The start time (UTC).", "format": "date-time" }, "completedAt": { "type": [ "null", "string" ], "description": "The completion time (UTC). `null` while the run is in progress.", "format": "date-time" }, "error": { "type": [ "null", "string" ], "description": "The error message. Populated only for failed runs." } }, "description": "The history record of a cleanup run." }, "RetentionRunTriggerResponse": { "required": [ "jobId", "target" ], "type": "object", "properties": { "jobId": { "type": "string", "description": "The id of the enqueued job.", "format": "uuid" }, "target": { "type": "string", "description": "The target to process; `\"*\"` for all targets." } }, "description": "Response to a \"run now\" request." }, "RunAgentStatistics": { "required": [ "agentName", "totalRuns", "failedRuns" ], "type": "object", "properties": { "agentName": { "type": "string", "description": "The agent name." }, "totalRuns": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "This agent's total number of runs.", "format": "int64" }, "failedRuns": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "This agent's number of runs that ended in an error.", "format": "int64" }, "totalTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "This agent's total token usage.", "format": "int64" } }, "description": "An agent's run summary." }, "RunComparisonResponse": { "required": [ "left", "right" ], "type": "object", "properties": { "left": { "description": "The left-hand run.", "$ref": "#/components/schemas/RunComparisonSide" }, "right": { "description": "The right-hand run.", "$ref": "#/components/schemas/RunComparisonSide" } }, "description": "Side-by-side summary of two runs." }, "RunComparisonSide": { "required": [ "runId", "agentName", "status", "toolCallCount" ], "type": "object", "properties": { "runId": { "type": "string", "description": "Run identifier.", "format": "uuid" }, "agentName": { "type": "string", "description": "Agent name." }, "agentVersion": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Definition version. `null` if unknown.", "format": "int32" }, "modelId": { "type": [ "null", "string" ], "description": "Model used." }, "status": { "description": "Final status.", "$ref": "#/components/schemas/RunStatus" }, "durationMs": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Duration (milliseconds). `null` if the run has not finished.", "format": "int64" }, "usage": { "oneOf": [ { "type": "null" }, { "description": "Token usage.", "$ref": "#/components/schemas/RunUsage" } ] }, "cost": { "oneOf": [ { "type": "null" }, { "description": "Cost.", "$ref": "#/components/schemas/RunCost" } ] }, "toolCallCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Number of tool calls.", "format": "int32" }, "errorClass": { "oneOf": [ { "type": "null" }, { "description": "Error class. `null` for a successful run.", "$ref": "#/components/schemas/RunErrorClass" } ] }, "errorMessage": { "type": [ "null", "string" ], "description": "Error message. `null` for a successful run." }, "replayOfRunId": { "type": [ "null", "string" ], "description": "Source of this run, if it is a replay.", "format": "uuid" }, "output": { "type": [ "null", "string" ], "description": "Text produced by the model." }, "scores": { "type": "array", "items": { "$ref": "#/components/schemas/RunScore" }, "description": "Scores written against this run." } }, "description": "One side of the comparison." }, "RunCost": { "required": [ "source" ], "type": "object", "properties": { "inputCost": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "description": "Gets the input token cost, or `null` when the price is unknown.", "format": "double" }, "inputPricePerMillionTokens": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "description": "Gets the input price, per million tokens, that produced\n`InputCost`. `null` when the price is unknown.", "format": "double" }, "outputCost": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "description": "Gets the output token cost, or `null` when the price is unknown.", "format": "double" }, "outputPricePerMillionTokens": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "description": "Gets the output price, per million tokens, that produced\n`OutputCost`. `null` when the price is unknown.", "format": "double" }, "cachedInputCost": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "description": "Gets the cost of the input tokens that were served from the prompt\ncache, or `null` when no cache read was priced.", "format": "double" }, "cachedInputPricePerMillionTokens": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "description": "Gets the cache-read price, per million tokens, that produced\n`CachedInputCost`. `null` when no cache rate\nwas applied — either the cache rate is undefined, or the provider\nreported no cache read at all.", "format": "double" }, "currency": { "type": [ "null", "string" ], "description": "Gets the currency, taken from `Tracon:Pricing:Currency`." }, "source": { "description": "Gets where the price came from.", "$ref": "#/components/schemas/PricingSource" } }, "description": "Cost of a run. It is computed and written once when the run ends (a price\nsnapshot) — a later change to the price list does not change past values." }, "RunCostRecalculationResult": { "required": [ "runsConsidered", "runsUpdated", "runsStillUnknown", "runsSkipped" ], "type": "object", "properties": { "runsConsidered": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Gets the number of runs considered, that is those with a model and usage\nAND an unpriced (`PricingSource.Unknown` or absent) cost.", "format": "int64" }, "runsUpdated": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Gets the number of runs whose price resolved and was updated.", "format": "int64" }, "runsStillUnknown": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Gets the number of runs whose price is still unknown afterwards.", "format": "int64" }, "runsSkipped": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Gets the number of runs skipped because they already carried a known\nprice. A priced run's cost is a snapshot and is never rewritten.", "format": "int64" } }, "description": "Result of a cost recalculation." }, "RunError": { "required": [ "type", "message" ], "type": "object", "properties": { "type": { "type": "string", "description": "Gets the name of the exception type." }, "message": { "type": "string", "description": "Gets the error message." }, "class": { "oneOf": [ { "type": "null" }, { "description": "Gets the class chosen by IRunErrorClassifier. Rows written\nBEFORE the error class was introduced hold `null`, which\nthe user interface shows in the `Unknown` bucket.", "$ref": "#/components/schemas/RunErrorClass" } ] }, "fingerprint": { "type": [ "null", "string" ], "description": "Gets the digest of the normalized message, used to cluster repetitions of\nthe same fault. `null` when no classifier ran, as for\n`Class`." } }, "description": "Error information for a failed run." }, "RunErrorClass": { "enum": [ "Unknown", "ProviderError", "ProviderUnavailable", "RateLimited", "QuotaExceeded", "ContentFiltered", "ToolError", "Timeout", "CompilationFailed", "Canceled", "ContentBlocked", "Infrastructure", "ToolTimeout", "StructuredResponseInvalid", null ] }, "RunErrorCluster": { "required": [ "fingerprint", "count", "sampleMessage", "sampleRunId", "lastSeenAt" ], "type": "object", "properties": { "fingerprint": { "type": "string", "description": "The digest of the normalized message." }, "count": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of runs in this cluster.", "format": "int64" }, "sampleMessage": { "type": "string", "description": "The raw error message of the most recent occurrence in the cluster." }, "sampleRunId": { "type": "string", "description": "The run identifier of the most recent occurrence in the cluster.", "format": "uuid" }, "lastSeenAt": { "type": "string", "description": "The moment this cluster was last seen (UTC).", "format": "date-time" } }, "description": "The summary of runs sharing the same fingerprint." }, "RunErrorStatistics": { "required": [ "class", "totalRuns" ], "type": "object", "properties": { "class": { "description": "The error class.", "$ref": "#/components/schemas/RunErrorClass" }, "totalRuns": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The total number of runs falling into this class.", "format": "int64" }, "topClusters": { "type": "array", "items": { "$ref": "#/components/schemas/RunErrorCluster" }, "description": "This class's most frequent clusters, in descending order of count." } }, "description": "An error class's summary." }, "RunFeedbackRequest": { "required": [ "kind" ], "type": "object", "properties": { "name": { "type": [ "null", "string" ], "description": "The score's stable, low-cardinality name. Left blank it becomes\n`overall`." }, "kind": { "description": "The format of the score.", "$ref": "#/components/schemas/RunScoreKind" }, "value": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "description": "0/1 for RunScoreKind.Binary, 1 to 5 for\nRunScoreKind.Stars, 0 to 100 for\nRunScoreKind.Numeric. Left out for\nRunScoreKind.Categorical, required otherwise.", "format": "double" }, "textValue": { "type": [ "null", "string" ], "description": "The categorical label. Required for RunScoreKind.Categorical\nand rejected for every other kind." }, "messageId": { "type": [ "null", "string" ], "description": "The id of the scored message. If left blank, the score applies to the whole run." }, "comment": { "type": [ "null", "string" ], "description": "Free-text comment." } }, "description": "Request body for writing a run/message score." }, "RunInputResponse": { "required": [ "runId", "createdAt", "messages" ], "type": "object", "properties": { "runId": { "type": "string", "description": "Run identifier.", "format": "uuid" }, "createdAt": { "type": "string", "description": "Creation time of the record (UTC).", "format": "date-time" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessage" }, "description": "Input messages, with their polymorphic content, exactly as recorded." } }, "description": "HTTP response for a run's recorded input." }, "RunKind": { "enum": [ "Agent", "Workflow", "Eval" ], "description": "Reports what a `runs` row records." }, "RunLabelStatistics": { "required": [ "key", "value", "totalRuns", "failedRuns" ], "type": "object", "properties": { "key": { "type": "string", "description": "The label key." }, "value": { "type": "string", "description": "The label value." }, "totalRuns": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of runs carrying this exact key/value pair.", "format": "int64" }, "failedRuns": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "This label's number of runs that ended in an error.", "format": "int64" }, "totalTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "This label's total token usage.", "format": "int64" }, "totalCost": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "description": "This label's total cost. `null` if no run carrying it was ever priced.", "format": "double" } }, "description": "A label's run summary; one entry per distinct key/value pair." }, "RunModelStatistics": { "required": [ "modelId", "totalRuns" ], "type": "object", "properties": { "modelId": { "type": "string", "description": "The model name." }, "totalRuns": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The total number of runs made with this model.", "format": "int64" }, "inputTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The total input tokens.", "format": "int64" }, "outputTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The total output tokens.", "format": "int64" }, "totalTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The total tokens.", "format": "int64" }, "totalCost": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "description": "The total cost of runs made with this model. `null` if pricing is undefined.", "format": "double" } }, "description": "A model's run summary. The input to cost computation." }, "RunRecord": { "required": [ "id", "agentName", "status", "startedAt" ], "type": "object", "properties": { "id": { "type": "string", "description": "Gets the run id. A time-ordered UUID (v7).", "format": "uuid" }, "agentName": { "type": "string", "description": "Gets the name of the agent that ran. For workflow runs this is the workflow\nname: the existing lists, statistics and user interface read this column, and\nleaving it empty would show workflow rows without a name." }, "kind": { "description": "Gets whether this row records an agent or a workflow.", "$ref": "#/components/schemas/RunKind" }, "workflowName": { "type": [ "null", "string" ], "description": "Gets the name of the workflow. Populated only on\nRunKind.Workflow rows." }, "status": { "description": "Gets the current status of the run.", "$ref": "#/components/schemas/RunStatus" }, "startedAt": { "type": "string", "description": "Gets the start time (UTC).", "format": "date-time" }, "completedAt": { "type": [ "null", "string" ], "description": "Gets the completion time (UTC), or `null` while the run is in flight.", "format": "date-time" }, "tenantId": { "type": [ "null", "string" ], "description": "Gets the tenant the run belongs to." }, "userId": { "type": [ "null", "string" ], "description": "Gets the user the run belongs to, or `null` when it was\nnot known." }, "labels": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "Gets the labels the run carries, or `null` when it\ncarries none." }, "sessionId": { "type": [ "null", "string" ], "description": "Gets the id of the session that was used." }, "modelId": { "type": [ "null", "string" ], "description": "Gets the model used by the run. Cost and per-model reports need it. It is\n`null` when the agent definition carries no model." }, "modelProvider": { "type": [ "null", "string" ], "description": "Gets the provider of `ModelId`, or `null` for\na row written before this column existed. Rows written before are not\nbackfilled — see `POST /api/stats/recalculate-costs`." }, "isStreaming": { "type": "boolean", "description": "Gets whether the run streamed." }, "usage": { "oneOf": [ { "type": "null" }, { "description": "Gets the token usage, or `null` when the provider reported none.", "$ref": "#/components/schemas/RunUsage" } ] }, "error": { "oneOf": [ { "type": "null" }, { "description": "Gets the error information. Populated only for RunStatus.Failed.", "$ref": "#/components/schemas/RunError" } ] }, "eventCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Gets the number of events written for this run.", "format": "int64" }, "parentRunId": { "type": [ "null", "string" ], "description": "Gets the id of the run that started this one, or `null` for a\nroot run.", "format": "uuid" }, "rootRunId": { "type": [ "null", "string" ], "description": "Gets the id of the run at the root of the tree. `null` for a\nroot run and always populated for a child run.", "format": "uuid" }, "depth": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Gets the depth in the tree. The root run is 0.", "format": "int32" }, "agentVersion": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Gets the definition version this run measured, or `null` when unknown.", "format": "int32" }, "experimentId": { "type": [ "null", "string" ], "description": "Gets the experiment this run belongs to, or `null` outside an experiment.", "format": "uuid" }, "variant": { "type": [ "null", "string" ], "description": "Gets the experiment variant this run was assigned to, or `null` outside an experiment." }, "childRunCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Gets the number of direct child runs.", "format": "int32" }, "treeUsage": { "oneOf": [ { "type": "null" }, { "description": "Gets the total token usage of this run and every run below it.", "$ref": "#/components/schemas/RunUsage" } ] }, "cost": { "oneOf": [ { "type": "null" }, { "description": "Gets the run's own cost. `null` when the model is unknown;\nwhen the model is known the value is populated even if the price is not.", "$ref": "#/components/schemas/RunCost" } ] }, "treeCost": { "oneOf": [ { "type": "null" }, { "description": "Gets the total cost of this run and every run below it.", "$ref": "#/components/schemas/RunTreeCost" } ] }, "replayOfRunId": { "type": [ "null", "string" ], "description": "Gets the source run id when this run is a replay, otherwise\n`null`.", "format": "uuid" }, "continuedFromRunId": { "type": [ "null", "string" ], "description": "Gets the id of the run this one continues after an interruption, or\n`null` for a run that is not a continuation.", "format": "uuid" } }, "description": "Summary of a run. It acts as the header of the event stream." }, "RunReplayRequest": { "type": "object", "properties": { "agentVersion": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "The agent definition version to use. The currently active version if not given.", "format": "int32" }, "modelId": { "type": [ "null", "string" ], "description": "The model name to override with. The definition's own model is used if not given." }, "toolMode": { "description": "The tool behavior. Defaults to ReplayToolMode.ReplayTools.", "$ref": "#/components/schemas/ReplayToolMode" } }, "description": "A replay request." }, "RunReplayResponse": { "required": [ "runId", "sourceRunId", "toolMode", "compareLocation" ], "type": "object", "properties": { "runId": { "type": "string", "description": "Identifier of the newly started run.", "format": "uuid" }, "sourceRunId": { "type": "string", "description": "Identifier of the source run. Same as `runs.replay_of_run_id`.", "format": "uuid" }, "toolMode": { "description": "Tool mode applied.", "$ref": "#/components/schemas/ReplayToolMode" }, "agentVersion": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Definition version used. `null` for a code agent.", "format": "int32" }, "modelId": { "type": [ "null", "string" ], "description": "Model used." }, "output": { "type": [ "null", "string" ], "description": "Text produced by the model." }, "compareLocation": { "type": "string", "description": "Address of the endpoint that places the two runs side by side." } }, "description": "Result of a replay." }, "RunScore": { "required": [ "tenantId", "runId", "name", "kind", "source" ], "type": "object", "properties": { "id": { "type": "string", "description": "The score's identifier.", "format": "uuid" }, "tenantId": { "type": "string", "description": "The tenant." }, "runId": { "type": "string", "description": "The identifier of the run being scored.", "format": "uuid" }, "messageId": { "type": [ "null", "string" ], "description": "The identifier of the message being scored. If empty, the score belongs to the whole run." }, "name": { "type": "string", "description": "The score's stable, low-cardinality name — part of the uniqueness key." }, "kind": { "description": "The shape of the value.", "$ref": "#/components/schemas/RunScoreKind" }, "value": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "description": "The numeric value: 0/1 for RunScoreKind.Binary, 1 to 5 for\nRunScoreKind.Stars, 0 to 100 for\nRunScoreKind.Numeric.", "format": "double" }, "textValue": { "type": [ "null", "string" ], "description": "The categorical value. Set only for a RunScoreKind.Categorical score." }, "comment": { "type": [ "null", "string" ], "description": "A free-text comment." }, "source": { "type": "string", "description": "The score's source: `human`, `api`, or `judge:{name}`." }, "author": { "type": [ "null", "string" ], "description": "The actor who gave the score. `null` in an identity-less setup." }, "createdAt": { "type": "string", "description": "The creation/last-updated time.", "format": "date-time" } }, "description": "A human (or judge) score for a run or for a single message within a run." }, "RunScoreAggregate": { "required": [ "key", "kind", "count" ], "type": "object", "properties": { "key": { "type": "string", "description": "The breakdown key: a score name, an author, a source, or an agent name,\ndepending on which list this entry is in." }, "kind": { "description": "The shape every score in this group shares.", "$ref": "#/components/schemas/RunScoreKind" }, "count": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of scores in the group, INCLUDING those carrying no value.", "format": "int64" }, "noValueCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of scores in the group carrying no value\n(`Value` is `null`). A\nRunScoreKind.Categorical score always carries no value, so\nfor that kind this equals `Count`. Never counted into\n`Average`.", "format": "int64" }, "average": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "description": "The average value. `null` for\nRunScoreKind.Categorical, or when every score in the group\ncarries no value.", "format": "double" }, "minimum": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "description": "The smallest value. Same null rule as `Average`.", "format": "double" }, "maximum": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "description": "The largest value. Same null rule as `Average`.", "format": "double" }, "categories": { "type": "object", "additionalProperties": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "description": "Count per category (`TextValue`), highest count\nfirst. Populated only on IReadOnlyList<RunScoreAggregate> RunScoreSummary.ByName entries\nwhose RunScoreKind RunScoreAggregate.Kind is RunScoreKind.Categorical; every\nother group carries an empty map." }, "truncatedCategoryCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of distinct categories that did NOT fit inside\nIReadOnlyDictionary<string, long> RunScoreAggregate.Categories because `MaxRows` (RunScoreQuery) was\nreached. Zero when nothing was cut. Reported instead of silently\ndropping categories, which would read as \"these categories do not exist\".", "format": "int64" } }, "description": "One aggregated group: every score sharing a breakdown key AND a\nRunScoreKind." }, "RunScoreBucket": { "enum": [ "Hour", "Day", "Week", null ] }, "RunScoreBucketAggregate": { "required": [ "bucketStart", "groups" ], "type": "object", "properties": { "bucketStart": { "type": "string", "description": "The bucket's start time (UTC).", "format": "date-time" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/RunScoreAggregate" }, "description": "The name/kind groups scored inside this bucket — grouped exactly like\nIReadOnlyList<RunScoreAggregate> RunScoreSummary.ByName, bounded by\nint RunScoreQuery.MaxRows. Every entry's IReadOnlyDictionary<string, long> RunScoreAggregate.Categories\nis empty; a categorical breakdown over time is out of scope for this series." } }, "description": "One time bucket of the trend series (IReadOnlyList<RunScoreBucketAggregate> RunScoreSummary.Series)." }, "RunScoreKind": { "enum": [ "Binary", "Stars", "Numeric", "Categorical" ], "description": "The shape of the value a RunScore carries." }, "RunScoreSummary": { "required": [ "byName" ], "type": "object", "properties": { "byName": { "type": "array", "items": { "$ref": "#/components/schemas/RunScoreAggregate" }, "description": "The breakdown by score name — the primary breakdown, always populated." }, "byAuthor": { "type": "array", "items": { "$ref": "#/components/schemas/RunScoreAggregate" }, "description": "The breakdown by author. Scores with no author (an identity-less setup) are excluded." }, "bySource": { "type": "array", "items": { "$ref": "#/components/schemas/RunScoreAggregate" }, "description": "The breakdown by source (`human`, `api`, `judge:{name}`)." }, "byAgent": { "type": "array", "items": { "$ref": "#/components/schemas/RunScoreAggregate" }, "description": "The breakdown by the agent that produced the scored run." }, "series": { "type": "array", "items": { "$ref": "#/components/schemas/RunScoreBucketAggregate" }, "description": "The trend series, one entry per time bucket. Empty when\n`Bucket` (RunScoreQuery) was not given. Buckets with no matching\nscore are NOT included — this is a sparse series, not a filled one." } }, "description": "The result of ValueTask<RunScoreSummary> IRunScoreStore.SummarizeAsync(RunScoreQuery query, CancellationToken cancellationToken = default(CancellationToken))." }, "RunScoreTarget": { "enum": [ "Any", "Run", "Message", null ] }, "RunStatistics": { "required": [ "totalRuns", "completedRuns", "failedRuns", "canceledRuns", "runningRuns" ], "type": "object", "properties": { "totalRuns": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The total number of runs matching the filter.", "format": "int64" }, "completedRuns": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of runs that completed successfully.", "format": "int64" }, "failedRuns": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of runs that ended in an error.", "format": "int64" }, "canceledRuns": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of cancelled runs.", "format": "int64" }, "runningRuns": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of runs still running.", "format": "int64" }, "awaitingInputRuns": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of runs awaiting human input.", "format": "int64" }, "inputTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The total input tokens.", "format": "int64" }, "outputTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The total output tokens.", "format": "int64" }, "totalTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The total tokens.", "format": "int64" }, "cachedInputTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The input tokens that were served from the prompt cache. Counted INSIDE\n`InputTokens`, so the two must not be added together.", "format": "int64" }, "reasoningTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The tokens spent on reasoning. Counted INSIDE `OutputTokens`.", "format": "int64" }, "audioInputTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The audio input tokens. Counted INSIDE `InputTokens`.", "format": "int64" }, "audioOutputTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The audio output tokens. Counted INSIDE `OutputTokens`.", "format": "int64" }, "byAgent": { "type": "array", "items": { "$ref": "#/components/schemas/RunAgentStatistics" }, "description": "The breakdown by agent." }, "byModel": { "type": "array", "items": { "$ref": "#/components/schemas/RunModelStatistics" }, "description": "The breakdown by model. Runs with an unknown model name do not appear\nin this list; they are still counted in the totals." }, "byVersion": { "type": "array", "items": { "$ref": "#/components/schemas/RunVersionStatistics" }, "description": "The breakdown by definition version. Runs with an unknown version do not appear in this list." }, "byUser": { "type": "array", "items": { "$ref": "#/components/schemas/RunUserStatistics" }, "description": "The breakdown by user. Runs that carry no user identity do not appear\nin this list; they are still counted in the totals." }, "byLabel": { "type": "array", "items": { "$ref": "#/components/schemas/RunLabelStatistics" }, "description": "The breakdown by label. One entry per distinct key/value pair, so a run\ncarrying three labels contributes to three entries." }, "byErrorClass": { "type": "array", "items": { "$ref": "#/components/schemas/RunErrorStatistics" }, "description": "The breakdown by error class. Only runs that ended in an error are\ncounted. Rows written before the error class was added appear in the\n`Unknown` bucket (past rows are not backfilled)." }, "totalCost": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "description": "The total cost. If a model has undefined pricing, that model's run\ncosts are not included in this total (only runs with\nknown pricing are summed); the number of runs excluded appears in\n`RunsWithUnknownPricing`. `null` if no run\nwas ever priced.", "format": "double" }, "currency": { "type": [ "null", "string" ], "description": "The currency. Populated when `TotalCost` is populated." }, "runsWithUnknownPricing": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of runs whose model is known but whose pricing is undefined.", "format": "int64" }, "errorRate": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "description": "The error rate among settled runs (0–1). `null` if no\nrun has settled.", "format": "double" }, "scoredRuns": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of runs that received at least one RunScore\n(at the run or message level). Eval runs (RunKind.Eval)\nare excluded for the same reason as `TotalRuns`.", "format": "int64" }, "positiveRate": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "description": "The positive rate among RunScoreKind.Binary scores (0–1).\nStar ratings are not included in this rate — averaging the two kinds\nwould be meaningless. `null` if there is no binary score.", "format": "double" } }, "description": "A summary of the runs in a time range." }, "RunStatus": { "enum": [ "Running", "Completed", "Failed", "Canceled", "AwaitingInput", "Queued", "AwaitingApproval" ], "description": "Status of a run." }, "RunTrace": { "required": [ "id", "traceId", "tenantId", "startedAt" ], "type": "object", "properties": { "id": { "type": "string", "description": "The database identifier.", "format": "uuid" }, "traceId": { "type": "string", "description": "The W3C trace identifier (32-character hex)." }, "runId": { "type": [ "null", "string" ], "description": "The associated run. `null` for spans without a run.", "format": "uuid" }, "tenantId": { "type": "string", "description": "The tenant identifier." }, "startedAt": { "type": "string", "description": "The first span's start (UTC).", "format": "date-time" }, "endedAt": { "type": [ "null", "string" ], "description": "The last span's end (UTC).", "format": "date-time" }, "spans": { "type": "array", "items": { "$ref": "#/components/schemas/TraceSpan" }, "description": "The spans, ordered by start time." } }, "description": "A run's span tree. The waterfall view is built on top of this." }, "RunTreeCost": { "type": "object", "properties": { "inputCost": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "description": "Gets the total input cost across the tree.", "format": "double" }, "outputCost": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "description": "Gets the total output cost across the tree.", "format": "double" }, "cachedInputCost": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "description": "Gets the total cached-input cost across the tree.", "format": "double" }, "currency": { "type": [ "null", "string" ], "description": "Gets the currency." }, "runsWithUnknownPricing": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Gets how many runs in the tree have an unknown price.", "format": "int64" } }, "description": "Total cost of a run tree (the root plus every child run)." }, "RunUsage": { "type": "object", "properties": { "inputTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Gets the number of input tokens.", "format": "int64" }, "outputTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Gets the number of output tokens.", "format": "int64" }, "totalTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Gets the total number of tokens.", "format": "int64" }, "cachedInputTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Gets the input tokens that were served from the provider's prompt\ncache. Counted INSIDE `InputTokens`.", "format": "int64" }, "reasoningTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Gets the tokens the model spent on reasoning. Counted INSIDE\n`OutputTokens`.", "format": "int64" }, "audioInputTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Gets the audio input tokens. Counted INSIDE `InputTokens`.", "format": "int64" }, "audioOutputTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Gets the audio output tokens. Counted INSIDE `OutputTokens`.", "format": "int64" } }, "description": "Token usage of a run." }, "RunUserStatistics": { "required": [ "userId", "totalRuns", "failedRuns" ], "type": "object", "properties": { "userId": { "type": "string", "description": "The user identity." }, "totalRuns": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "This user's total number of runs.", "format": "int64" }, "failedRuns": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "This user's number of runs that ended in an error.", "format": "int64" }, "totalTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "This user's total token usage.", "format": "int64" }, "totalCost": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "description": "This user's total cost. `null` if no run of theirs was ever priced.", "format": "double" } }, "description": "A user's run summary." }, "RunVersionStatistics": { "required": [ "agentName", "version", "totalRuns", "failedRuns" ], "type": "object", "properties": { "agentName": { "type": "string", "description": "The agent name this breakdown belongs to." }, "version": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The definition version.", "format": "int32" }, "totalRuns": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The total number of runs made with this version.", "format": "int64" }, "failedRuns": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "This version's number of runs that ended in an error.", "format": "int64" }, "totalTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "This version's total token usage.", "format": "int64" } }, "description": "A definition version's run summary." }, "SearchKnowledgeHit": { "required": [ "sourceId", "chunkIndex", "content", "distance" ], "type": "object", "properties": { "sourceId": { "type": "string", "description": "Identifier of the source the chunk belongs to." }, "chunkIndex": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Sequence number within the source.", "format": "int32" }, "content": { "type": "string", "description": "The chunk's text." }, "distance": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "description": "Cosine distance. A smaller value means closer.", "format": "double" }, "metadata": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "Optional metadata given at write time." } }, "description": "A semantic search hit." }, "SearchKnowledgeRequest": { "required": [ "query" ], "type": "object", "properties": { "query": { "type": "string", "description": "Natural language query to search." }, "top": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Number of results to return. If not given, the default in configuration is used.", "format": "int32" } }, "description": "A semantic search request." }, "SessionBranchRequest": { "type": "object", "properties": { "upToSequence": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "The sequence number of the last item to include (inclusive). If not\ngiven, the whole conversation is copied.", "format": "int64" }, "newSessionId": { "type": [ "null", "string" ], "description": "The identifier of the new session to open. Generated if not given." } }, "description": "A request to branch a conversation from a specific point." }, "SessionBranchResult": { "required": [ "sessionId", "conversationId", "parentSessionId", "parentConversationId", "branchFromSequence", "copiedItemCount" ], "type": "object", "properties": { "sessionId": { "type": "string", "description": "The new session's identifier." }, "conversationId": { "type": "string", "description": "The new conversation's identifier.", "format": "uuid" }, "parentSessionId": { "type": "string", "description": "The source session's identifier." }, "parentConversationId": { "type": "string", "description": "The source conversation's identifier.", "format": "uuid" }, "branchFromSequence": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The branch point: the sequence number of the last item copied to the\nnew conversation. `-1` if no item was copied.", "format": "int64" }, "copiedItemCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of items copied.", "format": "int32" } }, "description": "The result of branching." }, "SessionDetailResponse": { "required": [ "id", "agentName", "createdAt", "updatedAt", "state" ], "type": "object", "properties": { "id": { "type": "string", "description": "Session identifier." }, "agentName": { "type": "string", "description": "Agent the session belongs to." }, "tenantId": { "type": [ "null", "string" ], "description": "Tenant identifier." }, "createdAt": { "type": "string", "description": "Creation time.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "Last update time.", "format": "date-time" }, "messages": { "oneOf": [ { "type": "null" }, { "description": "Chat history. Returns `null` if the history could not\nbe read (e.g. the agent is no longer in the catalog).", "$ref": "#/components/schemas/JsonElement" } ] }, "state": { "description": "Serialized session state.", "$ref": "#/components/schemas/JsonElement" } }, "description": "Detailed view of a single session: metadata and chat history." }, "SessionRecord": { "required": [ "id", "agentName", "state", "createdAt", "updatedAt" ], "type": "object", "properties": { "id": { "type": "string", "description": "The session identifier." }, "agentName": { "type": "string", "description": "The agent the session belongs to." }, "state": { "description": "The serialized session state. Microsoft Agent Framework's\n`SerializeSessionAsync` output, treated as opaque.", "$ref": "#/components/schemas/JsonElement" }, "createdAt": { "type": "string", "description": "The creation time (UTC).", "format": "date-time" }, "updatedAt": { "type": "string", "description": "The last-updated time (UTC).", "format": "date-time" }, "tenantId": { "type": [ "null", "string" ], "description": "The tenant identifier." }, "ownerId": { "type": [ "null", "string" ], "description": "The user the session belongs to, or `null` when the\nsession is unowned." }, "stateSchemaVersion": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The Tracon schema generation that wrote `State`.", "format": "int32" }, "stateMafVersion": { "type": [ "null", "string" ], "description": "The Microsoft Agent Framework package version that produced\n`State`." }, "version": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The record's write generation, used for optimistic concurrency.", "format": "int64" } }, "description": "A stored session." }, "SkillScriptGrant": { "required": [ "tenantId", "skillName" ], "type": "object", "properties": { "id": { "type": "string", "description": "The grant record identifier. A time-ordered UUID (v7).", "format": "uuid" }, "tenantId": { "type": "string", "description": "The tenant the grant belongs to." }, "skillName": { "type": "string", "description": "The name of the skill granted." }, "scriptName": { "type": [ "null", "string" ], "description": "The name of the script granted. If `null`, all of the\nskill's scripts are covered." }, "grantedBy": { "type": [ "null", "string" ], "description": "The actor who gave the grant." }, "grantedAt": { "type": "string", "description": "The moment the grant was given (UTC).", "format": "date-time" }, "expiresAt": { "type": [ "null", "string" ], "description": "The moment the grant expires. Never expires if `null`.", "format": "date-time" }, "revokedAt": { "type": [ "null", "string" ], "description": "The moment the grant was revoked. Active if `null`.", "format": "date-time" } }, "description": "The record carrying permission to execute a skill script." }, "SkillScriptGrantRequest": { "required": [ "skillName" ], "type": "object", "properties": { "skillName": { "type": "string", "description": "Name of the skill being granted permission." }, "scriptName": { "type": [ "null", "string" ], "description": "Name of the script being granted permission. If `null`,\nevery script of the skill is covered." }, "expiresAt": { "type": [ "null", "string" ], "description": "Expiration time of the grant. If `null`, it is unlimited.", "format": "date-time" } }, "description": "Request to grant script execution permission." }, "SpeakRequest": { "required": [ "text" ], "type": "object", "properties": { "text": { "type": "string", "description": "The text to speak." }, "sessionId": { "type": [ "null", "string" ], "description": "The session the attachment is bound to. If left empty, the\nattachment is considered orphaned and deleted by the retention policy." }, "voiceId": { "type": [ "null", "string" ], "description": "The identifier of the voice to use. The default voice if empty." }, "includeTimestamps": { "type": "boolean", "description": "Requests character-level timing alongside the audio. Default `false`." } }, "description": "A speech synthesis request as an operator action." }, "SpeakResponse": { "required": [ "attachment", "characters", "isEstimated" ], "type": "object", "properties": { "attachment": { "description": "The saved attachment.", "$ref": "#/components/schemas/AttachmentDescriptor" }, "characters": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The billed character count.", "format": "int32" }, "isEstimated": { "type": "boolean", "description": "Whether the character count is estimated." }, "cost": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "description": "The computed amount. `null` if pricing is undefined.", "format": "double" }, "currency": { "type": [ "null", "string" ], "description": "The currency label." }, "alignment": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/SpeechAlignment" }, "description": "Character-level timing. `null` when not requested via\n`SpeakRequest.IncludeTimestamps`, or when the provider does not support it." } }, "description": "The result of speech synthesis." }, "SpeechAlignment": { "required": [ "character", "start", "end" ], "type": "object", "properties": { "character": { "type": "string", "description": "The character, as sent in the request text." }, "start": { "pattern": "^-?(\\d+\\.)?\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,7})?$", "type": "string", "description": "When the character starts, relative to the start of the audio." }, "end": { "pattern": "^-?(\\d+\\.)?\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,7})?$", "type": "string", "description": "When the character ends, relative to the start of the audio." } }, "description": "One character's position in the generated audio." }, "Stream": { "type": "string", "format": "binary" }, "SubAgentSettings": { "type": "object", "properties": { "childDeadline": { "pattern": "^-?(\\d+\\.)?\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,7})?$", "type": [ "null", "string" ], "description": "Gets the deadline applied to a single sub-agent run (the cooperative layer)." }, "waitTimeout": { "pattern": "^-?(\\d+\\.)?\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,7})?$", "type": [ "null", "string" ], "description": "Gets the hard wait cutoff handed to the framework (the hard-cutoff layer).\nMust be greater than `ChildDeadline`." } }, "description": "Determines how long an agent waits for the agents it calls." }, "TenantDescriptor": { "required": [ "id", "slug", "displayName" ], "type": "object", "properties": { "id": { "type": "string", "description": "The tenant identifier. A time-ordered UUID (v7).", "format": "uuid" }, "slug": { "type": "string", "description": "The tenant key. The same text as the `tenant_id` column in other\ntables, and `ITenantContext.TenantId` returns this value." }, "displayName": { "type": "string", "description": "The name shown in the UI." }, "createdAt": { "type": "string", "description": "The creation time (UTC).", "format": "date-time" } }, "description": "A registered tenant." }, "TenantEgressPolicyRequest": { "type": "object", "properties": { "allowedProviders": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Gets the closed set of allowed provider names. An empty list allows no provider." } }, "description": "The request body for creating or replacing a tenant's egress policy." }, "TenantEgressPolicyResponse": { "required": [ "tenantId" ], "type": "object", "properties": { "tenantId": { "type": "string", "description": "Gets the tenant this policy belongs to." }, "allowedProviders": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Gets the closed set of allowed provider names, or `null`\nwhen the tenant is unrestricted (no policy saved)." }, "updatedAt": { "type": [ "null", "string" ], "description": "Gets the time the policy was last written; `null` when unrestricted.", "format": "date-time" } }, "description": "The response describing a tenant's egress policy." }, "TenantProviderBindingRequest": { "type": "object", "properties": { "apiKeyConfigurationName": { "type": [ "null", "string" ], "description": "Gets the configuration key name the credential is read from. Never a value." }, "endpoint": { "type": [ "null", "string" ], "description": "Gets the optional endpoint override." } }, "description": "The request body for creating or replacing a tenant provider binding." }, "TenantProviderBindingResponse": { "required": [ "providerName", "apiKeyConfigurationName", "resolved", "updatedAt" ], "type": "object", "properties": { "providerName": { "type": "string", "description": "Gets the provider name." }, "apiKeyConfigurationName": { "type": "string", "description": "Gets the configuration key name the credential is read from." }, "endpoint": { "type": [ "null", "string" ], "description": "Gets the optional endpoint override." }, "resolved": { "type": "boolean", "description": "Gets whether `ApiKeyConfigurationName` currently resolves to a value." }, "updatedAt": { "type": "string", "description": "Gets the time this binding was last written.", "format": "date-time" } }, "description": "The response describing a tenant provider binding." }, "TenantRequest": { "type": "object", "properties": { "displayName": { "type": [ "null", "string" ], "description": "Name shown in the UI. If left empty, the key is used." } }, "description": "Request to create/update a tenant record." }, "TimeSeriesBucket": { "enum": [ "Hour", "Day", null ] }, "TimeSeriesPoint": { "required": [ "bucket" ], "type": "object", "properties": { "bucket": { "type": "string", "description": "The bucket's start time (UTC).", "format": "date-time" }, "runs": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of runs that started in this bucket.", "format": "int64" }, "failedRuns": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of runs that ended in an error in this bucket.", "format": "int64" }, "inputTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The total input tokens.", "format": "int64" }, "outputTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The total output tokens.", "format": "int64" }, "cost": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "description": "The total cost. `null` if no run was ever priced.", "format": "double" }, "averageDurationMs": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "description": "The average duration of settled runs (milliseconds).", "format": "double" } }, "description": "A summary of the runs in a time bucket. The result unit of\n`/api/stats/timeseries`; empty buckets are also returned (with zero events)." }, "ToolApprovalDecision": { "required": [ "requestId", "approved" ], "type": "object", "properties": { "requestId": { "type": "string", "description": "Identifier of the approved request. This is the\n`ToolApprovalRequestContent.RequestId` value received in the stream." }, "approved": { "type": "boolean", "description": "Whether the call is approved." }, "reason": { "type": [ "null", "string" ], "description": "Reason for the decision. Passed on to the model." }, "remember": { "type": "boolean", "description": "Whether the decision should be saved as a permanent rule (\"don't ask\nagain\"). Meaningful only while `Approved` is `true`." }, "rememberArgumentsOnly": { "type": "boolean", "description": "Whether the permanent rule covers only a call with the same arguments.\nIf `false`, it covers every call to the tool." } }, "description": "Tool approval decision sent from the UI." }, "ToolApprovalPresentation": { "type": "object", "properties": { "entityType": { "type": [ "null", "string" ], "description": "Gets the kind of entity the call acts on (for example `\"skill\"` or `\"order\"`)." }, "entityId": { "type": [ "null", "string" ], "description": "Gets the entity's own identifier, as read from the call's arguments." }, "entityName": { "type": [ "null", "string" ], "description": "Gets the entity's human-readable name, resolved from `EntityId`." }, "message": { "type": [ "null", "string" ], "description": "Gets a free-form sentence describing the call, for a reviewer who has none of the above." } }, "description": "A human-readable projection of one tool-approval request, produced by a consumer's\nIToolApprovalPresenter." }, "ToolApprovalRule": { "required": [ "id", "tenantId", "toolName", "createdAt" ], "type": "object", "properties": { "id": { "type": "string", "description": "Gets the rule id. A time-ordered UUID (v7).", "format": "uuid" }, "tenantId": { "type": "string", "description": "Gets the tenant the rule holds in." }, "agentName": { "type": [ "null", "string" ], "description": "Gets the agent the rule holds for. When `null` it covers every\nagent of the tenant." }, "toolName": { "type": "string", "description": "Gets the tool the rule holds for." }, "argumentsHash": { "type": [ "null", "string" ], "description": "Gets the argument fingerprint. When it is populated the rule covers only a call\nmade with the same arguments." }, "argumentConditions": { "type": "array", "items": { "$ref": "#/components/schemas/ToolArgumentCondition" }, "description": "Gets the argument conditions. All conditions must match for the rule to apply\n(`AND`); an empty list matches every call of the tool. Mutually exclusive\nwith `ArgumentsHash` — a rule carries one or the other, never both." }, "createdBy": { "type": [ "null", "string" ], "description": "Gets who created the rule, or `null` when there is no authentication." }, "createdAt": { "type": "string", "description": "Gets the creation time (UTC).", "format": "date-time" } }, "description": "A persistent approval rule for a tool call the user said \"do not ask again\" for." }, "ToolApprovalRuleRequest": { "required": [ "toolName" ], "type": "object", "properties": { "agentName": { "type": [ "null", "string" ], "description": "The agent the rule holds for. When empty it covers every agent of the tenant." }, "toolName": { "type": "string", "description": "The tool the rule holds for." }, "argumentConditions": { "type": "array", "items": { "$ref": "#/components/schemas/ToolArgumentCondition" }, "description": "All conditions must match for the rule to apply (`AND`). An empty list\n(the default) matches every call of the tool." } }, "description": "Request to create a persistent, argument-conditioned approval rule." }, "ToolArgumentCondition": { "required": [ "path", "operator", "value" ], "type": "object", "properties": { "path": { "type": "string", "description": "Gets the dotted path into the argument object, for example `order.amount`.\nNo array index is accepted." }, "operator": { "description": "Gets the comparison operator.", "$ref": "#/components/schemas/ToolArgumentOperator" }, "value": { "description": "Gets the value compared against. For ToolArgumentOperator.In and\nToolArgumentOperator.NotIn this is a JSON array of text or numbers;\nfor every other operator it is a single text, number, or boolean.", "$ref": "#/components/schemas/JsonElement" } }, "description": "One comparison against a tool call argument: path · operator · value." }, "ToolArgumentOperator": { "enum": [ "Equals", "NotEquals", "GreaterThan", "GreaterThanOrEqual", "LessThan", "LessThanOrEqual", "In", "NotIn" ], "description": "A comparison operator for a ToolArgumentCondition." }, "ToolCallContent": { "type": "object", "anyOf": [ { "$ref": "#/components/schemas/ToolCallContentFunctionCallContent" }, { "$ref": "#/components/schemas/ToolCallContentMcpServerToolCallContent" }, { "$ref": "#/components/schemas/ToolCallContentImageGenerationToolCallContent" }, { "$ref": "#/components/schemas/ToolCallContentCodeInterpreterToolCallContent" }, { "$ref": "#/components/schemas/ToolCallContentWebSearchToolCallContent" }, { "$ref": "#/components/schemas/ToolCallContentBase" } ] }, "ToolCallContentBase": { "required": [ "callId" ], "properties": { "callId": { "type": "string" }, "annotations": {}, "additionalProperties": {} } }, "ToolCallContentCodeInterpreterToolCallContent": { "required": [ "$type", "callId" ], "properties": { "$type": { "enum": [ "codeInterpreterToolCall" ], "type": "string" }, "inputs": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AIContent" } }, "callId": { "type": "string" }, "annotations": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AIAnnotation" } }, "additionalProperties": { "type": [ "null", "object" ] } } }, "ToolCallContentFunctionCallContent": { "required": [ "$type", "name", "callId" ], "properties": { "$type": { "enum": [ "functionCall" ], "type": "string" }, "name": { "type": "string" }, "arguments": {}, "informationalOnly": { "type": "boolean" }, "callId": { "type": "string" }, "annotations": {}, "additionalProperties": {} } }, "ToolCallContentImageGenerationToolCallContent": { "required": [ "$type", "callId" ], "properties": { "$type": { "enum": [ "imageGenerationToolCall" ], "type": "string" }, "callId": { "type": "string" }, "annotations": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AIAnnotation" } }, "additionalProperties": { "type": [ "null", "object" ] } } }, "ToolCallContentMcpServerToolCallContent": { "required": [ "$type", "name", "serverName", "callId" ], "properties": { "$type": { "enum": [ "mcpServerToolCall" ], "type": "string" }, "name": { "type": "string" }, "serverName": { "type": [ "null", "string" ] }, "arguments": { "type": [ "null", "object" ] }, "callId": { "type": "string" }, "annotations": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AIAnnotation" } }, "additionalProperties": { "type": [ "null", "object" ] } } }, "ToolCallContentWebSearchToolCallContent": { "required": [ "$type", "callId" ], "properties": { "$type": { "enum": [ "webSearchToolCall" ], "type": "string" }, "queries": { "type": [ "null", "array" ], "items": { "type": "string" } }, "callId": { "type": "string" }, "annotations": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AIAnnotation" } }, "additionalProperties": { "type": [ "null", "object" ] } } }, "ToolCallUsage": { "required": [ "unit", "quantity" ], "type": "object", "properties": { "unit": { "type": "string", "description": "The measurement unit. See ToolUsageUnits for known values." }, "quantity": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "description": "The billed quantity.", "format": "double" }, "cost": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "description": "The computed amount. Stays `null` if the\nconfiguration has no price for this tool — not zero.", "format": "double" }, "currency": { "type": [ "null", "string" ], "description": "The currency. Comes from `Tracon:Pricing:Currency`." }, "isEstimated": { "type": "boolean", "description": "Whether the quantity was measured or estimated." } }, "description": "A single tool call's non-token measurement and cost." }, "ToolDescriptor": { "required": [ "name" ], "type": "object", "properties": { "name": { "type": "string", "description": "The tool name. Used in agent definitions." }, "description": { "type": [ "null", "string" ], "description": "The description that lets the model understand when to call the tool." }, "jsonSchema": { "type": [ "null", "string" ], "description": "The arguments' JSON schema." }, "requiresApproval": { "type": "boolean", "description": "Whether explicit approval is required before the call." }, "source": { "type": [ "null", "string" ], "description": "The tool's source. `null` for tools defined in code;\nthe server name for tools coming from a remote MCP server." }, "runsOnClient": { "type": "boolean", "description": "Whether the tool's body runs on the caller (typically a browser)\ninstead of on the server." }, "effect": { "description": "The tool's effect class. Defaults to ToolEffect.Read.", "$ref": "#/components/schemas/ToolEffect" }, "requiredPermission": { "type": [ "null", "string" ], "description": "The permission name a caller must hold to call this tool, or\n`null` when the tool declares none." }, "timeout": { "pattern": "^-?(\\d+\\.)?\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,7})?$", "type": [ "null", "string" ], "description": "The longest duration this tool's call may run, or `null`\nto use the installation default (`TraconOptions.Tools.DefaultTimeout`)." }, "safeToRepeat": { "type": "boolean", "description": "Whether this tool's call may run again when an interrupted run is\ncontinued. See `TraconToolRegistration.SafeToRepeat`." }, "maxOutputBytes": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "The most bytes (UTF-8) this tool's result may carry, or\n`null` to use the installation default\n(`TraconOptions.Tools.DefaultMaxOutputBytes`).", "format": "int32" } }, "description": "The UI-facing definition of a tool registered in code. The agent editor\nshows a selection from this list; it does not accept free-text input." }, "ToolEffect": { "enum": [ "Read", "Write", "Destructive", "External" ], "description": "Classifies the blast radius of a tool call." }, "ToolInvocationRecord": { "required": [ "id", "runId", "toolName", "createdAt" ], "type": "object", "properties": { "id": { "type": "string", "description": "The record identifier. A time-ordered UUID (v7).", "format": "uuid" }, "runId": { "type": "string", "description": "The run that made the call.", "format": "uuid" }, "toolName": { "type": "string", "description": "The name of the tool called." }, "toolCallId": { "type": [ "null", "string" ], "description": "The call identifier generated by the model. Distinguishes multiple calls of the same kind." }, "source": { "type": [ "null", "string" ], "description": "The tool's source. `null` for tools defined in code;\nthe server name for MCP tools." }, "arguments": { "type": [ "null", "string" ], "description": "The call arguments. Raw text; may not be valid JSON." }, "result": { "type": [ "null", "string" ], "description": "The call result. Raw text; may not be valid JSON." }, "duration": { "pattern": "^-?(\\d+\\.)?\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,7})?$", "type": [ "null", "string" ], "description": "The call's duration. `null` if the event pair did not match." }, "error": { "type": [ "null", "string" ], "description": "The error message. Populated only if the call errored." }, "createdAt": { "type": "string", "description": "The moment the call settled (UTC).", "format": "date-time" }, "usage": { "oneOf": [ { "type": "null" }, { "description": "The call's non-token measurement and cost. `null` if\nthe tool reported no measurement — which is empty for the vast\nmajority of calls.", "$ref": "#/components/schemas/ToolCallUsage" } ] }, "authorizationDenied": { "type": "boolean", "description": "Whether IToolAuthorizationHandler denied this call before it ran." }, "timedOut": { "type": "boolean", "description": "Whether the call ended because its execution timeout elapsed\n(TraconToolTimeoutException)." }, "succeeded": { "type": "boolean", "description": "Whether the call finished successfully." } }, "description": "The summary of a single completed tool call." }, "ToolUsage": { "required": [ "toolName", "totalCalls", "failedCalls" ], "type": "object", "properties": { "toolName": { "type": "string", "description": "The tool name." }, "totalCalls": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The total number of calls.", "format": "int64" }, "failedCalls": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of calls that errored.", "format": "int64" }, "averageDurationMs": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "description": "The average duration (milliseconds). `null` if no call carries a duration.", "format": "double" }, "lastCalledAt": { "type": [ "null", "string" ], "description": "The moment it was last called (UTC).", "format": "date-time" }, "errorRate": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "description": "The error rate among settled calls (0–1). `null` if there is no call.", "format": "double" } }, "description": "A tool's usage summary. Shown by the UI's Tools screen." }, "TraceSpan": { "required": [ "id", "spanId", "name", "startedAt" ], "type": "object", "properties": { "id": { "type": "string", "description": "The database identifier. Derived from the W3C identifiers.", "format": "uuid" }, "parentId": { "type": [ "null", "string" ], "description": "The parent span's database identifier. `null` for the root span.", "format": "uuid" }, "spanId": { "type": "string", "description": "The W3C span identifier (16-character hex)." }, "name": { "type": "string", "description": "The span name. Example: `chat gpt-5.4-mini`, `invoke_agent support`." }, "kind": { "description": "The span kind.", "$ref": "#/components/schemas/TraceSpanKind" }, "startedAt": { "type": "string", "description": "The start time (UTC).", "format": "date-time" }, "endedAt": { "type": [ "null", "string" ], "description": "The end time (UTC).", "format": "date-time" }, "status": { "description": "The result status.", "$ref": "#/components/schemas/TraceSpanStatus" }, "attributes": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The span attributes. GenAI semantic convention keys\n(`gen_ai.request.model`, `gen_ai.usage.input_tokens`) go here." } }, "description": "A single persisted OpenTelemetry span." }, "TraceSpanKind": { "enum": [ "Internal", "Server", "Client", "Producer", "Consumer" ], "description": "A span's OpenTelemetry kind. Values are stored in the database as\n`smallint`; the numbers are stable." }, "TraceSpanStatus": { "enum": [ "Unset", "Ok", "Error" ], "description": "A span's result status. `smallint` in the database." }, "TraconAuthenticationMeta": { "required": [ "allowRemoteAccess", "requiresBearerToken", "requiresAuthorizationPolicy" ], "type": "object", "properties": { "allowRemoteAccess": { "type": "boolean", "description": "Whether access from outside loopback is allowed." }, "requiresBearerToken": { "type": "boolean", "description": "Whether an `Authorization: Bearer` header is expected." }, "requiresAuthorizationPolicy": { "type": "boolean", "description": "Whether an ASP.NET Core authorization policy is applied." } }, "description": "Reports which authentication layers are enabled." }, "TraconDiagnosticsReport": { "required": [ "persistenceProvider", "registeredPersistenceProviders", "canConnect", "migrationsUpToDate", "pendingMigrations", "modelProviders", "configuration", "uiEmbedded", "toolCount", "agentCount", "agentSources", "extensionPoints" ], "type": "object", "properties": { "persistenceProvider": { "type": "string", "description": "Gets the name of the active persistence provider, for example `PostgreSQL` or `InMemory`." }, "registeredPersistenceProviders": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Gets the number of registered SQL persistence providers. More than `1`\nindicates a setup defect: the last call wins and silently disables the others.", "format": "int32" }, "canConnect": { "type": "boolean", "description": "Gets whether the active SQL provider can connect. Returns `true`\nwithout an SQL provider." }, "migrationsUpToDate": { "type": "boolean", "description": "Gets whether no migrations are pending. Returns `true` without an SQL provider." }, "pendingMigrations": { "type": "array", "items": { "type": "string" }, "description": "Gets the pending migration names. The list is empty when there is no SQL\nprovider or all migrations are applied." }, "modelProviders": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderDiagnostic" }, "description": "Gets the last known status of each registered model provider." }, "configuration": { "type": "array", "items": { "$ref": "#/components/schemas/ConfigurationDiagnostic" }, "description": "Gets the resolution status of configuration keys required by registered providers." }, "uiEmbedded": { "type": "boolean", "description": "Gets whether the management UI has embedded assets." }, "toolCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Gets the number of registered tools.", "format": "int32" }, "agentCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Gets the number of registered agents. Returns `null` when the catalog cannot be read.", "format": "int32" }, "agentSources": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSourceDiagnostic" }, "description": "Gets the agent sources registered in priority order." }, "extensionPoints": { "type": "array", "items": { "$ref": "#/components/schemas/ExtensionPointDiagnostic" }, "description": "Gets the embedding points a host application binds to attach Tracon\nto its own tenancy, identity, authorization, eventing, and storage." } }, "description": "Reports the self-diagnostics of the installation." }, "TraconMetaResponse": { "required": [ "version", "prefix", "authentication", "storage", "roles" ], "type": "object", "properties": { "version": { "type": "string", "description": "Tracon version." }, "prefix": { "type": "string", "description": "Path prefix the endpoints are connected to. The UI builds its own calls from this." }, "authentication": { "description": "Active authentication methods.", "$ref": "#/components/schemas/TraconAuthenticationMeta" }, "storage": { "description": "Active storage implementations.", "$ref": "#/components/schemas/TraconStorageMeta" }, "roles": { "description": "Role permissions of the current caller.", "$ref": "#/components/schemas/TraconRoleMeta" } }, "description": "Response for `{prefix}/api/meta`. Carries the minimum information the\nUI needs to configure itself." }, "TraconRoleMeta": { "required": [ "canRead", "canOperate", "canAdminister" ], "type": "object", "properties": { "canRead": { "type": "boolean", "description": "Whether the caller may read agents, runs, sessions, traces, and statistics." }, "canOperate": { "type": "boolean", "description": "Whether the caller may, in addition to Reader, start runs, give approvals, and delete sessions." }, "canAdminister": { "type": "boolean", "description": "Whether the caller may write agent definitions, add MCP servers, and manage tenants and audit trails." } }, "description": "Reports which role levels the current request's caller satisfies." }, "TraconStorageMeta": { "required": [ "persistent", "agentDefinitionStore", "runStore", "sessionStore", "jobStore", "jobWorkerEnabled" ], "type": "object", "properties": { "persistent": { "type": "boolean", "description": "Whether all three stores are persistent. Returns\n`false` if any is in-memory." }, "agentDefinitionStore": { "type": "string", "description": "Type name of the agent definition store." }, "runStore": { "type": "string", "description": "Type name of the run store." }, "sessionStore": { "type": "string", "description": "Type name of the session store." }, "jobStore": { "type": "string", "description": "Type name of the job queue store." }, "jobWorkerEnabled": { "type": "boolean", "description": "Whether the background job worker is running in this process. If\n`false`, the queue can still be written to and read\nfrom; only this process does not lease jobs." } }, "description": "Reports which storage implementations are active." }, "UploadDocumentChunk": { "required": [ "index", "content" ], "type": "object", "properties": { "index": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Sequence number within the source.", "format": "int32" }, "content": { "type": "string", "description": "The chunk's text." }, "embedding": { "type": [ "null", "array" ], "items": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "float" }, "description": "The chunk's embedding. If empty, the server embeds it; if filled in, it\nis written as is and returns 400 if it does not match the store's dimension." }, "metadata": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "Optional metadata." } }, "description": "A single ready-made chunk in an upload request." }, "UploadDocumentRequest": { "required": [ "sourceId" ], "type": "object", "properties": { "sourceId": { "type": "string", "description": "Source identifier. Uploading again with the same identifier replaces the old one." }, "text": { "type": [ "null", "string" ], "description": "Raw text. If given, the server chunks and embeds it." }, "chunks": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/UploadDocumentChunk" }, "description": "Ready-made chunks. If `UploadDocumentChunk.Embedding` is\nleft empty, the server embeds it; if it is filled in, it is written as is." } }, "description": "Request to upload a document." }, "UploadDocumentResponse": { "required": [ "sourceId", "chunkCount" ], "type": "object", "properties": { "sourceId": { "type": "string", "description": "Identifier of the uploaded source." }, "chunkCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Number of chunks written.", "format": "int32" } }, "description": "Result of a document upload request." }, "UsageDetails": { "type": "object", "properties": { "inputTokenCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int64" }, "outputTokenCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int64" }, "totalTokenCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int64" }, "cachedInputTokenCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int64" }, "reasoningTokenCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int64" }, "inputAudioTokenCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int64" }, "inputTextTokenCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int64" }, "outputAudioTokenCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int64" }, "outputTextTokenCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int64" }, "additionalCounts": { "type": [ "null", "object" ], "additionalProperties": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" } } } }, "ValidationMessage": { "required": [ "severity", "code", "message" ], "type": "object", "properties": { "severity": { "description": "Gets the severity of the finding.", "$ref": "#/components/schemas/ValidationSeverity" }, "code": { "type": "string", "description": "Gets the stable machine-readable code, for example `unknown_tool` or `cycle`." }, "message": { "type": "string", "description": "Gets the human-readable description. It is not translated." }, "path": { "type": [ "null", "string" ], "description": "Gets the path of the offending field inside the definition, for example\n`toolNames[2]`. It is `null` when the finding points at no field." } }, "description": "A single finding produced by the validation of an agent definition." }, "ValidationSeverity": { "enum": [ "Error", "Warning" ], "description": "The severity of a ValidationMessage." }, "VoiceDescriptor": { "required": [ "voiceId", "name" ], "type": "object", "properties": { "voiceId": { "type": "string", "description": "The voice identifier. Used in agent definitions and requests." }, "name": { "type": "string", "description": "The human-readable name." }, "category": { "type": [ "null", "string" ], "description": "The category given by the provider (for example, `premade`)." }, "attributes": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Provider-reported, bounded, safe scalar attributes (for example,\n`gender` or `language` — see `VoiceAttributeNames`)." } }, "description": "The definition of an available voice." }, "VoiceHealth": { "required": [ "providerName", "isHealthy", "latency", "checkedAt" ], "type": "object", "properties": { "providerName": { "type": "string", "description": "The provider name." }, "isHealthy": { "type": "boolean", "description": "Whether the provider is reachable." }, "latency": { "pattern": "^-?(\\d+\\.)?\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,7})?$", "type": "string", "description": "The check's duration." }, "checkedAt": { "type": "string", "description": "The moment the check was performed (UTC).", "format": "date-time" }, "detail": { "type": [ "null", "string" ], "description": "The reason, if failed. The text carries neither an API key nor an address." }, "voiceCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "The number of voices seen during the check.", "format": "int32" } }, "description": "The voice provider's reachability status." }, "VoiceSessionCost": { "type": "object", "properties": { "durationCost": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "description": "What the session's duration cost.", "format": "double" }, "characterCost": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "description": "What the synthesized characters cost.", "format": "double" }, "currency": { "type": [ "null", "string" ], "description": "The currency the amounts are in." } }, "description": "What one voice conversation cost." }, "VoiceSessionEndReason": { "enum": [ "Client", "IdleTimeout", "DurationLimit", "Error", "ServerShutdown", "Abandoned", "Provider", null ] }, "VoiceSessionRecord": { "required": [ "id", "tenantId", "sessionId", "agentName", "startedAt" ], "type": "object", "properties": { "id": { "type": "string", "description": "The connection's identifier.", "format": "uuid" }, "tenantId": { "type": "string", "description": "The tenant. Resolved when the connection is established and\nfixed for the connection's lifetime." }, "sessionId": { "type": "string", "description": "The identifier of the agent session the conversation runs in." }, "agentName": { "type": "string", "description": "The name of the agent being talked to." }, "startedAt": { "type": "string", "description": "The moment the connection opened.", "format": "date-time" }, "endedAt": { "type": [ "null", "string" ], "description": "The moment the connection closed; `null` while still open.", "format": "date-time" }, "turns": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of completed conversation turns.", "format": "int32" }, "inputSeconds": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "description": "The total resolved audio duration (seconds). Stays\n`null` if the provider does not report duration —\nTracon does not fabricate a duration.", "format": "double" }, "outputChars": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "The total characters synthesized to speech.", "format": "int64" }, "endReason": { "oneOf": [ { "type": "null" }, { "description": "Why the connection closed.", "$ref": "#/components/schemas/VoiceSessionEndReason" } ] }, "createdBy": { "type": [ "null", "string" ], "description": "The actor who opened the connection." }, "provider": { "type": [ "null", "string" ], "description": "The provider that hosted the conversation, e.g. `openai`;\n`null` when Tracon ran the conversation itself." }, "model": { "type": [ "null", "string" ], "description": "The model the conversation ran on; `null` when unknown." }, "liveSeconds": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "description": "The billable wall-clock duration of a provider-hosted live session, in seconds.", "format": "double" }, "cost": { "oneOf": [ { "type": "null" }, { "description": "What the conversation cost; `null` when nothing was priced.", "$ref": "#/components/schemas/VoiceSessionCost" } ] } }, "description": "The summary record of a real-time voice connection." }, "WebhookDelivery": { "required": [ "id", "subscriptionId", "tenantId", "eventType", "payload", "status", "createdAt" ], "type": "object", "properties": { "id": { "type": "string", "description": "The delivery identifier. Sent in the request as the `X-Tracon-Delivery` header.", "format": "uuid" }, "subscriptionId": { "type": "string", "description": "The subscription identifier.", "format": "uuid" }, "tenantId": { "type": "string", "description": "The tenant identifier." }, "eventType": { "type": "string", "description": "The event name." }, "payload": { "type": "string", "description": "The JSON body sent." }, "status": { "description": "The delivery's status.", "$ref": "#/components/schemas/WebhookDeliveryStatus" }, "attempt": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of attempts made.", "format": "int32" }, "responseCode": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "The HTTP status code the recipient returned. `null` if a\nconnection could not be established.", "format": "int32" }, "error": { "type": [ "null", "string" ], "description": "The most recent error message." }, "createdAt": { "type": "string", "description": "The creation time (UTC).", "format": "date-time" }, "deliveredAt": { "type": [ "null", "string" ], "description": "The successful delivery time (UTC).", "format": "date-time" } }, "description": "A single delivery record." }, "WebhookDeliveryStatus": { "enum": [ "Pending", "Delivered", "Failed", "Dropped" ], "description": "The status of a webhook delivery attempt." }, "WebhookSaveRequest": { "type": "object", "properties": { "url": { "type": [ "null", "string" ], "description": "The address events are sent to. Only `https` (or loopback `http`)." }, "events": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "The names of the subscribed events. See WebhookEvents." }, "secretConfigurationKey": { "type": [ "null", "string" ], "description": "The name of the configuration key from which the signing secret is read.\nNot the secret itself." }, "headers": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "Additional headers to add to every request." }, "enabled": { "type": "boolean", "description": "Whether the subscription is enabled." } }, "description": "The request body for saving a webhook subscription." }, "WebhookSubscription": { "required": [ "id", "tenantId", "name", "url", "events", "createdAt", "updatedAt" ], "type": "object", "properties": { "id": { "type": "string", "description": "The subscription identifier.", "format": "uuid" }, "tenantId": { "type": "string", "description": "The tenant the subscription belongs to." }, "name": { "type": "string", "description": "The name, unique within the tenant." }, "url": { "type": "string", "description": "The address events are sent to." }, "events": { "type": "array", "items": { "type": "string" }, "description": "The subscribed event names. See WebhookEvents." }, "secretConfigurationKey": { "type": [ "null", "string" ], "description": "The name of the configuration key the signing secret\nis read from. Not the secret itself." }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Extra headers added to every request." }, "enabled": { "type": "boolean", "description": "Whether the subscription is enabled." }, "consecutiveFailures": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The consecutive-failure count. Once the threshold is exceeded, the\nsubscription disables itself and is written to the audit trail.", "format": "int32" }, "createdAt": { "type": "string", "description": "The creation time (UTC).", "format": "date-time" }, "updatedAt": { "type": "string", "description": "The last-updated time (UTC).", "format": "date-time" } }, "description": "An external system's event subscription." }, "WebhookTestResponse": { "required": [ "name", "queued", "message" ], "type": "object", "properties": { "name": { "type": "string", "description": "The subscription name." }, "queued": { "type": "boolean", "description": "Whether the event was written to the queue." }, "message": { "type": "string", "description": "The description shown to the user." } }, "description": "The response for the test event." }, "WorkflowCheckpointRecord": { "required": [ "id", "tenantId", "sessionId", "checkpointId", "createdAt", "state" ], "type": "object", "properties": { "id": { "type": "string", "description": "Gets the record identifier. A time-ordered UUID (v7).", "format": "uuid" }, "tenantId": { "type": "string", "description": "Gets the tenant the record belongs to." }, "sessionId": { "type": "string", "description": "Gets the identifier of the run session. Microsoft Agent Framework\ngroups checkpoints under this value." }, "checkpointId": { "type": "string", "description": "Gets the checkpoint identifier. The value belongs to Tracon, not\nto Microsoft Agent Framework: `CreateAsync` generates it and\nhands it back to MAF." }, "parentCheckpointId": { "type": [ "null", "string" ], "description": "Gets the identifier of the previous checkpoint. `null` for the first checkpoint." }, "runId": { "type": [ "null", "string" ], "description": "Gets the identifier of the run that produced this checkpoint.\n`null` if no run was in progress when the checkpoint\nwas written.", "format": "uuid" }, "createdAt": { "type": "string", "description": "Gets the creation time (UTC).", "format": "date-time" }, "state": { "description": "Gets the opaque run state.", "$ref": "#/components/schemas/JsonElement" }, "stateSchemaVersion": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Gets the Tracon schema generation that wrote `State`.", "format": "int32" }, "stateMafVersion": { "type": [ "null", "string" ], "description": "Gets the Microsoft Agent Framework package version that produced\n`State`." } }, "description": "Represents a single checkpoint of a workflow run." }, "WorkflowDefinition": { "required": [ "name", "kind" ], "type": "object", "properties": { "name": { "type": "string", "description": "Gets the workflow's unique name. Serves as the key in the catalog and in API routes." }, "displayName": { "type": [ "null", "string" ], "description": "Gets the display name shown in the UI. `Name` is used if left empty." }, "description": { "type": [ "null", "string" ], "description": "Gets the short description of what the workflow does." }, "kind": { "description": "Gets the built-in pattern to use.", "$ref": "#/components/schemas/WorkflowKind" }, "agentNames": { "type": "array", "items": { "type": "string" }, "description": "Gets the agent names to enter the graph. Order is meaningful for\nWorkflowKind.Sequential; for other kinds it defines the\nparticipant set." }, "managerAgentName": { "type": [ "null", "string" ], "description": "Gets the manager agent's name. Required for\nWorkflowKind.Magentic, unused in other patterns." }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowNodeReference" }, "description": "Gets the ordered node list for a WorkflowKind.Sequential\nworkflow that mixes agent and function nodes." }, "maxIterations": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Gets the maximum number of turns. The only guard against an infinite\nloop in the WorkflowKind.GroupChat,\nWorkflowKind.Handoff, and WorkflowKind.Magentic\npatterns.", "format": "int32" }, "handoffInstructions": { "type": [ "null", "string" ], "description": "Gets the extra instruction that tells the model how to decide on a\nhandoff. Used only for WorkflowKind.Handoff." }, "requirePlanApproval": { "type": "boolean", "description": "Gets whether the plan the manager agent builds must be approved by a\nhuman before execution starts. Applies only to\nWorkflowKind.Magentic." }, "tenantId": { "type": [ "null", "string" ], "description": "Gets the tenant the definition belongs to. `null` for workflows defined in code." }, "version": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Gets the definition version. Increments by one on every save.", "format": "int32" }, "updatedAt": { "type": [ "null", "string" ], "description": "Gets the last modification time (UTC).", "format": "date-time" } }, "description": "Represents the full definition of a workflow, whether defined through the\nUI or in code." }, "WorkflowDescriptor": { "required": [ "name", "origin" ], "type": "object", "properties": { "name": { "type": "string", "description": "Gets the workflow's unique name." }, "displayName": { "type": [ "null", "string" ], "description": "Gets the display name shown in the UI." }, "description": { "type": [ "null", "string" ], "description": "Gets the short description." }, "origin": { "description": "Gets the source of the definition.", "$ref": "#/components/schemas/AgentDefinitionOrigin" }, "kind": { "oneOf": [ { "type": "null" }, { "description": "Gets the built-in pattern. `null` for workflows\ndefined by a factory in code: a free-form graph does not correspond\nto a pattern.", "$ref": "#/components/schemas/WorkflowKind" } ] }, "agentNames": { "type": "array", "items": { "type": "string" }, "description": "Gets the agent names entering the graph. Can be empty for code-defined workflows." }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowNodeReference" }, "description": "Gets the mixed agent/function node list for a Sequential workflow that\nuses function nodes. Empty for every other definition." }, "version": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Gets the definition version. Always 1 for code-defined workflows.", "format": "int32" }, "updatedAt": { "type": [ "null", "string" ], "description": "Gets the last modification time (UTC).", "format": "date-time" } }, "description": "Represents a summary view of a workflow listed in the catalog." }, "WorkflowEdgeKind": { "enum": [ "Direct", "FanOut", "FanIn" ], "description": "Represents the kind of an edge." }, "WorkflowFunctionResponse": { "required": [ "name", "inputType", "outputType" ], "type": "object", "properties": { "name": { "type": "string", "description": "The function's unique name." }, "description": { "type": [ "null", "string" ], "description": "The short description of what the function does." }, "inputType": { "type": "string", "description": "The display name of the CLR type the function accepts." }, "outputType": { "type": "string", "description": "The display name of the CLR type the function returns." } }, "description": "Wire-safe view of a registered function node." }, "WorkflowGraph": { "required": [ "name", "startExecutorId", "mermaid" ], "type": "object", "properties": { "name": { "type": "string", "description": "Gets the name of the workflow the graph belongs to." }, "startExecutorId": { "type": "string", "description": "Gets the identifier of the node that receives the input message first." }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowGraphNode" }, "description": "Gets the nodes in the graph." }, "edges": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowGraphEdge" }, "description": "Gets the edges between nodes." }, "mermaid": { "type": "string", "description": "Gets the Mermaid text produced by Microsoft Agent Framework." } }, "description": "Represents a workflow's compiled graph: nodes, edges, and external\nrequest ports." }, "WorkflowGraphEdge": { "required": [ "from", "to", "kind" ], "type": "object", "properties": { "from": { "type": "string", "description": "Gets the source node's identifier." }, "to": { "type": "string", "description": "Gets the target node's identifier." }, "kind": { "description": "Gets the edge's kind.", "$ref": "#/components/schemas/WorkflowEdgeKind" } }, "description": "Represents the connection between two nodes." }, "WorkflowGraphNode": { "required": [ "id", "label", "kind" ], "type": "object", "properties": { "id": { "type": "string", "description": "Gets the executor identifier." }, "label": { "type": "string", "description": "Gets the short label shown in the UI." }, "kind": { "description": "Gets the node's role.", "$ref": "#/components/schemas/WorkflowNodeKind" }, "agentName": { "type": [ "null", "string" ], "description": "Gets the agent's name if the node represents an agent; otherwise\n`null`." }, "executorType": { "type": [ "null", "string" ], "description": "Gets the Microsoft Agent Framework executor type. For debugging." } }, "description": "Represents a node in the graph." }, "WorkflowKind": { "enum": [ "Sequential", "Concurrent", "Handoff", "GroupChat", "Magentic", null ] }, "WorkflowNodeKind": { "enum": [ "Unknown", "Agent", "Orchestration", "RequestPort", "Output", "Function" ], "description": "Represents the role of a graph node." }, "WorkflowNodeReference": { "required": [ "name", "kind" ], "type": "object", "properties": { "name": { "type": "string", "description": "Gets the referenced name: an agent name from the catalog when\nWorkflowNodeKind WorkflowNodeReference.Kind is WorkflowNodeKind.Agent, or a\nfunction name from the code registry when it is\nWorkflowNodeKind.Function." }, "kind": { "description": "Gets which registry `Name` is looked up in.", "$ref": "#/components/schemas/WorkflowNodeKind" } }, "description": "Points to a single node entering a workflow's graph: an agent from the\ncatalog, or a function registered in code." }, "WorkflowPendingRequest": { "required": [ "runId", "requestId", "portId", "form" ], "type": "object", "properties": { "runId": { "type": "string", "description": "Gets the identifier of the run that produced the request.", "format": "uuid" }, "requestId": { "type": "string", "description": "Gets the request identifier. Send this value when responding; the\nresumed execution matches it to the request published with the same id." }, "portId": { "type": "string", "description": "Gets the identifier of the port that published the request. It maps to a graph node." }, "requestType": { "type": [ "null", "string" ], "description": "Gets the request data type name." }, "responseType": { "type": [ "null", "string" ], "description": "Gets the expected response type name." }, "prompt": { "type": [ "null", "string" ], "description": "Gets the request text shown to the user. For plan approval, this is the plan itself." }, "form": { "description": "Gets the input field the UI should display.", "$ref": "#/components/schemas/WorkflowRequestForm" }, "requestedAt": { "type": "string", "description": "Gets the UTC time when the request was published.", "format": "date-time" } }, "description": "Represents human input awaited by a workflow run." }, "WorkflowRequestForm": { "enum": [ "Json", "Text", "Boolean", "PlanReview" ], "description": "Defines how the UI presents a pending request." }, "WorkflowRespondHttpRequest": { "required": [ "requestId" ], "type": "object", "properties": { "requestId": { "type": "string", "description": "Identifier of the request being answered." }, "approved": { "type": [ "null", "boolean" ], "description": "Yes/no response. In a plan approval, `true` approves\nthe plan; `false` sends it back with the correction in\nthe `Text` field." }, "text": { "type": [ "null", "string" ], "description": "Text response; in a plan approval this is the correction instruction." }, "data": { "oneOf": [ { "type": "null" }, { "description": "Free-form response body. Resolved against the port's response type.", "$ref": "#/components/schemas/JsonElement" } ] }, "checkpointId": { "type": [ "null", "string" ], "description": "Identifier of the checkpoint to resume. If left empty, the run's most\nrecent checkpoint is used." } }, "description": "Response to a pending human input request." }, "WorkflowResumeHttpRequest": { "type": "object", "properties": { "checkpointId": { "type": [ "null", "string" ], "description": "Identifier of the checkpoint to resume from. If left empty, the run's\nmost recent checkpoint is used." } }, "description": "Request to resume a workflow from a checkpoint." }, "WorkflowRunHttpRequest": { "type": "object", "properties": { "message": { "type": [ "null", "string" ], "description": "User message to feed into the graph." }, "sessionId": { "type": [ "null", "string" ], "description": "Identifier of the execution session. If left empty, one is generated.\nCheckpoints are grouped under this value." } }, "description": "Request to run a workflow." }, "WorkflowSaveRequest": { "type": "object", "properties": { "displayName": { "type": [ "null", "string" ], "description": "Name shown in the UI." }, "description": { "type": [ "null", "string" ], "description": "Short description of what the workflow does." }, "kind": { "description": "Built-in pattern to use.", "$ref": "#/components/schemas/WorkflowKind" }, "agentNames": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Names of agents to add to the graph." }, "nodes": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/WorkflowNodeReference" }, "description": "Ordered agent/function node list for a Sequential workflow that mixes\nfunction nodes in with agents. Mutually exclusive with\nIReadOnlyList<string>? WorkflowSaveRequest.AgentNames; leave both empty or set only one." }, "managerAgentName": { "type": [ "null", "string" ], "description": "Name of the manager agent. Only for WorkflowKind.Magentic." }, "maxIterations": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Maximum number of turns.", "format": "int32" }, "handoffInstructions": { "type": [ "null", "string" ], "description": "Handoff instructions. Only for WorkflowKind.Handoff." }, "requirePlanApproval": { "type": "boolean", "description": "Whether the manager agent's plan must be approved by a human. Only for\nWorkflowKind.Magentic." } }, "description": "Request to save a workflow definition." } }, "securitySchemes": { "bearer": { "type": "http", "description": "The token configured through TraconEndpointOptions, or an API key issued from /api/api-keys. The header is compared in constant time. When no token is configured the endpoints are reachable from loopback only, so an unauthenticated local run still works.", "scheme": "bearer" } } }, "security": [ { "bearer": [] } ], "tags": [ { "name": "Tracon" }, { "name": "Meta" }, { "name": "Agents" }, { "name": "Attachments" }, { "name": "Skills" }, { "name": "Governance" }, { "name": "Sessions" }, { "name": "Runs" }, { "name": "Workflows" }, { "name": "Scheduling" }, { "name": "Evals" }, { "name": "Experiments" }, { "name": "Webhooks" }, { "name": "ApiKeys" }, { "name": "TenantProviders" }, { "name": "Triggers" }, { "name": "Approvals" }, { "name": "Retention" }, { "name": "Knowledge" }, { "name": "Models" }, { "name": "Voice" }, { "name": "Images" }, { "name": "Diagnostics" }, { "name": "OpenAI" } ] }