Skip to main content
POST
Metered pay-per-use call

Authorizations

Authorization
string
header
required

Tenant secret key (lcr_…). Server-side only.

Headers

X-Locus-Max-Charge-Credits
string

Hosted wrapped APIs: hard per-call ceiling in tenant credits, including applicable markup. Rejected with 409 charge_ceiling_exceeded before reservation or upstream dispatch if exceeded. Applies to fal generation reservations. Not forwarded upstream.

Pattern: ^(?:0|[1-9]\d{0,24})(?:\.\d{1,6})?$
X-Locus-Session-Id
string

Required only when the end-user JWT carries sid. Send the original high-entropy session value; sid is its SHA-256 fingerprint. Ignored for secret-key authentication.

Required string length: 16 - 128
Pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]{15,127}$
Idempotency-Key
string
required

Required. Missing → 400. Same key + different body → 409. Retries replay the stored outcome for 24 hours after the call; after that the key is released and reusing it starts a new call.

Prefer
string

respond-async: answer 202 with the apiCallId once the provider request is sent, and finish the call in the background. Read the outcome from resultUrl (POST /wrapped/credits/calls/{callId}/result). Anything decided before dispatch (validation, balance, policy, a replay) answers as usual. Ignored when stream is true.

Example:

"respond-async"

X-Locus-End-User
string

Case-sensitive immutable ID in the tenant namespace. Prefer an identity-provider subject, not an email address.

Required string length: 1 - 200
Pattern: ^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,199}$

Path Parameters

provider
string
required
endpoint
string
required

Body

application/json

Upstream-shaped request body (see the per-endpoint docs at /credits/md)

Response

Raw upstream response. For fal/generate this acknowledges queue submission: credits remain reserved until a background reconciler confirms the result. Confirmed failures release the hold; successful results capture it. Read /wrapped/credits/calls/{callId} for settlement status.