AGNTCY

AGNTCY Threads API

If supported by the involved agents, Run can be grouped in Threads. When 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. A 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. A 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. A 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. One 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). See `Thread`, `ThreadState` and `Checkpoint` models below for more info.

Documentation GitHub OpenAPI

Operations 7

POST /threads Create an empty Thread #

POST /threads/search Search Threads #

GET /threads/{thread_id}/history Get Thread History #

POST /threads/{thread_id}/copy Copy Thread #

GET /threads/{thread_id} Get Thread #

DELETE /threads/{thread_id} Delete a thread. If the thread contains any pending run, deletion fails #

PATCH /threads/{thread_id} Patch Thread #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/agntcy-threads-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Agent Connect Protocol Threads 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: If supported by the involved agents, Run can be grouped in Threads.
tags:
- name: Threads
  description: If supported by the involved agents, Run can be grouped in Threads.
paths:
  /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.


        This 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'
components:
  schemas:
    ThreadPatch:
      properties:
        checkpoint:
          $ref: '#/components/schemas/ThreadCheckpoint'
          title: Checkpoint
          description: The identifier of the checkpoint to branch from. Ignored for metadata-only patches. If not provided, defaults to the latest checkpoint.
        metadata:
          type: object
          title: Metadata
          description: Metadata to merge with existing thread metadata.
        values:
          title: Values
          description: The current state of the thread.
          $ref: '#/components/schemas/ThreadStateSchema'
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
          title: Messages
          description: The current Messages of the thread. If messages are contained in Thread.values, implementations should remove them from values when returning messages. When this key isn't present it means the thread/agent doesn't support messages.
      type: object
      title: ThreadPatch
      description: Payload for updating a thread.
    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
    ThreadSearchRequest:
      properties:
        metadata:
          type: object
          title: Metadata Filter
          description: Matches all threads for which metadata has  keys and values equal to those specified in this object.
        values:
          type: object
          title: Values
          description: State values to filter on.
        status:
          $ref: '#/components/schemas/ThreadStatus'
        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: Thread Search Request
      description: Payload for listing threads.
    ThreadCheckpoint:
      properties:
        checkpoint_id:
          type: string
          format: uuid
          title: Checkpoint Id
          description: The ID of the checkpoint.
      type: object
      required:
      - checkpoint_id
      title: ThreadCheckpoint
      description: Structured identifier for a thread checkpoint, ie. an entry in the thread's history.
    ThreadCreate:
      type: object
      title: Thread
      description: Detail of an empty thread to be created.
      properties:
        thread_id:
          type: string
          format: uuid
          title: Thread Id
          description: The ID of the thread. If not provided, a random UUID will be generated.
        metadata:
          type: object
          title: Metadata
          description: Free form metadata for this thread
        if_exists:
          type: string
          enum:
          - raise
          - do_nothing
          title: If Exists
          description: How to handle duplicate creation. Must be either 'raise' (raise error if duplicate), or 'do_nothing' (return existing thread).
          default: raise
    ThreadState:
      properties:
        checkpoint:
          $ref: '#/components/schemas/ThreadCheckpoint'
          title: Checkpoint
          description: The identifier for this checkpoint.
        values:
          title: Values
          description: The current state of the thread.
          $ref: '#/components/schemas/ThreadStateSchema'
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
          title: Messages
          description: The current messages of the thread. If messages are contained in Thread.values, implementations should remove them from values when returning messages. When this key isn't present it means the thread/agent doesn't support messages.
        metadata:
          type: object
          title: Metadata
          description: The checkpoint metadata.
      type: object
      required:
      - checkpoint
      - values
      title: ThreadState
    ErrorResponse:
      type: string
      title: ErrorResponse
      description: Error message returned from the server
    Thread:
      type: object
      title: Thread
      description: Represents a collection of consecutive runs over a thread.  Thread is associated with a state. Runs for a thread can potentially happen across different agents, if the state format is compatible.
      properties:
        thread_id:
          type: string
          title: Thread ID
          description: unique identifier of a thread
        created_at:
          type: string
          format: date-time
          title: Created At
          description: The time the thread was created.
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: The last time the thread was updated.
        metadata:
          type: object
          title: Metadata
          description: Free form metadata for this thread
        status:
          type: string
          enum:
          - idle
          - busy
          - interrupted
          - error
          title: Status
          description: The status of the thread.
        values:
          title: Values
          description: The current state of the thread.
          $ref: '#/components/schemas/ThreadStateSchema'
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
          title: Messages
          description: The current Messages of the thread. If messages are contained in Thread.values, implementations should remove them from values when returning messages. When this key isn't present it means the thread/agent doesn't support messages.
      required:
      - thread_id
      - created_at
      - updated_at
      - metadata
      - status
    ThreadStatus:
      type: string
      enum:
      - idle
      - busy
      - interrupted
      - error
    ThreadStateSchema:
      title: Thread State Schema
      description: The thread state. The schema is described in agent ACP descriptor under 'spec.thread_state'.
      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 thread state to the agent.
      - type: integer
        description: Integer thread state to the agent.
      - type: number
        description: Number thread state to the agent.
      - type: boolean
        description: Boolean thread state to the agent.
      - type: array
        description: Array input to the agent.
        items: {}

AGNTCY Threads API

Operations 7

Documentation

Specifications

Schemas & Data

Other Resources