Agent integration

AI agents are SkillCafe's primary customers. An agent can discover SkillCafe and register itself without a human-style form. Humans connect, authorise, fund and manage agents.

API version 2026-09-13 · Terms v0.1

1 · Machine discovery

A single public document lists the SkillCafe name, API version, registration endpoint, Barista and Café Library locations, current Terms version, authentication method and documentation location.

GET /api/public/skillcafe/discovery

2 · Self-registration

POST /api/public/agents/register
Content-Type: application/json

{
  "agent_name": "SalesAjen-02",
  "agent_type": "AUTONOMOUS_AGENT",
  "use_case": "Outbound campaign creative",
  "owner_reference": "acme-ops",
  "developer_reference": "acme-platform-team",
  "principal": { "name": "Acme Ltd", "type": "ORGANISATION" }
}

The response returns an Agent ID, agent code, Agent Passport, registration timestamp and a one-time Agent Token. New agents start as PROVISIONAL. Statuses: PROVISIONAL · ACTIVE · APPROVAL_REQUIRED · SUSPENDED. Registration is limited to 5 per hour per client.

3 · Agent Token

Tokens are generated server-side, stored only as a hash, shown once, and can be rotated or revoked. Send them as a bearer credential.

GET  /api/public/agents/me
POST /api/public/agents/token/rotate
POST /api/public/agents/token/revoke

Authorization: Bearer sc_agt_...

4 · Identity, principal and authority

Agent identity — the AI worker itself.
Principal / owner — the human or organisation responsible, where applicable.
Payment authority — a separate record for what the agent may spend.

A provisional passport can exist before any owner grants payment authority. Promotional starter credits are never issued on self-registration.

5 · Ask Barista by machine API

Integrate once, then your agent talks to SkillCafe on its own — no human needs to open the Barista page again. This is the same discovery and ranking engine that powers the human Barista page. Describe the need in plain language; the result comes back in the same request.

This separate paid Barista machine endpoint is not Remote MCP discovery. It currently costs 0.05 Café Credits when a match is returned.

POST /api/public/v1/barista/query
Authorization: Bearer sc_agt_...
Content-Type: application/json
Idempotency-Key: <your-unique-key>   # optional, replay-safe

{
  "need": "I need speech to text for call recordings",
  "category": "speech-to-text",                 # optional
  "max_service_fee": 0.10,                       # optional cap, server sets the fee
  "client_request_id": "job-8412",               # optional, also replay-safe
  "metadata": { "workflow": "call-summary" },     # optional
  "delivery_mode": "sync",                       # or "callback" with callback_url
  "callback_url": "https://your-agent.example.com/skillcafe/hook"
}

The response carries request_id, client_request_id, agent_id, status, recommended_capability and alternative_capabilities (provider, category, trust status, integration status, BYOK requirement, official documentation link, reason), service_fee, service_fee_charged and remaining_credit_balance. Unavailable metadata reads “Not yet available”; catalogued capabilities carry an explicit not-yet-verified notice.

Barista requests have their own rate-limit policy per Agent Passport tier, separate from the strict token-management limits: provisional 60/h · standard 600/h · high_volume 3000/h. The earlier path /api/public/agents/barista keeps working as an alias.

6 · Café Spend Pass

Every paid request is checked server-side: token validity, Agent Passport status, the owner-granted Café Spend Pass (per-charge, daily and monthly limits), owner Terms acceptance and the server-held Café Credit balance. The agent never sends an amount.

{ "status": "APPROVAL_REQUIRED", "message": "..." }   402
{ "status": "SUSPENDED" }                              403
{ "status": "LIMIT_EXCEEDED" }                         402
{ "status": "INSUFFICIENT_CREDITS" }                   402
{ "status": "UNAUTHORIZED" }                           401

Nothing is charged unless a Library match is returned. Successful charges append an immutable Café Credit ledger entry under Barista Service Fee, attributed to the Agent Passport.

7 · Callback / webhook

Immediate response is the Phase 1 default. Supply callback_url to also receive the completed result as a signed POST containing request_id, agent_id, status, result, credits charged and completion time. Verify it with HMAC-SHA256 over <timestamp>.<raw body>; the signing secret is shown once, on the first callback request.

x-skillcafe-request-id: <request id>
x-skillcafe-idempotency-key: <request id>
x-skillcafe-timestamp: <unix seconds>
x-skillcafe-signature: sha256=<hex hmac>

Callback URLs must be HTTPS and publicly routable — localhost, private ranges and internal hostnames are rejected. Delivery retries up to 3 times with backoff, redirects are not followed, and every attempt is logged with its status and timestamp. Secrets are never included in callback payloads, and no Agent Token is ever sent back. With "delivery_mode": "callback" (the older value "async" still works) the API acknowledges with a request id (HTTP 202, status accepted) and the result arrives only through the signed callback. Retries never charge the wallet a second time — the service fee follows the normal Barista charging rules once per request.

8 · Status / polling fallback

No callback URL? Read the result back with the request id. Only the agent that created the request can read it, using its own Agent Token. Statuses: accepted · processing · completed · no_match · failed. The response also reports delivery_mode, created and completed times, credits charged, and — for callback requests — callback_configured, callback_status, callback_attempts, callback_last_response_code and callback_last_attempt_at. No callback URL or secret is echoed back.

GET /api/public/v1/barista/requests/{request_id}
Authorization: Bearer sc_agt_...

9 · Live capability execution (BYOK)

Live execution is capability-driven: any Café Library listing that is Trust Gate approved, integrated, adapter-backed and priced can be executed through this one endpoint. Each capability carries its own Café Credit price, read server-side from its listing — a price sent by a caller is ignored. Where a capability is BYOK, the agent's owner stores their own provider API key in SkillCafe; it is held encrypted, used server-side only and never returned to a browser, an agent or a log, and the provider bills its usage directly to that owner. The capability fee is charged once per successful execution into the immutable ledger as SkillCafe Capability Fee. A failed provider response, a missing provider key or missing spending authority is never charged. Every other Café Library capability stays catalogued for discovery only.

POST /api/public/v1/capabilities/execute
Authorization: Bearer sc_agt_...
Content-Type: application/json

{
  "capability": "research-doi-lookup",
  "input": { "doi": "10.1038/nature12373" },
  "client_request_id": "job-8842",
  "delivery_mode": "sync",
  "max_results": 5
}

The response carries request_id, status, capability, provider, trust and integration status, the normalised output (answer plus title, url, snippet and relevance score per result), execution_ms, service_fee_charged, ledger_transaction_id and remaining_credit_balance. Machine errors: UNAUTHORIZED, SUSPENDED, APPROVAL_REQUIRED, INSUFFICIENT_CREDITS, LIMIT_EXCEEDED, PROVIDER_CREDENTIAL_REQUIRED, CAPABILITY_NOT_EXECUTABLE, PROVIDER_ERROR, RATE_LIMITED. Repeating the same client_request_id (or Idempotency-Key header) replays the stored result — never a second provider call and never a second charge. Callback mode reuses the same signed webhook delivery and retry rules; poll with the status endpoint if a callback fails.

GET /api/public/v1/capabilities/executions/{request_id}
Authorization: Bearer sc_agt_...

10 · Integration flow for a human developer

You integrate SkillCafe once. After that the agent handles discovery itself and you only return for owner-level decisions such as authorising spend.

developer integrates SkillCafe
  -> agent reads the discovery document
  -> agent self-registers
  -> agent receives its Agent Token
  -> owner links the agent and authorises spending (if required)
  -> agent calls the Barista API
  -> result returns immediately, or is pushed to the callback URL
  -> agent continues its own workflow

11 · Remote MCP

SkillCafe.ai exposes one Remote MCP server through the canonical URL below. New integrations must use the canonical URL. The legacy URL is DEPRECATED: it is kept temporarily for already-integrated clients and reaches the same server; it is not a second MCP service.

Remote MCP discovery tools are free. Capability execution is charged at the published Café Credit price of the selected Skill. The separate paid Barista machine endpoint is a different service and currently costs 0.05 Café Credits.

POST /mcp                 # canonical
POST /api/public/mcp       # DEPRECATED legacy compatibility only
Authorization: Bearer sc_agt_...
Content-Type: application/json

{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }

search_capability — Describe a capability need in plain language and receive the most relevant SkillCafe capabilities from the Café Library index. Public discovery: no Agent Token, no Café Credit charge and no model call. Pricing: FREE — 0 Café Credits.
resolve_capability — Read the agent-safe details of one capability: name, description, category, provider display name, Café Credit price, BYOK requirement, input and output schema, availability, trust status and documentation link. Provider implementation secrets are never returned. Remote MCP resolution is free and deducts 0 Café Credits. Pricing: FREE — 0 Café Credits.
get_quote — Return the Café Credit charge for a capability plus whether BYOK is required. With a valid Agent Token it also reports the owner wallet balance, whether spending authority is sufficient and what owner action is still required. The quote is free, deducts 0 Café Credits, never executes anything and never starts funding. Pricing: FREE — 0 Café Credits.
execute — Execute an approved capability through the existing SkillCafe execution path at the selected Skill's published Café Credit price: Agent Passport authentication, delegated authority, spending controls, Café Credit accounting, idempotency, execution records and provider routing. Without sufficient authority it returns a structured action-required response instead of executing. Pricing: Published Café Credit price of the selected Skill.
check_result — Read the state and result of an execution the authenticated agent created, with no additional discovery charge. Executions belonging to another agent are never returned. Pricing: No additional discovery charge.

A client that cannot set headers may pass agent_token as a tool argument instead. Tokens are validated server-side against the stored hash, respect rotation and revocation immediately, and are never returned in a tool result, a request-status response, a callback payload or a log.

New agents should search with task-aware search_capability through /mcp. The older skillcafe_search_capabilities tool (legacy endpoint only, DEPRECATED) calls the separate paid Barista machine service; it is not the free Remote MCP search_capability tool. It accepts delivery_mode: "sync" (default) or "callback" with an HTTPS callback_url, reusing the same signed callback delivery, retry and request-status tracking described above. Its charging is unchanged: the 0.05 Café Credit Barista Service Fee only, checked against passport status, payment authority, limits, Terms and the server-held balance. No authority → APPROVAL_REQUIRED with nothing charged; no match → nothing charged. An MCP client can read balances and limits but can never set a fee, alter a balance or grant itself spending authority.

# connect SkillCafe MCP to your own AI agent
{
  "mcpServers": {
    "skillcafe": {
              "url": "https://skillcafe.ai/mcp",
      "headers": { "Authorization": "Bearer sc_agt_..." }
    }
  }
}

12 · SkillCafe Sales Catalogue

A public, unauthenticated, machine-readable catalogue of what SkillCafe can sell. Each entry states what the capability does, the problems it solves, which agent types it suits, the SkillCafe fee in Café Credits, the provider billing rule, the requirements, trust and availability, and the exact steps from discovery to execution. Only listings with sales status active are returned, and a capability is only reported executable when SkillCafe genuinely executes it — marketing text can never override real trust, execution or payment state.

GET /api/public/v1/sales/catalog
GET /api/public/v1/sales/catalog?problem=I need current information from the web
GET /api/public/v1/sales/catalog?executable=true&byok_required=true
GET /api/public/v1/sales/catalog?category=Web%20Search&max_skillcafe_fee=0.25
GET /api/public/v1/sales/catalog/{capability_id}

Filtering is plain structured metadata matching over category, provider, tags, problems solved, use cases and machine benefits — no model call and no charge. Ranked recommendations remain a Barista request at the standard Barista Service Fee.

curl "https://skillcafe.ai/api/public/v1/sales/catalog?problem=current+web+information&executable=true"

# then evaluate one listing in full
curl "https://skillcafe.ai/api/public/v1/sales/catalog/tavily-search"

Every listing carries machine-actionable next steps in order: DISCOVER → EVALUATE → REGISTER/AUTHENTICATE → SATISFY REQUIREMENTS → EXECUTE. Where owner approval, payment authority, a BYOK provider credential or Café Credits are still missing, the catalogue reports the requirement rather than implying it can be bypassed. No credential, token or secret material appears anywhere in a catalogue response.

13 · Terms v0.1

GET /api/public/skillcafe/terms

An agent is not assumed to have authority to accept Terms for its owner. Where owner approval is required, the agent status becomes APPROVAL_REQUIRED.

SkillCafe is an aggregation, discovery, routing and service platform.
Third-party APIs and models are independently owned and operated by their providers.
SkillCafe screening does not guarantee future security, quality or availability.
Use of third-party APIs remains subject to each provider's own terms.
SkillCafe-owned capabilities are identified separately in the Café Library.
Café Credits are a closed-loop platform credit: not cash, not transferable, not redeemable for cash, and usable only for SkillCafe services.
Third-party API costs remain directly between you and the provider using your own provider credentials (BYOK).