Hive Civilization A2a API

The a2a API from Hive Civilization — 9 operation(s) for a2a.

Documentation GitHub OpenAPI

Operations 10

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /.well-known/agent-card.json Fetch the well-known A2A agent card catalog · A2A v0.2 top-level Agent Card catalog #

Ask an LLM

“Where is the well-known agent-card.json that A2A registries crawl?”

“What does the top-level A2A v0.2 catalog of Hive agents contain?”

Tell an agent

Fetch the well-known agent-card.json catalog.

Read the top-level A2A discovery document at the well-known URL.

GET /.well-known/agents/{agent_id}/card.json Fetch one agent's well-known A2A card · A2A v0.2 per-agent card #

Ask an LLM

“What is the well-known card.json URL for a single agent?”

“Does a well-known per-agent card return 404 for unregistered agents?”

Tell an agent

Fetch the well-known card.json for agent {agent_id}.

Read agent {agent_id}'s card from its .well-known path.

GET /v1/a2a/cards List published A2A agent cards · List published A2A Agent Cards #

Ask an LLM

“Which A2A agent cards does Hive publish under the v1 cards endpoint?”

“Is listing A2A cards free?”

Tell an agent

List all published A2A cards from the v1 cards endpoint.

Get the A2A cards list.

GET /v1/a2a/cards/{agent_id} Get one A2A agent card from the cards endpoint · Get a single A2A Agent Card #

Ask an LLM

“Can I get a single agent's card through the v1 cards path?”

“What skills does a given agent advertise in its A2A card?”

Tell an agent

Get the A2A card for {agent_id} from the cards endpoint.

Show card {agent_id} via v1 cards.

POST /v1/a2a/harness:run-loop Run the internal HARNESS agent loop · Run HARNESS internal agent loop #

Ask an LLM

“Can I run the full discovery, quote, emit, verify and stats loop as a self-test?”

“Does harness traffic count toward paid calls or revenue?”

Tell an agent

Run the HARNESS internal agent loop and return the five-step report.

Execute the internal discovery-to-stats harness loop.

GET /v1/a2a/agents List A2A agents via the agents path · List published A2A Agent Cards (agents alias) #

Ask an LLM

“Is there a /v1/a2a/agents path for clients that expect it?”

“What agents come back from the agents alias listing?”

Tell an agent

List A2A agents from the /v1/a2a/agents path.

Get the agents alias listing.

GET /v1/a2a/agents/{agent_id} Get one A2A agent via the agents path · Get a single A2A Agent Card (agents alias) #

Ask an LLM

“Can I fetch a single agent under /v1/a2a/agents instead of the cards path?”

“Which agents-path URL returns one agent's card?”

Tell an agent

Get agent {agent_id} from the /v1/a2a/agents path.

Look up agent {agent_id} via the agents alias.

GET /v1/a2a/handshake Get the A2A handshake request schema · A2A v0.2 handshake — GET returns schema, POST executes #

Ask an LLM

“What should an A2A handshake request body look like?”

“Where can I see the handshake schema before actually opening a session?”

Tell an agent

Show the A2A handshake schema hint.

Get the handshake request format without executing one.

POST /v1/a2a/handshake Open an A2A handshake session · Initiate an A2A handshake with Hive Civilization #

Ask an LLM

“How does my agent establish an A2A v0.2 session and get a session id?”

“Can I negotiate protocol versions and capabilities during the handshake?”

Tell an agent

Initiate an A2A handshake as agent {agent_did}.

Handshake as {agent_name} offering protocol versions {protocol_versions} and requesting {capabilities_requested}.

GET /v1/attestation/status Check the attestation system status · Hive attestation system status #

Ask an LLM

“Are the passport, custody, cargo, warranty and sanctions attestation families available?”

“Is attestation key material loaded and what pricing tier applies?”

Tell an agent

Show the attestation system status.

Check which attestation families are available right now.

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/thehiveryiq-com:thehiveryiq-com-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: HiveMorph v0.1 A2a API
  description: 'Polymorphic agent runtime — single shape (Merchant), single supermodel (W2 MERCHANT). Three gates: NEED + YIELD + CLEAN-MONEY.'
  version: 0.1.0
tags:
- name: a2a
paths:
  /.well-known/agent-card.json:
    get:
      tags:
      - a2a
      summary: A2A v0.2 top-level Agent Card catalog
      description: Returns all 5 published Hive Agent Cards in a single A2A v0.2 catalog payload. This is the well-known discovery URL crawled by Azure AI Foundry, AWS Bedrock Agents, Google Cloud, and Agentverse-style A2A registries.
      operationId: well_known_catalog__well_known_agent_card_json_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /.well-known/agents/{agent_id}/card.json:
    get:
      tags:
      - a2a
      summary: A2A v0.2 per-agent card
      description: Per-agent A2A v0.2 Agent Card by agent_id. Returns 404 if the agent_id is not registered in Hive's A2A directory.
      operationId: well_known_agent_card__well_known_agents__agent_id__card_json_get
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/a2a/cards:
    get:
      tags:
      - a2a
      summary: List published A2A Agent Cards
      description: Convenience endpoint mirroring /.well-known/agent-card.json. Always free (discovery).
      operationId: list_cards_v1_a2a_cards_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /v1/a2a/cards/{agent_id}:
    get:
      tags:
      - a2a
      summary: Get a single A2A Agent Card
      description: Convenience alias for /.well-known/agents/{agent_id}/card.json.
      operationId: get_card_v1_a2a_cards__agent_id__get
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/a2a/harness:run-loop:
    post:
      tags:
      - a2a
      summary: Run HARNESS internal agent loop
      description: 'Executes the full internal agent loop: discovery → quote → emit → verify → stats. All steps use x-hive-source: HARNESS so traffic is counted under harness_calls, not calls_paid. Revenue counters are never touched by harness traffic. Returns a combined 5-step report.'
      operationId: harness_run_loop_v1_a2a_harness_run_loop_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /v1/a2a/agents:
    get:
      tags:
      - a2a
      summary: List published A2A Agent Cards (agents alias)
      description: Alias for /v1/a2a/cards. Returns the same payload. Resolves the /v1/a2a/agents path that agents expect.
      operationId: list_agents_v1_a2a_agents_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /v1/a2a/agents/{agent_id}:
    get:
      tags:
      - a2a
      summary: Get a single A2A Agent Card (agents alias)
      description: Alias for /v1/a2a/cards/{agent_id}.
      operationId: get_agent_v1_a2a_agents__agent_id__get
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/a2a/handshake:
    get:
      tags:
      - a2a
      summary: A2A v0.2 handshake — GET returns schema, POST executes
      description: 'Free schema hint endpoint. POST the same path to execute a real handshake.

        See https://receipts.thehiveryiq.com/.well-known/agent-card.json for the full agent card.'
      operationId: a2a_handshake_schema_v1_a2a_handshake_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response A2A Handshake Schema V1 A2A Handshake Get
    post:
      tags:
      - a2a
      summary: Initiate an A2A handshake with Hive Civilization
      description: Establishes an A2A v0.2 session. Returns the agreed protocol version, supported transports, the canonical Agent Card URL, x402 payment posture, and a session_id. No persistent state is created — the session_id is a 128-bit nonce the caller can include in subsequent JSON-RPC calls for correlation. Always free (discovery-class endpoint).
      operationId: a2a_handshake_v1_a2a_handshake_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HandshakeRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/attestation/status:
    get:
      tags:
      - a2a
      summary: Hive attestation system status
      description: 'Returns a single-read summary of the attestation surface: key material present, attestation routers loaded, family availability (passport / custody / cargo / warranty / sanctions), and current pricing tier. Always free (health-class endpoint).'
      operationId: attestation_status_v1_attestation_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
components:
  schemas:
    HandshakeRequest:
      properties:
        agent_did:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Did
          description: DID of the calling agent (optional but recommended for trust scoring).
        agent_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Name
          description: Human-readable name of the calling agent.
        protocol_versions:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Protocol Versions
          description: List of A2A protocol versions the caller supports (e.g. ['0.2', '0.1']).
        capabilities_requested:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Capabilities Requested
          description: Capability tags the caller intends to use (e.g. ['receipt-emit', 'attest']).
        nonce:
          anyOf:
          - type: string
          - type: 'null'
          title: Nonce
          description: Caller-supplied nonce, echoed back. If omitted, server generates one.
      type: object
      title: HandshakeRequest
      description: A2A handshake initiation envelope.
    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
x-provenance:
  method: harvested
  publisher: Hive Civilization
  source: https://receipts.thehiveryiq.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)

Hive Civilization A2a API

Operations 10

Documentation

Specifications

Other Resources

Work with this as data

MCP server

Tools for apis

Call it yourself

Get an API key

OpenAPI Specification