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-agents-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 Agents 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: Agents
paths:
  /agents:
    get:
      summary: List Agents
      description: 'Return a flat list of agent sessions for the web GUI grid.


        When ``TaskStore.agents`` is empty (e.g. only mock adapters spawned and

        they never heartbeat) we fall back to synthesising one entry per

        claimed/in-progress task, marked with ``"synthetic": true``. That keeps

        the GUI grid populated during demos and avoids the dreaded "0 sessions"

        empty state when work is obviously in flight.


        Both branches render the id and title of the task a session is on, so

        both narrow to the caller''s tenant scope: the live sessions carry no

        tenant of their own and are placed by the task they name, while the

        synthesised entries are built from a scoped read in the first place.'
      operationId: list_agents_agents_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  additionalProperties: true
                  type: object
                type: array
                title: Response List Agents Agents Get
      tags:
      - Agents
  /agents/{session_id}/logs:
    get:
      summary: Agent Logs
      description: 'Return log file content for a session.


        Args:

        session_id: Agent session ID.

        tail_bytes: If > 0, return only the last N bytes of the log.'
      operationId: agent_logs_agents__session_id__logs_get
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      - name: tail_bytes
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Tail Bytes
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentLogsResponse'
        '404':
          description: No log file for session
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Agents
  /agents/{session_id}/kill:
    post:
      summary: Agent Kill
      description: 'Request that an agent session be killed.


        Writes a ``.kill`` signal file that the orchestrator picks up on

        its next tick.'
      operationId: agent_kill_agents__session_id__kill_post
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentKillResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Agents
  /agents/{session_id}/stream:
    get:
      summary: Agent Stream
      description: SSE stream of live log output for a session.
      operationId: agent_stream_agents__session_id__stream_get
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      responses:
        '200':
          description: Server-Sent Events stream. The response body does not terminate.
          content:
            text/event-stream:
              schema:
                type: string
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Agents
  /agents/{agent_id}/heartbeat:
    post:
      summary: Agent Heartbeat
      description: Register an agent heartbeat.
      operationId: agent_heartbeat_agents__agent_id__heartbeat_post
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HeartbeatRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeartbeatResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Agents
  /api/v1/agents:
    get:
      summary: List Agents
      description: 'Return a flat list of agent sessions for the web GUI grid.


        When ``TaskStore.agents`` is empty (e.g. only mock adapters spawned and

        they never heartbeat) we fall back to synthesising one entry per

        claimed/in-progress task, marked with ``"synthetic": true``. That keeps

        the GUI grid populated during demos and avoids the dreaded "0 sessions"

        empty state when work is obviously in flight.


        Both branches render the id and title of the task a session is on, so

        both narrow to the caller''s tenant scope: the live sessions carry no

        tenant of their own and are placed by the task they name, while the

        synthesised entries are built from a scoped read in the first place.'
      operationId: list_agents_api_v1_agents_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  additionalProperties: true
                  type: object
                type: array
                title: Response List Agents Api V1 Agents Get
      tags:
      - Agents
  /api/v1/agents/{session_id}/logs:
    get:
      summary: Agent Logs
      description: 'Return log file content for a session.


        Args:

        session_id: Agent session ID.

        tail_bytes: If > 0, return only the last N bytes of the log.'
      operationId: agent_logs_api_v1_agents__session_id__logs_get
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      - name: tail_bytes
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Tail Bytes
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentLogsResponse'
        '404':
          description: No log file for session
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Agents
  /api/v1/agents/{session_id}/kill:
    post:
      summary: Agent Kill
      description: 'Request that an agent session be killed.


        Writes a ``.kill`` signal file that the orchestrator picks up on

        its next tick.'
      operationId: agent_kill_api_v1_agents__session_id__kill_post
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentKillResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Agents
  /api/v1/agents/{session_id}/stream:
    get:
      summary: Agent Stream
      description: SSE stream of live log output for a session.
      operationId: agent_stream_api_v1_agents__session_id__stream_get
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      responses:
        '200':
          description: Server-Sent Events stream. The response body does not terminate.
          content:
            text/event-stream:
              schema:
                type: string
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Agents
  /api/v1/agents/{agent_id}/heartbeat:
    post:
      summary: Agent Heartbeat
      description: Register an agent heartbeat.
      operationId: agent_heartbeat_api_v1_agents__agent_id__heartbeat_post
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HeartbeatRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeartbeatResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Agents
components:
  schemas:
    HeartbeatRequest:
      properties:
        role:
          type: string
          title: Role
          default: ''
        status:
          type: string
          enum:
          - starting
          - working
          - idle
          - dead
          title: Status
          default: working
      type: object
      title: HeartbeatRequest
      description: Body for POST /agents/{agent_id}/heartbeat.
    HeartbeatResponse:
      properties:
        agent_id:
          type: string
          title: Agent Id
        acknowledged:
          type: boolean
          title: Acknowledged
        server_ts:
          type: number
          title: Server Ts
      type: object
      required:
      - agent_id
      - acknowledged
      - server_ts
      title: HeartbeatResponse
      description: Response for heartbeat.
    AgentKillResponse:
      properties:
        session_id:
          type: string
          title: Session Id
        kill_requested:
          type: boolean
          title: Kill Requested
      type: object
      required:
      - session_id
      - kill_requested
      title: AgentKillResponse
      description: Response for POST /agents/{session_id}/kill.
    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
    AgentLogsResponse:
      properties:
        session_id:
          type: string
          title: Session Id
        content:
          type: string
          title: Content
        size:
          type: integer
          title: Size
      type: object
      required:
      - session_id
      - content
      - size
      title: AgentLogsResponse
      description: Response for GET /agents/{session_id}/logs.