{"openapi":"3.1.0","info":{"title":"Decagon API","version":"1.0.0"},"paths":{"/v1/agent-versioning/versions":{"get":{"summary":"List Agent Versions","description":"List agent versions, newest first (created_at descending, then id descending). Supplying both `before` and `after` returns 422. A `before`/`after` id that is not an agent version in this team returns 404.","operationId":"list_agent_versions_v1_agent_versioning_versions_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of items to return, from 1 to 100; defaults to 100. A page may contain fewer items. Use has_more, not page length, to determine whether another page is available.","default":100,"title":"Limit"},"description":"Maximum number of items to return, from 1 to 100; defaults to 100. A page may contain fewer items. Use has_more, not page length, to determine whether another page is available."},{"name":"before","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"Return the nearest page strictly before this item ID in the endpoint's defined ordering, excluding the referenced item. Use the first returned item's ID to continue backward. Before and after are mutually exclusive; supplying both returns 422. IDs are opaque strings, not encoded cursors or lexical sort boundaries.","title":"Before"},"description":"Return the nearest page strictly before this item ID in the endpoint's defined ordering, excluding the referenced item. Use the first returned item's ID to continue backward. Before and after are mutually exclusive; supplying both returns 422. IDs are opaque strings, not encoded cursors or lexical sort boundaries."},{"name":"after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"Return the next page strictly after this item ID in the endpoint's defined ordering, excluding the referenced item. Use the last returned item's ID to continue forward. Before and after are mutually exclusive; supplying both returns 422. Omit both boundaries to request the first page.","title":"After"},"description":"Return the next page strictly after this item ID in the endpoint's defined ordering, excluding the referenced item. Use the last returned item's ID to continue forward. Before and after are mutually exclusive; supplying both returns 422. Omit both boundaries to request the first page."},{"name":"has_traffic","in":"query","required":false,"schema":{"type":"boolean","description":"When true, return only versions currently serving traffic (percent_traffic > 0). When false or omitted, return all non-archived agent versions.","default":false,"title":"Has Traffic"},"description":"When true, return only versions currently serving traffic (percent_traffic > 0). When false or omitted, return all non-archived agent versions."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentVersionListResponse"}}}},"4XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}},"description":"Client Error"},"5XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}},"description":"Server Error"}}},"post":{"summary":"Publish Agent Version","operationId":"publish_agent_version_v1_agent_versioning_versions_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":200,"pattern":"\\S"},{"type":"null"}],"description":"Unique key for this submission within the team. Reuse it only to retry the same request.","title":"Idempotency-Key"},"description":"Unique key for this submission within the team. Reuse it only to retry the same request."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentVersionPublishRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentVersionPublishResponse"}}}},"4XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}},"description":"Client Error"},"5XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}},"description":"Server Error"}}}},"/v1/agent-versioning/versions/traffic":{"post":{"summary":"Set Agent Version Traffic","operationId":"set_agent_version_traffic_v1_agent_versioning_versions_traffic_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":200,"pattern":"\\S"},{"type":"null"}],"description":"Unique key for this submission within the team. Reuse it only to retry the same request.","title":"Idempotency-Key"},"description":"Unique key for this submission within the team. Reuse it only to retry the same request."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentVersionTrafficRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentVersionTrafficResponse"}}}},"4XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}},"description":"Client Error"},"5XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}},"description":"Server Error"}}}},"/v1/simulations":{"get":{"summary":"List Simulations","description":"List saved simulations, newest first (created_at descending, then resource ID descending). Supplying both `before` and `after` returns 422. Missing or inaccessible pagination boundaries return 404.","operationId":"list_simulations_v1_simulations_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of items to return, from 1 to 100; defaults to 100. A page may contain fewer items. Use has_more, not page length, to determine whether another page is available.","default":100,"title":"Limit"},"description":"Maximum number of items to return, from 1 to 100; defaults to 100. A page may contain fewer items. Use has_more, not page length, to determine whether another page is available."},{"name":"before","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"Return the nearest page strictly before this item ID in the endpoint's defined ordering, excluding the referenced item. Use the first returned item's ID to continue backward. Before and after are mutually exclusive; supplying both returns 422. IDs are opaque strings, not encoded cursors or lexical sort boundaries.","title":"Before"},"description":"Return the nearest page strictly before this item ID in the endpoint's defined ordering, excluding the referenced item. Use the first returned item's ID to continue backward. Before and after are mutually exclusive; supplying both returns 422. IDs are opaque strings, not encoded cursors or lexical sort boundaries."},{"name":"after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"Return the next page strictly after this item ID in the endpoint's defined ordering, excluding the referenced item. Use the last returned item's ID to continue forward. Before and after are mutually exclusive; supplying both returns 422. Omit both boundaries to request the first page.","title":"After"},"description":"Return the next page strictly after this item ID in the endpoint's defined ordering, excluding the referenced item. Use the last returned item's ID to continue forward. Before and after are mutually exclusive; supplying both returns 422. Omit both boundaries to request the first page."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationListResponse"}}}},"4XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}},"description":"Client Error"},"5XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}},"description":"Server Error"}}}},"/v1/simulation/runs":{"post":{"summary":"Create Simulation Runs","description":"Create a batch of text-only runs for saved simulations. Retry with the same Idempotency-Key and request to avoid duplicate runs.","operationId":"create_simulation_runs_v1_simulation_runs_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"\\S","description":"Unique key for this submission within the team. Reuse it only to retry the same request.","title":"Idempotency-Key"},"description":"Unique key for this submission within the team. Reuse it only to retry the same request."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationRunCreateRequest"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationRunCreateResponse"}}}},"4XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}},"description":"Client Error"},"5XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}},"description":"Server Error"}}}},"/v1/simulation/runs/{id}":{"get":{"summary":"Get Simulation Run Batch","description":"Read the runs in a simulation batch with their lifecycle status and judge outcome.","operationId":"get_simulation_run_batch_v1_simulation_runs__id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","title":"Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationRunBatchObject"}}}},"4XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}},"description":"Client Error"},"5XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}},"description":"Server Error"}}}}},"components":{"schemas":{"AgentVersion":{"properties":{"id":{"type":"string","title":"Id","description":"Opaque identifier for the agent version."},"label":{"type":"string","title":"Label","description":"Version label, derived from the version sequence."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Commit message associated with the agent version."},"commit_sha":{"type":"string","title":"Commit Sha","description":"Git commit SHA the agent version was created from."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Time when the agent version was created."},"percent_traffic":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Percent Traffic","description":"Percentage of traffic assigned to this version."}},"type":"object","required":["id","label","description","commit_sha","created_at","percent_traffic"],"title":"AgentVersion"},"AgentVersionListResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/AgentVersion"},"type":"array","title":"Data","description":"Items in this page, in the endpoint's defined ordering for both forward and backward requests. Contains at most limit items; empty when no items match."},"has_more":{"type":"boolean","title":"Has More","description":"Whether more matching items exist beyond this page in the requested direction: after the last item for forward or initial requests, before the first item for before requests. False for an empty or final page. Keep the same filters and ordering when requesting another page.","default":false}},"type":"object","title":"AgentVersionListResponse"},"AgentVersionPublishRequest":{"properties":{"staging_commit_sha":{"type":"string","pattern":"^[0-9a-f]{40}$","title":"Staging Commit Sha","description":"40-character lowercase hexadecimal Git SHA of the staging main branch version to publish."},"description":{"type":"string","maxLength":1000,"minLength":1,"title":"Description","description":"Commit message for this publish (maximum 1000 characters)."}},"additionalProperties":false,"type":"object","required":["staging_commit_sha","description"],"title":"AgentVersionPublishRequest"},"AgentVersionPublishResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Opaque identifier for the agent version."},"label":{"type":"string","title":"Label","description":"Version label, derived from the version sequence."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Commit message associated with the agent version."},"commit_sha":{"type":"string","title":"Commit Sha","description":"Git commit SHA the agent version was created from."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Time when the agent version was created."},"percent_traffic":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Percent Traffic","description":"Percentage of traffic assigned to this version."}},"type":"object","required":["id","label","description","commit_sha","created_at","percent_traffic"],"title":"AgentVersionPublishResponse"},"AgentVersionTraffic":{"properties":{"agent_version_id":{"type":"string","maxLength":100,"minLength":1,"title":"Agent Version Id","description":"Opaque agent version ID (maximum 100 characters)."},"percent_traffic":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Percent Traffic","description":"Percentage of traffic routed to this version."}},"additionalProperties":false,"type":"object","required":["agent_version_id","percent_traffic"],"title":"AgentVersionTraffic"},"AgentVersionTrafficRequest":{"properties":{"traffic_allocation":{"items":{"$ref":"#/components/schemas/AgentVersionTraffic"},"type":"array","maxItems":100,"minItems":1,"title":"Traffic Allocation","description":"Full traffic split; versions not listed go to 0%."}},"additionalProperties":false,"type":"object","required":["traffic_allocation"],"title":"AgentVersionTrafficRequest"},"AgentVersionTrafficResponse":{"properties":{"traffic_allocation":{"items":{"$ref":"#/components/schemas/AgentVersionTraffic"},"type":"array","title":"Traffic Allocation","description":"The applied traffic split."}},"type":"object","required":["traffic_allocation"],"title":"AgentVersionTrafficResponse"},"KnowledgeMode":{"type":"string","enum":["live","draft"],"title":"KnowledgeMode"},"PublicError":{"properties":{"code":{"type":"string","title":"Code"},"message":{"type":"string","title":"Message"}},"type":"object","required":["code","message"],"title":"PublicError"},"PublicErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/PublicError"}},"type":"object","required":["error"],"title":"PublicErrorResponse"},"SimulationListResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/SimulationObject"},"type":"array","title":"Data","description":"Items in this page, in the endpoint's defined ordering for both forward and backward requests. Contains at most limit items; empty when no items match."},"has_more":{"type":"boolean","title":"Has More","description":"Whether more matching items exist beyond this page in the requested direction: after the last item for forward or initial requests, before the first item for before requests. False for an empty or final page. Keep the same filters and ordering when requesting another page.","default":false}},"type":"object","title":"SimulationListResponse"},"SimulationObject":{"properties":{"id":{"type":"string","title":"Id","description":"Stable, opaque simulation resource ID, including its prefix. Use this value for before/after pagination."},"name":{"type":"string","title":"Name","description":"Display name of the saved simulation, from its spec title. Names are not necessarily unique."}},"type":"object","required":["id","name"],"title":"SimulationObject"},"SimulationRunBatchObject":{"properties":{"id":{"type":"string","title":"Id","description":"Opaque simulation batch ID."},"runs":{"items":{"$ref":"#/components/schemas/SimulationRunObject"},"type":"array","title":"Runs","description":"Runs in this batch with their current execution status and outcome."}},"type":"object","required":["id","runs"],"title":"SimulationRunBatchObject"},"SimulationRunCreateRequest":{"properties":{"simulation_ids":{"items":{"type":"string","minLength":1,"pattern":"\\S"},"type":"array","maxItems":5,"minItems":1,"title":"Simulation Ids","description":"Saved simulation IDs to run. IDs must be unique."},"run_count":{"type":"integer","maximum":3.0,"minimum":1.0,"title":"Run Count","description":"Number of runs per simulation. Total runs equals len(simulation_ids) times run_count.","default":1},"branch":{"type":"string","minLength":1,"pattern":"\\S","title":"Branch","description":"Agent branch to run the simulation against. Defaults to main.","default":"main"},"knowledge_mode":{"anyOf":[{"$ref":"#/components/schemas/KnowledgeMode"},{"type":"null"}],"description":"Knowledge to use: live or draft. When omitted, defaults to draft if draft reads are enabled, otherwise live. Draft requests use live when draft reads are disabled."}},"additionalProperties":false,"type":"object","required":["simulation_ids"],"title":"SimulationRunCreateRequest"},"SimulationRunCreateResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Opaque batch ID. Use it to retrieve the batch's runs."}},"type":"object","required":["id"],"title":"SimulationRunCreateResponse"},"SimulationRunObject":{"properties":{"simulation_id":{"type":"string","title":"Simulation Id","description":"Saved simulation ID for this run."},"status":{"type":"string","enum":["queued","running","completed","error"],"title":"Status","description":"Run execution status: queued, running, completed, or error."},"outcome":{"anyOf":[{"type":"string","enum":["passed","failed","inconclusive"]},{"type":"null"}],"title":"Outcome","description":"Judge verdict for a completed run: passed, failed, or inconclusive when the simulation was invalid or could not be judged. Null while the run is queued or running, or when the run ended in an error before it could be judged."}},"type":"object","required":["simulation_id","status","outcome"],"title":"SimulationRunObject"}},"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}}},"servers":[{"url":"https://api.decagon.ai"}]}