A standard REST interface for invoking and configuring remote agents: agent discovery and descriptors, stateful threads, thread runs, and stateless runs, each with create / wait / stream / resume / cancel paths. OpenAPI 3.1.1, version 0.2.3, 30 operations. ACP is a specification every compliant agent server implements — it declares no servers[] and AGNTCY hosts no instance of it.
{
"openapi": "3.1.1",
"info": {
"title": "Agent Connect Protocol",
"version": "0.2.3",
"x-provenance": {
"method": "harvested",
"authored_by": "AGNTCY (Outshift by Cisco)",
"harvested_by": "API Evangelist",
"harvested_on": "2026-08-19",
"first_party": true,
"provider_published": true,
"source_host": "agntcy.org / outshift.com",
"note": "Four first-party machine-readable contracts: the Agent Connect Protocol OpenAPI 3.1.1, the OASF Schema API, and two AGNTCY Identity OpenAPI 3.0.3 documents. schema.oasf.outshift.com is the one genuinely callable AGNTCY-hosted API (unauthenticated, 200)."
},
"x-evidence": [
{
"type": "source",
"url": "https://spec.acp.agntcy.org/"
},
{
"type": "source",
"url": "https://schema.oasf.outshift.com/doc"
},
{
"type": "source",
"url": "https://identity-docs.outshift.com/api/openapi/service/v1alpha1/openapi.yaml"
}
]
},
"tags": [
{
"name": "Agents",
"description": "Agents are AI workflows that can be configured and/or executed on this server. This means that a client of this server can start a Run on any of the Agents supported by this server.\nEach agent may support different features of ACP, also each agent specifies the schemas of the objects carried by ACP for configuration, input, output, interrupts and state. \nDetails of the ACP features and the schemas are kept in the ACP descriptor of the specific agent. This object can be retrieved through this ACP interface or is found in the ACP extension of the agent record in the agent directory.\nSee `Agent` and `AgentACPDescriptor` models below for more info."
},
{
"name": "Threads",
"description": "If supported by the involved agents, Run can be grouped in Threads. \nWhen a run is executed on a thread is called Thread Run. At the end of a Thread Run, the server keeps a thread state associated to the thread.\nA thread keeps track of agent states at every step so that continuity of the context is preserved. Moreover, such a book-keeping enables us some granular controls like debugging, interrupting or replaying a run/invocation.\n\nA thread state is a data context defined by the developer and can be anything and it gets passed through from one invocation to another so that business logic is instrumented by data.\n\nA thread keeps track of the whole state history. At every step, it also applies a checkpoint, which is primarily a `uuid`, so that it is easier to refer to a chunk of the history.\n\nOne can easily query the last state, a specific state (by checkpoint id), the whole state history, or, a part of the history (from a checkpoint).\n\nSee `Thread`, `ThreadState` and `Checkpoint` models below for more info."
},
{
"name": "Thread Runs",
"description": "Thread Runs are runs created on a thread. \nA Thread Run can be created on a thread **only** if there is no run in the `pending` status on the same thread, i.e. if the thread is in the state `idle`\nNote that runs over the same thread can be executed on different agents, as long as the agents support the same thread state format.\nSee `Thread` and `RunCreateStateful` for more info."
},
{
"name": "Stateless Runs",
"description": "A Run represents an execution of an agent.\nThe output of a Run can be a final result or an interrupt.\nResult from a run can be retrieved by polling or by blocking and waiting for the result.\nSee `Run` and `RunOutput` models below for more info."
}
],
"paths": {
"/agents/search": {
"post": {
"tags": [
"Agents"
],
"summary": "Search Agents",
"description": "Returns a list of agents matching the criteria provided in the request.\n\nThis endpoint also functions as the endpoint to list all agents.",
"operationId": "search_agents",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentSearchRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/Agent"
},
"type": "array",
"title": "Matching Agent List"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/agents/{agent_id}": {
"get": {
"tags": [
"Agents"
],
"summary": "Get Agent",
"description": "Get an agent by ID.",
"operationId": "get_agent_by_id",
"parameters": [
{
"description": "The ID of the agent.",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Agent Id",
"description": "The ID of the agent."
},
"name": "agent_id",
"in": "path"
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Agent"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/agents/{agent_id}/descriptor": {
"get": {
"tags": [
"Agents"
],
"summary": "Get Agent ACP Descriptor from its id",
"description": "Get agent ACP descriptor by agent ID.",
"operationId": "get_acp_descriptor_by_id",
"parameters": [
{
"description": "The ID of the agent.",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Agent Id",
"description": "The ID of the agent."
},
"name": "agent_id",
"in": "path"
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentACPDescriptor"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/threads": {
"post": {
"tags": [
"Threads"
],
"summary": "Create an empty Thread",
"description": "Create a new thread. ",
"operationId": "create_thread",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ThreadCreate"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Thread"
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/threads/search": {
"post": {
"tags": [
"Threads"
],
"summary": "Search Threads",
"description": "Search for threads.\n\nThis endpoint also functions as the endpoint to list all threads.",
"operationId": "search_threads",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ThreadSearchRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/Thread"
},
"type": "array",
"title": "Response Search Agents Agents Search Post"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/threads/{thread_id}/history": {
"get": {
"tags": [
"Threads"
],
"summary": "Get Thread History",
"description": "Get all past states for a thread.",
"operationId": "get_thread_history",
"parameters": [
{
"description": "The ID of the thread.",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Thread Id",
"description": "The ID of the thread."
},
"name": "thread_id",
"in": "path"
},
{
"required": false,
"schema": {
"type": "integer",
"title": "Limit",
"default": 10
},
"name": "limit",
"in": "query"
},
{
"required": false,
"schema": {
"type": "string",
"title": "Before"
},
"name": "before",
"in": "query"
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/ThreadState"
},
"type": "array"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/threads/{thread_id}/copy": {
"post": {
"tags": [
"Threads"
],
"summary": "Copy Thread",
"description": "Create a new thread with a copy of the state and checkpoints from an existing thread.",
"operationId": "copy_thread",
"parameters": [
{
"description": "The ID of the thread.",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Thread Id",
"description": "The ID of the thread."
},
"name": "thread_id",
"in": "path"
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Thread"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/threads/{thread_id}": {
"parameters": [
{
"description": "The ID of the thread.",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Thread ID",
"description": "The ID of the thread."
},
"name": "thread_id",
"in": "path"
}
],
"get": {
"tags": [
"Threads"
],
"summary": "Get Thread",
"description": "Get a thread from its ID. ",
"operationId": "get_thread",
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Thread"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"delete": {
"tags": [
"Threads"
],
"summary": "Delete a thread. If the thread contains any pending run, deletion fails.",
"description": "Delete a thread.",
"operationId": "delete_thread",
"responses": {
"204": {
"description": "Success"
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"patch": {
"tags": [
"Threads"
],
"summary": "Patch Thread",
"description": "Update a thread.",
"operationId": "patch_thread",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ThreadPatch"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Thread"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/threads/{thread_id}/runs": {
"parameters": [
{
"description": "The ID of the thread.",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Thread ID",
"description": "The ID of the thread."
},
"name": "thread_id",
"in": "path"
}
],
"get": {
"tags": [
"Thread Runs"
],
"summary": "List Runs for a thread",
"description": "List runs for a thread.",
"operationId": "list_thread_runs",
"parameters": [
{
"required": false,
"schema": {
"type": "integer",
"title": "Limit",
"default": 10
},
"name": "limit",
"in": "query"
},
{
"required": false,
"schema": {
"type": "integer",
"title": "Offset",
"default": 0
},
"name": "offset",
"in": "query"
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/RunStateful"
},
"type": "array"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"post": {
"tags": [
"Thread Runs"
],
"summary": "Create a Background Run on a thread",
"description": "Create a run on a thread, return the run ID immediately. Don't wait for the final run output.",
"operationId": "create_thread_run",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunCreateStateful"
}
}
},
"required": true
},
"callbacks": {
"runstatuschange": {
"{$request.body#/webhook}": {
"post": {
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunStateful"
}
}
}
},
"responses": {
"200": {
"description": "Your server returns this code if it accepts the callback"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunStateful"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/threads/{thread_id}/runs/stream": {
"post": {
"tags": [
"Thread Runs"
],
"summary": "Create a run on a thread and stream its output",
"description": "Create a run on a thread and join its output stream. See 'GET /runs/{run_id}/stream' for details on the return values.",
"operationId": "create_and_stream_thread_run_output",
"parameters": [
{
"description": "The ID of the thread.",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Thread Id",
"description": "The ID of the thread."
},
"name": "thread_id",
"in": "path"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunCreateStateful"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Stream of agent results either as `ValueRunResultUpdate` objects or `CustomRunResultUpdate` objects, according to the specific streaming mode requested. Note that the stream of events is carried using the format specified in SSE spec `text/event-stream`",
"content": {
"text/event-stream": {
"schema": {
"$ref": "#/components/schemas/RunOutputStream"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/threads/{thread_id}/runs/wait": {
"post": {
"tags": [
"Thread Runs"
],
"summary": "Create a run on a thread and block waiting for the result of the run",
"description": "Create a run on a thread and block waiting for its output. See 'GET /runs/{run_id}/wait' for details on the return values.",
"operationId": "create_and_wait_for_thread_run_output",
"parameters": [
{
"description": "The ID of the thread.",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Thread Id",
"description": "The ID of the thread."
},
"name": "thread_id",
"in": "path"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunCreateStateful"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunWaitResponseStateful"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/threads/{thread_id}/runs/{run_id}/wait": {
"get": {
"tags": [
"Thread Runs"
],
"summary": "Blocks waiting for the result of the run.",
"description": "Blocks waiting for the result of the run. See 'GET /runs/{run_id}/wait' for details on the return values.",
"operationId": "wait_for_thread_run_output",
"parameters": [
{
"description": "The ID of the thread.",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Thread Id",
"description": "The ID of the thread."
},
"name": "thread_id",
"in": "path"
},
{
"description": "The ID of the run.",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Run Id",
"description": "The ID of the run."
},
"name": "run_id",
"in": "path"
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunWaitResponseStateful"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/threads/{thread_id}/runs/{run_id}": {
"parameters": [
{
"description": "The ID of the thread.",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Thread Id",
"description": "The ID of the thread."
},
"name": "thread_id",
"in": "path"
},
{
"description": "The ID of the run.",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Run Id",
"description": "The ID of the run."
},
"name": "run_id",
"in": "path"
}
],
"get": {
"tags": [
"Thread Runs"
],
"summary": "Get Run",
"description": "Get a run by ID.",
"operationId": "get_thread_run",
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunStateful"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"post": {
"tags": [
"Thread Runs"
],
"summary": "Resume an interrupted Run",
"description": "Provide the needed input to a run to resume its execution. Can only be called for runs that are in the interrupted state Schema of the provided input must match with the schema specified in the agent specs under interrupts for the interrupt type the agent generated for this specific interruption.",
"operationId": "resume_thread_run",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResumePayloadSchema"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunStateful"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"delete": {
"tags": [
"Thread Runs"
],
"summary": "Delete Run",
"description": "Delete a run by ID.",
"operationId": "delete_thread_run",
"responses": {
"204": {
"description": "Success"
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"descri
# --- truncated at 32 KB (103 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/agntcy/refs/heads/main/openapi/agntcy-acp-openapi.json