Credits

Credits are quota used by operations that retrieve or process valuable agent context. They let Epismo meter usage without changing the pack and track data model.

One credit is priced at $0.01. Checkout requires a minimum total purchase of 500 credits across all allocations.

Balance

Credit balance is resolved in the current personal or workspace context. In the API, use workspaceId when checking a workspace balance. In the CLI, the selected workspace or EPISMO_TOKEN determines the context.

epismo credit balance

The API returns:

{
	"balance": 1200,
	"shortfall": 0
}

shortfall is non-zero when the current operation or plan needs more credits than the selected context has available.

Checkout

Checkout starts a purchase flow and returns a URL.

epismo credit checkout --allocations '[{"userId":"<user-id>","quantity":500}]'

API payload:

{
	"allocations": [{ "userId": "user-id", "quantity": 500 }]
}

In a workspace context, allocations are associated with that workspace. In personal space, they apply to the authenticated user context.

Each allocation needs a non-empty userId and a positive integer quantity. The total quantity across all allocations must be at least 500 credits.

What consumes credits

Credits are consumed by operations that run agents or retrieve valuable pack/search context for an agent or user.

When outline or metadata is enough, inspect search results or outlines before hydrating detail into an agent context. For large packs, prefer selective reads with blockIds / stepIds instead of immediately requesting full=true.

The implementation checks credit availability before credit-gated operations and consumes credit after a successful retrieval or successful agent usage. Post-read consumption is intentionally fail-open: if the content read succeeds but consumption fails, the response is still returned and the failure is logged server-side.

If there are not enough credits, credit-gated endpoints can return 402 Payment Required.

Operational guidance

• Check balance before batch jobs that perform many searches or detail gets.
• Check the selected workspace's credits before long-running agent workflows.
• Prefer outline and selective pack reads before full=true.
• Use workspace-scoped tokens in CI so credits are consumed from the intended workspace.