API & integration

Every agent artifact — free included — requires an authenticated caller. Sign your machine in with the CLI device flow and the runtime sends a bearer token automatically, or pass Authorization: Bearer <jwt> yourself. A paid agent additionally requires a completed purchase; without it the manifest is never released.

Returns the agent's manifest (the recipe — system prompt and tools). This is what the @findagent/mcp runtime fetches to run an agent.

GET /api/v1/agents/{slug}/manifest
GET /api/v1/agents/{slug}/manifest?version={semver}

Authorization: Bearer <token>

• 401 if unauthenticated, 402 if the agent is paid and you aren't entitled, 404 for an unknown or unpublished agent.
• 429 if you exceed the endpoint's rate limit (a Retry-After header tells you when to retry).

Returns the install artifact for a target client — the same byte-identical files the web installer and CLI emit, so every install path stays in sync.

GET /api/v1/agents/{slug}/install-bundle?llm={target}

Authorization: Bearer <token>

The response carries the agent identity, its license state, and a files[] array. The same auth and paid-entitlement rules as the manifest endpoint apply.

Returns a whole Department as a single bundle — the department manifest plus each member's resolved manifest. This is what the CLI findagent download <department> fetches so the runtime can run the team as one MCP server.

GET /api/v1/departments/{slug}/bundle

Authorization: Bearer <token>

• Authenticated callers only (the bundle carries member manifests) — 401 without a session or valid bearer.
• A paid member you aren't entitled to comes back with license_required and a null manifest — never leaked. 404 for an unknown or inaccessible department.
• 429 if you exceed the rate limit (with a Retry-After header).

A public, unauthenticated search over published agents — the same endpoint that backs the ⌘K command palette. Only status = published rows are ever returned.

GET /api/search?q={term}&limit={n}

• q — the search term. A query shorter than 2 characters returns an empty array ([]) without a round-trip.
• limit — optional, clamped to 1–25 (defaults to 10). Returns a JSON array of agent-card shapes.
• 429 if you exceed the rate limit (with a Retry-After header).

The CLI authenticates with an OAuth 2.0 Device Authorization Grant (RFC 8628) so a headless machine never has to copy a token by hand. The two endpoints are:

POST /api/auth/device/code
  { "client_id": "findagent-cli", "scope": "<optional>" }
  -> { device_code, user_code, verification_uri, verification_uri_complete, expires_in, interval }

POST /api/auth/device/token
  { "client_id": "findagent-cli", "device_code": "<code>",
    "grant_type": "urn:ietf:params:oauth:grant-type:device_code" }
  -> 400 { "error": "authorization_pending" | "slow_down" }   (keep polling)
  -> 200 { access_token, refresh_token?, expires_in? }         (approved)

• code mints a short-lived user_code the user confirms at the /device page (the verification_uri).
• token is polled until approval, then returns a single-use token. A consumed, unknown, or expired device_code returns the generic expired_token; access_denied means the user declined.

Run it with findagent login — see the install guide.

Which agent kinds reach which clients. Recipe agents paste in everywhere; doer agents reach a client through MCP (locally via the runtime, or hosted as a remote connector).

• Manifest spec — the shape of the document these endpoints return.
• CLI reference — the tooling built on these endpoints.