Bernstein

Bernstein A2a API

The A2a API from Bernstein — 14 operation(s) for a2a.

Documentation GitHub OpenAPI

Operations 14

GET /a2a/agent-card Agent Card #

GET /a2a/agents List A2A Agents #

POST /a2a/message A2A Message #

POST /a2a/tasks/send A2A Send Task #

GET /a2a/tasks/{a2a_task_id} A2A Get Task #

POST /a2a/tasks/{a2a_task_id}/artifacts A2A Add Artifact #

POST /a2a/v0/tasks A2A V0 Accept Task #

GET /api/v1/a2a/agent-card Agent Card #

GET /api/v1/a2a/agents List A2A Agents #

POST /api/v1/a2a/message A2A Message #

POST /api/v1/a2a/tasks/send A2A Send Task #

GET /api/v1/a2a/tasks/{a2a_task_id} A2A Get Task #

POST /api/v1/a2a/tasks/{a2a_task_id}/artifacts A2A Add Artifact #

POST /api/v1/a2a/v0/tasks A2A V0 Accept Task #

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/bernstein-run:bernstein-run-a2a-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: Bernstein Task Server A2a API
  description: 'Bernstein REST API - the open-source governance layer for AI agents, one git worktree per task.


    ## Authentication


    Authentication is ENABLED by default. Include a Bearer token in all requests:


    ```

    Authorization: Bearer

    ```


    To run without auth (development only), set `BERNSTEIN_AUTH_DISABLED=1` - this logs a loud warning and passes every request through.


    Public endpoints (no auth required): `/health`, `/health/ready`, `/health/live`, `/ready`, `/alive`, `/.well-known/agent.json`, `/docs`, `/openapi.json`, and the auth-flow endpoints (`/auth/login`, `/auth/oidc/callback`, etc.).


    Webhook and hook endpoints (`/webhook`, `/webhooks/*`, `/hooks/{session_id}`) authenticate via HMAC-SHA256 signatures - they do NOT accept Bearer tokens.


    ## Base URL


    Default: `http://127.0.0.1:8052`. Override with env vars `BERNSTEIN_HOST` and `BERNSTEIN_PORT`.


    ## Error Format


    All errors return JSON with a `detail` field:


    ```json

    {"detail": "Task not found: task-xyz"}

    ```


    | Status | Meaning |

    |--------|---------|

    | 400 | Bad request (validation error) |

    | 401 | Unauthorized (missing/invalid token) |

    | 403 | Forbidden (IP not in allowlist) |

    | 404 | Resource not found |

    | 409 | Conflict (task already in terminal state) |

    | 429 | Rate limited - respect the `Retry-After` header |

    | 500 | Internal server error |'
  version: 3.22.0
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  contact:
    name: Alex Chernysh
    url: https://github.com/sipyourdrink-ltd/bernstein
servers:
- url: http://{host}:{port}
  description: Task server started by the Bernstein CLI on the operator's own machine. There is no hosted instance; substitute the host and port of your install.
  variables:
    host:
      default: 127.0.0.1
      description: Interface the task server binds to. Loopback by default.
    port:
      default: '8052'
      description: Task server port. Override with BERNSTEIN_PORT.
tags:
- name: A2a
paths:
  /a2a/agent-card:
    get:
      summary: Agent Card
      description: 'Publish the Bernstein orchestrator Agent Card (legacy A2A path).


        The richer service manifest at ``/.well-known/agent.json`` is served by

        ``routes.well_known``; this endpoint is preserved for callers that

        historically pulled the orchestrator''s own A2A card.'
      operationId: agent_card_a2a_agent_card_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/A2AAgentCardResponse'
      tags:
      - A2a
  /a2a/agents:
    get:
      summary: List A2A Agents
      description: Return Bernstein's A2A agent card via the task API namespace.
      operationId: list_a2a_agents_a2a_agents_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/A2AAgentCardResponse'
      tags:
      - A2a
  /a2a/message:
    post:
      summary: A2A Message
      description: Receive an inbound A2A message and inject it into the target task context.
      operationId: a2a_message_a2a_message_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/A2AMessageRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/A2AMessageResponse'
        '404':
          description: Task not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - A2a
  /a2a/tasks/send:
    post:
      summary: A2A Send Task
      description: 'Receive a task from an external A2A agent.


        Creates both an A2A task record and a corresponding Bernstein task,

        linking them together for lifecycle synchronisation.'
      operationId: a2a_send_task_a2a_tasks_send_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/A2ATaskSendRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/A2ATaskResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - A2a
  /a2a/tasks/{a2a_task_id}:
    get:
      summary: A2A Get Task
      description: Get an A2A task by ID, syncing status from the Bernstein task.
      operationId: a2a_get_task_a2a_tasks__a2a_task_id__get
      parameters:
      - name: a2a_task_id
        in: path
        required: true
        schema:
          type: string
          title: A2A Task Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/A2ATaskResponse'
        '404':
          description: A2A task not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - A2a
  /a2a/tasks/{a2a_task_id}/artifacts:
    post:
      summary: A2A Add Artifact
      description: Attach an artifact to an A2A task.
      operationId: a2a_add_artifact_a2a_tasks__a2a_task_id__artifacts_post
      parameters:
      - name: a2a_task_id
        in: path
        required: true
        schema:
          type: string
          title: A2A Task Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/A2AArtifactRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/A2AArtifactResponse'
        '404':
          description: A2A task not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - A2a
  /a2a/v0/tasks:
    post:
      summary: A2A V0 Accept Task
      description: 'Accept a federated task delegated from a peer orchestrator.


        Wire format::


        {

        "sender": { ...AgentCard... },

        "task": { "id": "...", "message": "...", "role": "..." }

        }


        Returns 202 with the local federated-task id and the remote task id

        that was offered. Validation errors return HTTP 409 so that the

        caller''s retry policy treats them as terminal (the peer is reachable

        and authoritative, no point retrying with the same body).'
      operationId: a2a_v0_accept_task_a2a_v0_tasks_post
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response A2A V0 Accept Task A2A V0 Tasks Post
        '400':
          description: Invalid sender Agent Card or task body
        '409':
          description: Task rejected (validation, capacity, etc.)
      tags:
      - A2a
  /api/v1/a2a/agent-card:
    get:
      summary: Agent Card
      description: 'Publish the Bernstein orchestrator Agent Card (legacy A2A path).


        The richer service manifest at ``/.well-known/agent.json`` is served by

        ``routes.well_known``; this endpoint is preserved for callers that

        historically pulled the orchestrator''s own A2A card.'
      operationId: agent_card_api_v1_a2a_agent_card_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/A2AAgentCardResponse'
      tags:
      - A2a
  /api/v1/a2a/agents:
    get:
      summary: List A2A Agents
      description: Return Bernstein's A2A agent card via the task API namespace.
      operationId: list_a2a_agents_api_v1_a2a_agents_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/A2AAgentCardResponse'
      tags:
      - A2a
  /api/v1/a2a/message:
    post:
      summary: A2A Message
      description: Receive an inbound A2A message and inject it into the target task context.
      operationId: a2a_message_api_v1_a2a_message_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/A2AMessageRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/A2AMessageResponse'
        '404':
          description: Task not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - A2a
  /api/v1/a2a/tasks/send:
    post:
      summary: A2A Send Task
      description: 'Receive a task from an external A2A agent.


        Creates both an A2A task record and a corresponding Bernstein task,

        linking them together for lifecycle synchronisation.'
      operationId: a2a_send_task_api_v1_a2a_tasks_send_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/A2ATaskSendRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/A2ATaskResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - A2a
  /api/v1/a2a/tasks/{a2a_task_id}:
    get:
      summary: A2A Get Task
      description: Get an A2A task by ID, syncing status from the Bernstein task.
      operationId: a2a_get_task_api_v1_a2a_tasks__a2a_task_id__get
      parameters:
      - name: a2a_task_id
        in: path
        required: true
        schema:
          type: string
          title: A2A Task Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/A2ATaskResponse'
        '404':
          description: A2A task not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - A2a
  /api/v1/a2a/tasks/{a2a_task_id}/artifacts:
    post:
      summary: A2A Add Artifact
      description: Attach an artifact to an A2A task.
      operationId: a2a_add_artifact_api_v1_a2a_tasks__a2a_task_id__artifacts_post
      parameters:
      - name: a2a_task_id
        in: path
        required: true
        schema:
          type: string
          title: A2A Task Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/A2AArtifactRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/A2AArtifactResponse'
        '404':
          description: A2A task not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - A2a
  /api/v1/a2a/v0/tasks:
    post:
      summary: A2A V0 Accept Task
      description: 'Accept a federated task delegated from a peer orchestrator.


        Wire format::


        {

        "sender": { ...AgentCard... },

        "task": { "id": "...", "message": "...", "role": "..." }

        }


        Returns 202 with the local federated-task id and the remote task id

        that was offered. Validation errors return HTTP 409 so that the

        caller''s retry policy treats them as terminal (the peer is reachable

        and authoritative, no point retrying with the same body).'
      operationId: a2a_v0_accept_task_api_v1_a2a_v0_tasks_post
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response A2A V0 Accept Task Api V1 A2A V0 Tasks Post
        '400':
          description: Invalid sender Agent Card or task body
        '409':
          description: Task rejected (validation, capacity, etc.)
      tags:
      - A2a
components:
  schemas:
    A2ATaskSendRequest:
      properties:
        sender:
          type: string
          title: Sender
        message:
          type: string
          title: Message
        role:
          type: string
          title: Role
          default: backend
      type: object
      required:
      - sender
      - message
      title: A2ATaskSendRequest
      description: Body for POST /a2a/tasks/send - receive a task from an external A2A agent.
    A2AMessageResponse:
      properties:
        id:
          type: string
          title: Id
        sender:
          type: string
          title: Sender
        recipient:
          type: string
          title: Recipient
        content:
          type: string
          title: Content
        task_id:
          type: string
          title: Task Id
        direction:
          type: string
          title: Direction
        delivered:
          type: boolean
          title: Delivered
        external_endpoint:
          anyOf:
          - type: string
          - type: 'null'
          title: External Endpoint
        created_at:
          type: number
          title: Created At
      type: object
      required:
      - id
      - sender
      - recipient
      - content
      - task_id
      - direction
      - delivered
      - external_endpoint
      - created_at
      title: A2AMessageResponse
      description: Serialized A2A message returned by Bernstein endpoints.
    A2AAgentCardResponse:
      properties:
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
        capabilities:
          items:
            type: string
          type: array
          title: Capabilities
        protocol_version:
          type: string
          title: Protocol Version
        endpoint:
          type: string
          title: Endpoint
        provider:
          type: string
          title: Provider
      type: object
      required:
      - name
      - description
      - capabilities
      - protocol_version
      - endpoint
      - provider
      title: A2AAgentCardResponse
      description: 'Agent Card response for the ``/a2a/agent-card`` discovery endpoint.


        The A2A v1.0 card served at ``/.well-known/agent.json`` is built and

        signed in :mod:`bernstein.core.routes.well_known` and does not use this

        model.'
    A2AMessageRequest:
      properties:
        sender:
          type: string
          title: Sender
        recipient:
          type: string
          title: Recipient
        content:
          type: string
          title: Content
        task_id:
          type: string
          title: Task Id
      type: object
      required:
      - sender
      - recipient
      - content
      - task_id
      title: A2AMessageRequest
      description: Body for POST /a2a/message.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    A2AArtifactRequest:
      properties:
        name:
          type: string
          title: Name
        data:
          type: string
          title: Data
          default: ''
        content_type:
          type: string
          title: Content Type
          default: text/plain
      type: object
      required:
      - name
      title: A2AArtifactRequest
      description: Body for POST /a2a/tasks/{id}/artifacts - attach an artifact.
    A2ATaskResponse:
      properties:
        id:
          type: string
          title: Id
        bernstein_task_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Bernstein Task Id
        sender:
          type: string
          title: Sender
        message:
          type: string
          title: Message
        status:
          type: string
          title: Status
        artifacts:
          items:
            $ref: '#/components/schemas/A2AArtifactResponse'
          type: array
          title: Artifacts
        created_at:
          type: number
          title: Created At
        updated_at:
          type: number
          title: Updated At
        receipt:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Receipt
      type: object
      required:
      - id
      - bernstein_task_id
      - sender
      - message
      - status
      - artifacts
      - created_at
      - updated_at
      title: A2ATaskResponse
      description: 'Serialised A2A task in responses.


        ``receipt`` carries the lineage receipt for an inbound task (#2609): the

        execution evidence a caller verifies offline with ``bernstein a2a verify

        --receipt``. It is ``None`` on read paths, and on write paths when the

        node could not provision receipt key material - an absent receipt means

        "unattested", which a caller should treat as unverified rather than

        trusted.'
    A2AArtifactResponse:
      properties:
        name:
          type: string
          title: Name
        content_type:
          type: string
          title: Content Type
        data:
          type: string
          title: Data
        created_at:
          type: number
          title: Created At
      type: object
      required:
      - name
      - content_type
      - data
      - created_at
      title: A2AArtifactResponse
      description: Single artifact in responses.