openapi: 3.2.0 info: title: Agent Connect Protocol Stateless Runs API 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 description: 'A Run represents an execution of an agent. The output of a Run can be a final result or an interrupt. Result from a run can be retrieved by polling or by blocking and waiting for the result. See `Run` and `RunOutput` models below for more info.' tags: - name: Stateless Runs description: 'A Run represents an execution of an agent. The output of a Run can be a final result or an interrupt. Result from a run can be retrieved by polling or by blocking and waiting for the result. See `Run` and `RunOutput` models below for more info.' paths: /runs: post: tags: - Stateless Runs summary: Create a Background stateless Run description: Create a stateless run, return the run ID immediately. Don't wait for the final run output. operationId: create_stateless_run requestBody: content: application/json: schema: $ref: '#/components/schemas/RunCreateStateless' required: true callbacks: runstatuschange: '{$request.body#/webhook}': post: requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RunStateless' responses: '200': description: Your server returns this code if it accepts the callback responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/RunStateless' '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' /runs/search: post: tags: - Stateless Runs summary: Search Stateless Runs description: 'Search for stateless run. This endpoint also functions as the endpoint to list all stateless Runs.' operationId: search_stateless_runs requestBody: content: application/json: schema: $ref: '#/components/schemas/RunSearchRequest' required: true responses: '200': description: Success content: application/json: schema: items: $ref: '#/components/schemas/RunStateless' type: array title: Run Search Response '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /runs/stream: post: tags: - Stateless Runs summary: Create a stateless run and stream its output description: Create a stateless run and join its output stream. See 'GET /runs/{run_id}/stream' for details on the return values. operationId: create_and_stream_stateless_run_output requestBody: content: application/json: schema: $ref: '#/components/schemas/RunCreateStateless' 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' /runs/wait: post: tags: - Stateless Runs summary: Create a stateless run and wait for its output description: Create a stateless run and wait for its output. See 'GET /runs/{run_id}/wait' for details on the return values. operationId: create_and_wait_for_stateless_run_output requestBody: content: application/json: schema: $ref: '#/components/schemas/RunCreateStateless' required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/RunWaitResponseStateless' '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' /runs/{run_id}/wait: get: tags: - Stateless Runs summary: Blocks waiting for the result of the run. description: "Blocks waiting for the result of the run. The output can be:\n * an interrupt, this happens when the agent run status is `interrupted`\n * the final result of the run, this happens when the agent run status is `success`\n * an error, this happens when the agent run status is `error` or `timeout`\n\n\nThis call blocks until the output is available." operationId: wait_for_stateless_run_output parameters: - 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/RunWaitResponseStateless' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /runs/{run_id}: parameters: - 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: - Stateless Runs summary: Get Run description: Get a stateless run by ID. operationId: get_stateless_run responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/RunStateless' '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: - Stateless 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_stateless_run requestBody: content: application/json: schema: $ref: '#/components/schemas/ResumePayloadSchema' required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/RunStateless' '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: - Stateless Runs summary: Delete Stateless Run description: Delete a stateless run by ID. operationId: delete_stateless_run 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' /runs/{run_id}/stream: get: tags: - Stateless Runs summary: Stream output from Stateless Run description: Join the output stream of an existing run. This endpoint streams output in real-time from a run. Only output produced after this endpoint is called will be streamed. operationId: stream_stateless_run_output parameters: - 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: 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' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /runs/{run_id}/cancel: post: tags: - Stateless Runs summary: Cancel Stateless Run operationId: cancel_stateless_run parameters: - 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 - required: false schema: type: boolean title: Wait default: false name: wait in: query - description: Action to take when cancelling the run. Possible values are `interrupt` or `rollback`. `interrupt` will simply cancel the run. `rollback` will cancel the run and delete the run and associated checkpoints afterwards. required: false schema: type: string enum: - interrupt - rollback title: Action default: interrupt name: action in: query 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' components: schemas: ValueRunInterruptUpdate: title: Value Run Interrupt Update description: Partial result provided as value through streaming. type: object allOf: - $ref: '#/components/schemas/RunInterrupt' - type: object properties: run_id: type: string format: uuid title: Run Id description: The ID of the run. status: title: Run Status description: Status of the Run when this result was generated. This is particularly useful when this data structure is used for streaming results. As the server can indicate an interrupt or an error condition while streaming the result. $ref: '#/components/schemas/RunStatus' required: - run_id - status RunCreateStateless: allOf: - $ref: '#/components/schemas/RunCreate' - type: object properties: on_completion: type: string enum: - delete - keep title: On Completion description: Whether to delete or keep the thread created for a stateless run. Must be one of 'delete' or 'keep'. default: delete title: RunCreateStateless description: Payload for creating a stateless run. ErrorResponse: type: string title: ErrorResponse description: Error message returned from the server RunWaitResponseStateless: type: object properties: run: $ref: '#/components/schemas/RunStateless' title: Run description: The run information. output: $ref: '#/components/schemas/RunOutput' StreamingMode: type: string enum: - values - custom InputSchema: title: Input Schema description: The input of the agent. The schema is described in agent ACP descriptor under 'spec.input'. oneOf: - type: object description: 'This object contains an instance of an OpenAPI schema object, formatted as per the OpenAPI specs: https://spec.openapis.org/oas/v3.1.1.html#schema-object' - type: string description: String input to the agent. - type: integer description: Integer input to the agent. - type: number description: Number input to the agent. - type: boolean description: Boolean input to the agent. - type: array description: Array input to the agent. items: {} RunOutput: title: Run Output description: Output of a Run. Can be the final result or an interrupt. oneOf: - $ref: '#/components/schemas/RunResult' - $ref: '#/components/schemas/RunInterrupt' - $ref: '#/components/schemas/RunError' discriminator: propertyName: type mapping: result: '#/components/schemas/RunResult' interrupt: '#/components/schemas/RunInterrupt' error: '#/components/schemas/RunError' ResumePayloadSchema: title: Resume Payload Schema description: "This schema describes the resume payload after an interrupt. Actual schema describes a polimorphic object, which means a schema structured with `oneOf` and `discriminator`. The discriminator is the `interrupt_type`, while the schemas will be those defined in the agent spec under `interrupts`/`resume_payload` For example: oneOf:\n - $ref: '#/components/schemas/ApprovalResumePayload'\n - $ref: '#/components/schemas/QuestionResumePayload'\ndiscriminator:\n propertyName: interrupt_type\n mapping:\n approval: '#/components/schemas/ApprovalResumePayload'\n question: '#/components/schemas/QuestionResumePayload'" oneOf: - type: object description: 'This object contains an instance of an OpenAPI schema object, formatted as per the OpenAPI specs: https://spec.openapis.org/oas/v3.1.1.html#schema-object' - type: string description: String resume to the agent. - type: integer description: Integer resume to the agent. - type: number description: Number resume to the agent. - type: boolean description: Boolean resume to the agent. - type: array description: Array input to the agent. items: {} RunSearchRequest: properties: agent_id: type: string format: uuid title: Agent Id description: Matches all the Runs associated with the specified Agent ID. status: $ref: '#/components/schemas/RunStatus' title: Status description: Matches all the Runs associated with the specified status. One of 'pending', 'error', 'success', 'timeout', 'interrupted'. metadata: type: object title: Metadata Filter description: Matches all threads for which metadata has keys and values equal to those specified in this object. limit: type: integer title: Limit description: Maximum number to return. default: 10 minimum: 1 maximum: 1000 offset: type: integer title: Offset description: Offset to start from. default: 0 minimum: 0 type: object title: Run Search Request description: Payload for listing runs. RunInterrupt: title: Run Interrupt description: Interrupt occurred during a Run type: object properties: type: title: Output Type type: string enum: - interrupt interrupt: $ref: '#/components/schemas/InterruptPayloadSchema' required: - type - interrupt StreamUpdateSchema: type: object title: Stream Update Schema description: An update in the SSE event streaming where streaming mode is set to custom. The schema is described in agent ACP descriptor under 'spec.custom_streaming_update'. ValueRunResultUpdate: title: Value Run Result Update description: Partial result provided as value through streaming. type: object properties: type: title: Streaming Output Type type: string enum: - values run_id: type: string format: uuid title: Run Id description: The ID of the run. status: title: Run Status description: Status of the Run when this result was generated. This is particularly useful when this data structure is used for streaming results. As the server can indicate an interrupt or an error condition while streaming the result. $ref: '#/components/schemas/RunStatus' values: $ref: '#/components/schemas/OutputSchema' messages: type: array items: $ref: '#/components/schemas/Message' title: Messages description: Stream of messages returned by the run. required: - type - run_id - status - values RunError: title: Run Error description: Run terminated with an error type: object properties: type: title: Output Type type: string enum: - error run_id: type: string format: uuid title: Run Id description: The ID of the run. errcode: type: integer title: Error Code description: code of the error description: type: string title: Error Description description: description of the error required: - type - run_id - errcode - description ConfigSchema: title: Config description: The configuration for this agent. The schema is described in agent ACP descriptor under 'spec.config'. If missing, default values are used. oneOf: - type: object description: 'This object contains an instance of an OpenAPI schema object, formatted as per the OpenAPI specs: https://spec.openapis.org/oas/v3.1.1.html#schema-object' - type: string description: String config to the agent. - type: integer description: Integer config to the agent. - type: number description: Number config to the agent. - type: boolean description: Boolean config to the agent. - type: array description: Array input to the agent. items: {} InterruptPayloadSchema: title: Interrupt Payload description: "This schema describes the interrupt payload. Actual schema describes a polimorphic object, which means a schema structured with `oneOf` and `discriminator`. The discriminator is the `interrupt_type`, while the schemas will be the ones defined in the agent spec under `interrupts`/`interrupt_payload` For example: oneOf:\n - $ref: '#/components/schemas/ApprovalInterruptPayload'\n - $ref: '#/components/schemas/QuestionInterruptPayload'\ndiscriminator:\n propertyName: interruput_type\n mapping:\n approval: '#/components/schemas/ApprovalInterruptPayload'\n question: '#/components/schemas/QuestionInterruptPayload'" oneOf: - type: object description: 'This object contains an instance of an OpenAPI schema object, formatted as per the OpenAPI specs: https://spec.openapis.org/oas/v3.1.1.html#schema-object' - type: string description: String interrupt to the agent. - type: integer description: Integer interrupt to the agent. - type: number description: Number interrupt to the agent. - type: boolean description: Boolean interrupt to the agent. - type: array description: Array input to the agent. items: {} RunOutputStream: type: object title: Run Output Stream Event description: Server-sent event containing one agent output event. Actual event type is carried inside the data. properties: id: type: string description: Unique identifier of the event title: Event ID event: type: string enum: - agent_event description: Event type. This is the constant string `agent_event` to be compatible with SSE spec. The actual type differentiation is done in the event itself. data: title: Stream Event Payload description: A serialized JSON data structure carried in the SSE event data field. The event can carry either a full `ValueRunResultUpdate`, if streaming mode is `values` or an `CustomRunResultUpdate` if streaming mode is `custom` oneOf: - $ref: '#/components/schemas/ValueRunResultUpdate' - $ref: '#/components/schemas/CustomRunResultUpdate' - $ref: '#/components/schemas/ValueRunInterruptUpdate' - $ref: '#/components/schemas/ValueRunErrorUpdate' discriminator: propertyName: type mapping: values: '#/components/schemas/ValueRunResultUpdate' custom: '#/components/schemas/CustomRunResultUpdate' interrupt: '#/components/schemas/ValueRunInterruptUpdate' error: '#/components/schemas/ValueRunErrorUpdate' required: - id - event - data RunStateless: title: Agent Run Stateless description: Holds all the information of a stateless run allOf: - $ref: '#/components/schemas/Run' - type: object properties: creation: $ref: '#/components/schemas/RunCreateStateless' title: Creation description: '' required: - creation RunCreate: properties: agent_id: type: string title: Agent Id description: The agent ID to run. If not provided will use the default agent for this service. input: $ref: '#/components/schemas/InputSchema' metadata: type: object title: Metadata description: Metadata to assign to the run. config: properties: tags: items: type: string type: array title: Tags recursion_limit: type: integer title: Recursion Limit configurable: $ref: '#/components/schemas/ConfigSchema' type: object title: Config description: The configuration for the agent. webhook: type: string format: uri maxLength: 65536 minLength: 1 title: Status change webhook description: Webhook to call upon change of run status. This is a url that accepts a POST containing the `Run` object as body. See Callbacks definition. stream_mode: anyOf: - items: $ref: '#/components/schemas/StreamingMode' type: array - $ref: '#/components/schemas/StreamingMode' - type: 'null' title: Stream Mode description: If populated, indicates that the client requests to stream results with the specified streaming mode(s). The requested streaming mode(s) must be one or more of those supported by the agent as declared in agent ACP descriptor under `specs.capabilities` default: null on_disconnect: type: string enum: - cancel - continue title: On Disconnect description: The disconnect mode to use. Must be one of 'cancel' or 'continue'. default: cancel multitask_strategy: type: string enum: - reject - rollback - interrupt - enqueue title: Multitask Strategy description: Multitask strategy to use. Must be one of 'reject', 'interrupt', 'rollback', or 'enqueue'. default: reject after_seconds: type: integer title: After Seconds description: The number of seconds to wait before starting the run. Use to schedule future runs. type: object required: [] title: RunCreateStateful description: Payload for creating a run. OutputSchema: title: Output Schema description: The output of the agent. The schema is described in agent ACP descriptor under 'spec.output'. oneOf: - type: object description: 'This object contains an instance of an OpenAPI schema object, formatted as per the OpenAPI specs: https://spec.openapis.org/oas/v3.1.1.html#schema-object' - type: string description: String output to the agent. - type: integer description: Integer output to the agent. - type: number description: Number output to the agent. - type: boolean description: Boolean output to the agent. - type: array description: Array input to the agent. items: {} RunResult: title: Run Result description: Final result of a Run. type: object properties: type: title: Output Type type: string enum: - result values: $ref: '#/components/schemas/OutputSchema' messages: type: array items: $ref: '#/components/schemas/Message' title: Messages description: The messages returned by the run. required: - type Message: type: object properties: role: type: string title: Role description: The role of the message. content: title: Content description: The content of the message. oneOf: - type: string - type: array items: anyOf: - type: object properties: text: type: string type: const: text metadata: type: object required: - text - type title: MessageTextBlock - type: object properties: type: type: string metadata: type: object required: - type title: MessageAnyBlock id: type: string title: Id description: The ID of the message. metadata: type: object title: Metadata description: The metadata of the message. required: - role - content Run: title: Agent Run description: Holds common information of a run properties: run_id: type: string format: uuid title: Run Id description: The ID of the run. thread_id: type: string format: uuid title: Agent ID description: Optional Thread ID wher the Run belongs to. This is populated only for runs on agents agents supporting Threads. agent_id: type: string format: uuid title: Agent Id description: The agent that was used for this run. created_at: type: string format: date-time title: Created At description: The time the run was created. updated_at: type: string format: date-time title: Updated At description: The last time the run was updated. status: $ref: '#/components/schemas/RunStatus' title: Status description: The status of the run. One of 'pending', 'error', 'success', 'timeout', 'interrupted'. required: - run_id - agent_id - created_at - updated_at - status CustomRunResultUpdate: title: Custom Run Result Update description: Object holding a custom defined update of the agent result during streaming. type: object properties: type: title: Streaming Output Type type: string enum: - custom run_id: type: string format: uuid title: Run Id description: The ID of the run. status: title: Run Status description: Status of the Run when this result was generated $ref: '#/components/schemas/RunStatus' update: $ref: '#/components/schemas/StreamUpdateSchema' required: - type - status - update RunStatus: type: string enum: - pending - error - success - timeout - interrupted ValueRunErrorUpdate: title: Value Run Error Update description: Partial result provided as value through streaming. type: object allOf: - $ref: '#/components/schemas/RunError' - type: object properties: status: title: Run Status description: Status of the Run when this result was generated. This is particularly useful when this data structure is used for streaming results. As the server can indicate an interrupt or an error condition while streaming the result. $ref: '#/components/schemas/RunStatus' required: - status