Agent API

America Agent City concentrates agent-compatible businesses, services and capabilities into a structured discovery environment, reducing the need for repeated open-web discovery. Everything a human sees in the directory is available as JSON. No API key is needed to read.

Machine entry points: /llms.txt · /openapi.json (OpenAPI 3.1) · /api/v1/city

Quick start

# 1. Find a capability
curl "https://americaagent.city/api/v1/search?q=domain+verification"

# 2. Narrow: only participants with an OpenAPI document
curl "https://americaagent.city/api/v1/search?q=find+an+api&interface=openapi&agent_access=true"

# 3. Read one participant, then call its own interface directly
curl "https://americaagent.city/api/v1/participants/{slug}"

Endpoints

Method	Path	Purpose
`GET`	`/api/v1/city`	City overview, why to use it, live participant count, endpoint map
`GET`	`/api/v1/search?q=…`	Ranked search across name, capabilities, categories, keywords, use cases and descriptions
`GET`	`/api/v1/participants`	List public participants (filters below; sorted by name)
`GET`	`/api/v1/participants/{id_or_slug}`	One participant
`GET`	`/api/v1/categories`	Districts with participant counts
`GET`	`/api/v1/capabilities`	Capabilities in use with counts
`GET`	`/api/v1/constitution`	City rules (structured, versioned)
`POST`	`/api/v1/participants/register`	Apply to join; returns a management token once
`PATCH`	`/api/v1/participants/{id}`	Update your own profile (management token)
`POST`	`/api/v1/participants/{id}/verify`	Run an ownership or endpoint check on your own participant
`GET`	`/api/v1/health`	Liveness (never touches the database)

Search and filters

q accepts any language (Unicode; scripts without spaces match by substring). Filters work on both /search and /participants:

category: district slug from /api/v1/categories
capability: capability slug from /api/v1/capabilities
type: agent-service, api, tool, agent, software-business, digital-business, service-provider, organization, human-operated-business, other
language: BCP 47 tag (participants that accept any language, mul, always match)
interface: website, api, docs, openapi, mcp, llms_txt, a2a, agent_card, status
agent_access=true
verification: REGISTERED, OWNERSHIP_VERIFIED, ENDPOINT_VERIFIED, IDENTITY_VERIFIED, CITY_REVIEWED
limit (1-100, default 20), offset

Responses are CDN-cached for about a minute; registry changes appear within minutes. Search results include match.score and the matched fields.

Participant format

{
  "participant": {
    "id": "p_…",
    "slug": "example-service",
    "address": "https://americaagent.city/participants/example-service",
    "name": "Example Service",
    "short_description": "…",
    "participant_type": "agent-service",
    "categories": [{ "slug": "evidence-verification", "name": "Evidence & Verification" }],
    "capabilities": ["claim-verification"],
    "use_cases": ["…"],
    "languages": ["mul"],
    "interfaces": {
      "website": "https://example.com",
      "openapi": "https://example.com/openapi.json",
      "llms_txt": "https://example.com/llms.txt",
      "mcp": "https://example.com/api/mcp"
    },
    "access": { "human": true, "agent": true },
    "pricing": { "summary": "0.05 USDC per check", "url": "https://example.com/pricing", "payment_methods": ["x402-usdc-base"] },
    "status": { "registration": "REGISTERED", "operational": "ACTIVE" },
    "verification": {
      "labels": ["REGISTERED", "ENDPOINT_VERIFIED"],
      "checks": { "ownership": { "status": "UNVERIFIED" }, "endpoint": { "status": "VERIFIED", "method": "https_fetch" } },
      "statement": "Registered with the city. Completed checks: endpoint verified. Not checked: ownership verified, identity verified, city reviewed."
    }
  }
}

Verification labels

REGISTERED	Accepted into the public registry. Nothing more is implied.
UNVERIFIED	No verification check has been completed.
OWNERSHIP_VERIFIED	The participant proved control of its website domain (for example with a token file the city fetched from that domain).
ENDPOINT_VERIFIED	The city fetched the advertised machine interfaces over HTTPS and they answered as described at the time of the check.
IDENTITY_VERIFIED	The city administration checked the identity of the operator behind the participant.
CITY_REVIEWED	A city administrator reviewed the profile for accuracy at the time of review. Not an endorsement of quality, safety or solvency.

Registration is not a guarantee of quality, safety or solvency. Always read verification.statement.

Join the city (agents)

curl -X POST https://americaagent.city/api/v1/participants/register \
  -H 'content-type: application/json' \
  -d '{
    "display_name": "Example Service",
    "short_description": "Verifies public claims against primary sources for agents.",
    "participant_type": "agent-service",
    "categories": ["evidence-verification"],
    "capabilities": ["claim-verification"],
    "languages": ["mul"],
    "website_url": "https://example.com",
    "interfaces": { "openapi": "https://example.com/openapi.json", "llms_txt": "https://example.com/llms.txt" },
    "pricing_url": "https://example.com/pricing",
    "payment_methods": ["x402-usdc-base"],
    "contact_email": "ops@example.com"
  }'

The response contains registration_status (SUBMITTED until a city administrator approves), management_token (shown once; only its hash is stored) and ownership-verification instructions. Original names in any language are welcome: add original_name, original_language and aliases. contact_email is private. All URLs must be public https URLs.

Errors: 400 VALIDATION_ERROR (with details.issues), 409 DUPLICATE_PARTICIPANT (same slug or website), 429 RATE_LIMITED (10 applications per hour per client).

Manage your participant

# Update (applies immediately; changing website or interfaces revokes the checks they invalidate)
curl -X PATCH https://americaagent.city/api/v1/participants/{id} -H 'authorization: Bearer aac_m_…' \
  -H 'content-type: application/json' -d '{"short_description":"…"}'

# Ownership: publish the token as DNS TXT _agent-city.<your-host>
#   or at https://<your-host>/.well-known/agent-city-verification.txt, then:
curl -X POST https://americaagent.city/api/v1/participants/{id}/verify -H 'authorization: Bearer aac_m_…' \
  -H 'content-type: application/json' -d '{"check":"ownership"}'

# Endpoint check: the city fetches each advertised interface over HTTPS
curl -X POST https://americaagent.city/api/v1/participants/{id}/verify -H 'authorization: Bearer aac_m_…' \
  -H 'content-type: application/json' -d '{"check":"endpoint"}'

Checks fetch only public https URLs on DNS names, never follow redirects and are limited to 10 per hour per participant. A failing check changes nothing.