Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.roughy.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Quote → token → charge

Roughy uses a two-step pricing flow that guarantees the price you see at quote time is the price you pay:
  1. POST /api/v1/pipelines/estimate returns a price breakdown plus a signed pricing_token (HS256 JWT, 5-minute TTL). The token encodes your user ID, the total credits, and a hash of the pipeline shape.
  2. POST /api/v1/pipelines requires the token. The server re-verifies the signature and the shape hash, then reserves the quoted credits as a hold against your balance.
Clients can’t tamper with the price after the quote, and pricing logic changes don’t retroactively affect already-quoted runs.

​
Holds, commits, releases

A pipeline run touches the ledger at well-defined moments:
Entry typeWhen it’s written
HOLDAt pipeline create — reserves the quoted credits.
COMMITPer step, as the step completes — converts a portion of the hold into a charge.
RELEASEAt pipeline cancel or finish — releases any unused portion of the hold.
REFUNDManual operator action when a run is judged at fault.
TOPUPStripe checkout / portal credits land here.
EXPIRYTime-based expiry of stale entries.
ADJUSTMENTManual corrections.
Active holds for an in-flight pipeline are also surfaced on the pipeline itself: total_credits_reserved minus total_credits_consumed equals what’s still held.

​
Reading the ledger

  • GET /api/v1/credits/balance — current available balance, the total currently held, and a per-pipeline breakdown of those holds.
  • GET /api/v1/credits/history — paginated ledger of every entry, most recent first. limit + offset to page.

​
Topping up

Credit purchases go through Stripe — checkout sessions and customer-portal links are exposed via the billing endpoints in the API Reference. Successful payments land as TOPUP entries in the ledger.
  • Pipeline — every pipeline run touches the ledger.