Capabilities

Two levels: capabilities and providers

The catalog is two layers deep, so an agent can reason about what it needs before it picks who runs it:

Turn it on for your end users

Once Assistiv has enabled Capabilities for your platform, rolling it out to an end user is two steps with your platform key: provision their sk-eu_* key, then give them a budget. A budget is required — a run with none returns 402.

import { Assistiv } from "@assistiv/sdk";

// Platform key — server-side setup only.
const assistiv = new Assistiv({
  apiKey: process.env.ASSISTIV_PLATFORM_KEY,
});

// 1. Give the end user a key.
const { id, api_key } = await assistiv.endUsers.create({
  external_id: "user-42",
});

// 2. Give them a budget (required before any run can be charged).
await assistiv.budgets.create(id, { max_usd: 5, period: "monthly" });

// Hand api_key.raw_key (an sk-eu_* key) to that user's agent —
// it makes the search/run calls. Never the platform key.

How an agent uses it (MCP tools)

When Capabilities is enabled, an agent connecting to its per-user MCP URL with the end user's sk-eu_* key gets four tools automatically — no wiring by the platform. It plans over the menu, resolves to a provider, then runs it:

// The agent's loop, in tool calls:
list_capabilities()
//   -> [ image-generation, legal-data, sports-data, identity-verification, ... ]

list_providers({ capability: "legal-data", sort: "rating", verified_only: true, limit: 5 })
//   -> [ { uid: "cap_abc", name: "...", min_price_usd: 0.004, rating: 4.7,
//          call_method: "GET", input_example: { query: "..." } }, ... ]

capability_run({ capability: "cap_abc",
                 input: { query: "CFAA court opinions" },  // shaped from input_example
                 max_pay: 0.02 })
//   -> { ok: true, final_state: "billed", cost_usd: 0.0095, result: { ... } }

The REST endpoints (what the tools wrap)

Platforms running their own agent loop can call these directly. They use the end user's sk-eu_* key (with the inference scope) — never the platform key. Search returns only providers your policy allows and costs nothing; run is the money path.

# 1. Find a provider (no spend).
curl -X POST https://api.assistiv.ai/v1/capabilities/search \
  -H "Authorization: Bearer sk-eu_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "query": "generate an image", "limit": 8 }'

# 2. Run it — pass the candidate's uid as "capability".
curl -X POST https://api.assistiv.ai/v1/capabilities/run \
  -H "Authorization: Bearer sk-eu_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "capability": "cap_abc123",
    "input": { "prompt": "a cat wearing sunglasses" },
    "max_pay": 0.02
  }'

// POST /v1/capabilities/run response
{
  "capability": "image-generation",
  "ok": true,
  "final_state": "billed",
  "status": 200,
  "cost_usd": 0.0095,
  "charged_end_user": true,
  "run_id": "b3f1c2a4-...-uuid",
  "result": {
    "image_url": "https://cdn.example/out.png",
    "width": 1024,
    "height": 1024
  }
}

Pricing & billing

• Calls are charged to the end user's USD budget. The per-call ceiling is your policy's max_cost_per_call_usd, optionally lowered (never raised) per call by max_pay.
• The run response is authoritative: cost_usd is the settled amount and charged_end_user tells you whether the budget moved.
• A settled-but-failed call may still be charged (a platform-policy choice, on by default). Branch on final_state, not just ok.
• End users read their remaining balance with GET /v1/me/budget.

Policy state & availability

Browse responses badge every provider with two orthogonal signals. Policy state is whether your policy lets it run; availabilityis the provider's upstream health. The same policy predicate drives both these badges and what search returns, so they can never disagree.

Full field-by-field shapes are in the Capabilities API reference.