[ REFERENCE ]

Capabilities API

apiv0.1.0sdk@assistiv/sdk@0.2.0

Browse the catalog, search for a provider, and run one. For concepts (how Capabilities are enabled, the two-level model, billing), see the Capabilities overview.

ℹBase URL & keys

All endpoints share https://api.assistiv.ai/v1. Browsing (GET) works with any authenticated key; search and run require an end-user key (sk-eu_*) with the inference scope.

GET/v1/capabilities

The catalog shelf: active capabilities with published-provider aggregates.

Auth: any authenticated key. Works even before Capabilities is enabled for the platform — enabled tells you whether a run would currently be allowed.

Each capability

Name	Type	Required	Description
slug	string	Optional	Stable category id, e.g. image-generation.
name	string	Optional	Human-readable shelf label.
description	string \| null	Optional	What the category does.
provider_count	integer	Optional	Published providers under this capability.
in_policy_count	integer	Optional	How many of those your policy currently allows.
min_price_usd	number \| null	Optional	Cheapest observed price across published providers.
minted_by	string	Optional	How the shelf was created: "seed" (curated) or "classifier".
domains	string[]	Optional	Agent use-case verticals (e.g. sales, marketing, personal) for filtering.

The top-level enabled boolean reflects whether the run path is live for your platform.

json

// GET /v1/capabilities
{
  "enabled": true,
  "capabilities": [
    {
      "slug": "image-generation",
      "name": "Image Generation",
      "description": "Generate images from a text prompt.",
      "provider_count": 12,
      "in_policy_count": 5,
      "min_price_usd": 0.004,
      "minted_by": "seed",
      "domains": ["personal", "marketing"]
    }
  ]
}

GET/v1/capabilities/{slug}

One capability's published providers, sorted and filtered, badged for the calling platform.

Auth: any authenticated key. 404 if the slug is unknown or inactive.

Query params (all optional)

Name	Type	Required	Description
sort	string	Optional	cost (cheapest first, default) or rating (best first).Default: `cost`
max_cost	number	Optional	Keep only providers whose observed min price is at or below this (USD). A display prefilter — the run re-quotes the binding price.
min_rating	number	Optional	Keep only providers rated at or above this (0–5). Excludes unrated providers.
verified_only	boolean	Optional	Keep only providers whose availability is healthy.Default: `false`
limit	integer	Optional	Cap the result. Omit to return all (server-capped). The agent's list_providers tool defaults this to 12.

Each provider

Name	Type	Required	Description
uid	string	Optional	Stable handle (cap_*) — pass this as capability to run.
slug	string \| null	Optional	Display name; may be null.
name	string \| null	Optional	Provider name.
description	string \| null	Optional	What the provider does.
url	string \| null	Optional	Upstream endpoint the call resolves to.
min_price_usd	number \| null	Optional	Cheapest observed price.
median_price_usd	number \| null	Optional	Median observed price.
max_price_usd	number \| null	Optional	Highest observed price.
rating	number \| null	Optional	0–5 stars; null when unrated.
availability	string	Optional	Upstream health: healthy \| unknown \| down.
last_synced_at	string \| null	Optional	ISO-8601 timestamp of the last catalog sync.
policy_state	string	Optional	in_policy \| denylisted \| not_allowlisted \| above_ceiling.
call_method	string \| null	Optional	How to call the provider: GET \| POST \| …
input_example	object \| null	Optional	A concrete example request body — the copy-and-tweak template for the run input.
input_schema	object \| null	Optional	The provider's body schema (field types), when published.

json

// GET /v1/capabilities/image-generation
{
  "slug": "image-generation",
  "name": "Image Generation",
  "description": "Generate images from a text prompt.",
  "enabled": true,
  "providers": [
    {
      "uid": "cap_abc123",
      "slug": "flux-fast",
      "name": "FLUX (fast)",
      "description": "Low-latency text-to-image.",
      "url": "https://gateway.example/image",
      "min_price_usd": 0.004,
      "median_price_usd": 0.008,
      "max_price_usd": 0.02,
      "rating": 4.7,
      "availability": "healthy",
      "last_synced_at": "2026-06-10T14:32:00Z",
      "policy_state": "in_policy",
      "call_method": "GET",
      "input_example": { "q": "Eiffel Tower, Paris", "limit": 3 },
      "input_schema": { "type": "object", "properties": { "q": { "type": "string"} } }
    }
  ]
}

POST/v1/capabilities/search

Freeform discovery of providers the platform's policy allows. No payment occurs.

Auth: end-user key (sk-eu_*) with the inference scope. 403 for a platform key or when Capabilities is not enabled.

Request Body

Name	Type	Required	Description
query	string	Required	Natural-language description of the action needed. 1–500 chars.
limit	integer	Optional	Max candidates to return, 1–25.Default: `8`

Every candidate is policy-filtered, so anything returned is runnable. Pass the candidate's uid to run.

bash

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 }'

json

{
  "candidates": [
    {
      "uid": "cap_abc123",
      "slug": "flux-fast",
      "name": "FLUX (fast)",
      "description": "Low-latency text-to-image.",
      "url": "https://gateway.example/image",
      "cost_usd": 0.01,
      "protocol": "x402",
      "rating": 4.7
    }
  ]
}

POST/v1/capabilities/run

Call one provider. Reserves a hold, pays, and debits the end user's budget. The money path.

Auth: end-user key (sk-eu_*) with the inference scope.

Request Body

Name	Type	Required	Description
capability	string	Required	The provider uid (cap_*) from search or browse. 1–200 chars.
input	object \| null	Optional	Request body forwarded to the provider (e.g. { prompt }). Shape is provider-specific.
max_pay	number	Optional	Per-call ceiling in USD. Only tightens the policy ceiling, never raises it. Must be > 0.

Response

Name	Type	Required	Description
capability	string	Optional	Capability slug that was run.
ok	boolean	Optional	The provider's own success flag.
final_state	string	Optional	released (no charge) \| billed \| failed.
status	integer \| null	Optional	The provider's HTTP status.
cost_usd	number \| null	Optional	Authoritative settled cost.
charged_end_user	boolean \| null	Optional	Whether the end user's budget was debited.
run_id	string \| null	Optional	Durable run id for your audit trail.
result	any	Optional	The provider's response body.

⚠Branch on final_state, not just ok

A settled-but-failed call may still be charged (a platform-policy choice, on by default). Treat billed as spent regardless of ok.

bash

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
  }'

json

{
  "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
  }
}

Agent tools (MCP)

When Capabilities is enabled, these four tools auto-register on the platform's per-user MCP URL (mcp.assistiv.ai/mcp) — an agent with the end user's sk-eu_* key discovers them automatically. Each wraps a REST endpoint above.

Tool	Args	Wraps
`list_capabilities`	—	`GET /v1/capabilities`
`list_providers`	capability, sort, max_cost, min_rating, verified_only, limit (default 12)	`GET /v1/capabilities/{slug}`
`capability_search`	query, limit	`POST /v1/capabilities/search`
`capability_run`	capability (uid), input, max_pay	`POST /v1/capabilities/run`

The plan → resolve → execute flow and the agent's how-to-call template (input_example) are in the Capabilities overview.

Status codes

Code	When
`200`	Success. For `run`, this includes settled-but-failed calls — inspect `final_state`.
`402`	Denied by policy (above ceiling / denylisted / not allowlisted) or balance (no budget, exhausted, wallet empty).
`403`	Capabilities not enabled for the platform, or a platform key used on `search`/`run`.
`404`	Unknown capability slug on `GET /v1/capabilities/{slug}`.