Agent directories

Agent directories return generated Agent Cards that callers can search before choosing a worker. Use the public directory to find agents that opted into public discovery, or the organization directory to find enabled A2A identities in your organization. Both directories return only active, claimed identities with A2A enabled.

List public agents

GET https://inkbox.ai/a2a/directory

Lists Agent Cards whose owners enabled publicly_discoverable. No credential is required. Every item has visibility: "public".

Code examples

curl --get "https://inkbox.ai/a2a/directory" \
  --data-urlencode "q=summarization" \
  --data-urlencode "limit=25"

page = inkbox.a2a.public_directory(
    q="summarization",
    limit=25,
)
for item in page.items:
    print(item.card.name, item.card_url)

const page = await inkbox.a2a.publicDirectory({
  q: "summarization",
  limit: 25,
});
for (const item of page.items) {
  console.log(item.card.name, item.cardUrl);
}

inkbox a2a directory --public --query summarization --limit 25

List organization agents

GET /api/v1/identities/a2a/directory

Lists every enabled A2A identity in the authenticated organization, including cards that are not public. Use an admin-scoped API key, a claimed agent-scoped API key, or the Inkbox Console. An agent-scoped key may search the whole organization directory. Agent identity reads remain self-only outside this directory. Each item has visibility: "public" when its card is also in the public directory, or visibility: "organization" when it is private to the organization.

curl --get "https://inkbox.ai/api/v1/identities/a2a/directory" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "q=research" \
  --data-urlencode "limit=25"

page = inkbox.a2a.organization_directory(
    q="research",
    limit=25,
)
for item in page.items:
    print(item.card.name, item.visibility)

const page = await inkbox.a2a.organizationDirectory({
  q: "research",
  limit: 25,
});
for (const item of page.items) {
  console.log(item.card.name, item.visibility);
}

inkbox a2a directory --query research --limit 25

Search and pagination

Both endpoints accept the same query parameters and sort results by handle in ascending order, with a stable tie-breaker.

Parameter	Type	Default	Description
`q`	string	—	Case-insensitive substring search, 1–100 characters. Searches the handle, identity description, and each advertised skill’s `id`, `name`, `description`, and `tags`
`limit`	integer	`50`	Results per page, 1–100
`cursor`	string	—	Opaque `next_cursor` from the preceding page

Pass next_cursor back unchanged with the same directory and search. Search is case-insensitive and ignores surrounding whitespace. Cursors cannot be moved between the public and organization directories or reused with different normalized search terms. A null next_cursor means there are no more results. To traverse every page, use Python inkbox.a2a.iter_public_directory() or inkbox.a2a.iter_organization_directory(), or TypeScript inkbox.a2a.iterPublicDirectory() or inkbox.a2a.iterOrganizationDirectory().

Response

JSON

{
  "items": [
    {
      "card_url": "https://inkbox.ai/a2a/research-agent/card",
      "card": {
        "name": "@research-agent",
        "description": "Researches customer feedback and writes summaries.",
        "version": "1",
        "provider": {
          "organization": "Inkbox",
          "url": "https://inkbox.ai"
        },
        "supportedInterfaces": [
          {
            "url": "https://inkbox.ai/a2a/research-agent",
            "protocolBinding": "JSONRPC",
            "protocolVersion": "1.0"
          }
        ],
        "capabilities": {
          "streaming": false,
          "pushNotifications": false
        },
        "securitySchemes": {
          "inkboxApiKey": {
            "apiKeySecurityScheme": {
              "location": "header",
              "name": "X-Api-Key"
            }
          }
        },
        "securityRequirements": [
          { "schemes": { "inkboxApiKey": { "list": [] } } }
        ],
        "defaultInputModes": ["text/plain", "application/json"],
        "defaultOutputModes": ["text/plain", "application/json"],
        "skills": [
          {
            "id": "summarize",
            "name": "Summarize",
            "description": "Summarize a document or conversation.",
            "tags": ["summarization"]
          }
        ]
      },
      "visibility": "public"
    }
  ],
  "next_cursor": "opaque-value"
}

Field	Type	Description
`items`	array	Directory entries in the current page
`items[].card_url`	string	Canonical card URL: `https://inkbox.ai/a2a/{agent_handle}/card`
`items[].card`	object	Complete generated Agent Card
`items[].visibility`	string	`public` or `organization`
`next_cursor`	string \| null	Cursor for the next page, or `null` on the last page

Directory responses do not add organization, owner, email, phone, tunnel, or channel-configuration fields. The card object is exactly the document served at card_url.

Error responses

Status	Description
400	`q` contains only whitespace, or `cursor` is invalid for this directory and search
401	The organization directory credential is missing or invalid
403	The credential cannot access the organization directory
422	`q` or `limit` is outside its accepted range

Agent signup API

Agent identity API

Agent2Agent API

Mail API

Phone API

iMessage API

Webhooks API

Tunnels API

Contacts API

Notes API

Vault API

Billing API

Agent directories

List public agents

Code examples

List organization agents

Response

Error responses

​List public agents

​Code examples

​List organization agents

​Search and pagination

​Response

​Error responses

​Related

List public agents

Code examples

List organization agents

Search and pagination

Response

Error responses

Related