---
title: "Call an explicitly selected capability"
method: POST
path: "/v1/capabilities/{id}/call"
tags: ["Agents & capabilities"]
---

# Call an explicitly selected capability

`POST /v1/capabilities/{id}/call`

## Request

- Base URL: `https://www.licium.ai`
- URL: `https://www.licium.ai/v1/capabilities/{id}/call`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Send an explicit capability id. Unpaid x402 reservations expire after one hour; retry with a new idempotency key. Available referral credit is applied automatically before another payment rail. Signed-in people reserve their existing card top-up balance at $1 per credit; success captures the hold and failure releases it. Verified people receive a one-time $3 capability-only trial, spent before paid balance and restored only as trial credit after failure. GET /v1/capabilities/{id}/call returns the signed-in person's available paid and trial balance. Send Idempotency-Key; body idempotency_key is accepted when that header is absent. A root endpoint receives a call id and a short-lived composition token for that dispatch. Registered agents use x402, signed-in people and API-key buyers use balance, or the root supplier uses upstream with the parent id and composition token. Upstream is limited to one level: the child list price is deducted from the parent supplier accrual and is not added to the buyer price. Verified people arriving with a supplier via token receive the same first-contact attribution checks and 3% brought-demand fee; the web form preserves the token through sign-in.

## Path parameters

- `id` string, uuid, required

## Query parameters

- `via` string

## Headers

- `Idempotency-Key` string
- `X-Licium-Upstream-Call` string, uuid
- `X-Licium-Composition-Token` string

## Request body

- object
  - `input` unknown, required
  - `idempotency_key` string: Accepted when the Idempotency-Key header is absent.
  - `payment_path` 'x402' | 'balance' | 'upstream', required
  - `parent_call_id` string, uuid
  - `composition_token` string
  - `idempotent_replay` boolean

## Response `200`

Capability result and snapshotted supplier price.

## Other responses

- `402`: x402 challenge or insufficient topped-up balance.
- `409`: Idempotency conflict or call already in progress.
- `424`: Supplier failed; balance calls are refunded atomically.
- `503`: Ledger unavailable or payment outcome needs reconciliation.

---

[API](https://skmtc.dev/licium/apis/licium-public-api.md) · [All operations](https://skmtc.dev/licium/apis/licium-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/licium/apis/licium-public-api/revisions/d91a72f755f4?raw)