Capabilities & Artifacts#

Capabilities endpoints let clients discover the enabled Agent API surface for the authenticated agent. The Agent API also ships official generated artifacts, including the OpenAPI document and generated SDK, CLI, and MCP references.

Capabilities Endpoints#

text

example

GET /v1/agent/capabilities
GET /v1/agent/capabilities.json

Both routes return the same capability shape. Use JSON when a client expects an artifact-like URL.

Capabilities Response#

This example is abbreviated to one endpoint. The real endpoints array returns one entry per catalog method.

json

example

{
  "ok": true,
  "api_version": "1.0",
  "agent_api_contract_version": "1.0.0",
  "base_path": "/v1/agent",
  "endpoints": [
    {
      "method": "POST",
      "path": "/v1/agent/conversions/quote",
      "description": "Create a stateful conversion quote.",
      "rate_limit_class": "simulate",
      "idempotency_required": true,
      "request_schema": "agentApiConversionQuoteRequest",
      "response_schema": "agentApiConversionQuoteResponse"
    }
  ],
  "webhook_event_types": ["payment.executed"],
  "subscribable_webhook_event_types": ["payment.executed"],
  "operation_types": ["payment"]
}

Use Cases#

Use capabilities for:

feature detection
discovering the agent-specific enabled surface
reading idempotency metadata
reading rate-limit class metadata
detecting wrapper and version awareness through surrounding agent context
selecting only routes available under /v1/agent/*

The source catalog is the authority for v1 route exposure. If a generated capabilities artifact contradicts the source catalog, trust the source catalog and treat the artifact as stale until regenerated.

Notes#

The capability response intentionally includes both webhook_event_types and subscribable_webhook_event_types.

webhook_event_types is the full documented vocabulary.
subscribable_webhook_event_types is the subset accepted by webhook create and update routes.

Trusted-destination confirm, cancel, and remove routes are part of public v1 (scope agent:trusted_destinations:write); creating a brand-new trusted destination remains an app-only action.

Generated Tooling#

The Agent API ships an official TypeScript SDK, CLI, and MCP server; see Choose Your Surface for how these surfaces compare and what they share.

OpenAPI#

The Agent API OpenAPI document is served at:

text

example

GET /v1/agent/openapi.json

It is public and unauthenticated, and describes the /v1/agent/* surface. You can fetch it with any tool:

curl

request

curl -sS https://api.hightop.com/v1/agent/openapi.json

Or through the official tooling:

terminal

command

hightop openapi --pretty

typescript

example

const openapi = await new HightopAgentClient({ baseUrl: 'https://api.hightop.com' }).openapi.get()

Notes on the document#

Treat the /v1/agent/* catalog and the capabilities endpoints on this page as the authoritative v1 surface. Generated OpenAPI output may also include legacy agent-callable /actions/* and /info/* routes; those are not part of Agent API v1.
The document is regenerated from source schemas, so it always matches the live contract. If you generate your own client from it, regenerate when the contract version changes.