Credits and billing
Credits and billing are managed at the workspace boundary.
Credits are the execution boundary for credit-bearing Dreamstate work. Use the fetched capability contract before a run because it supplies the capability’s cost policy, accepted mode, input shape, and whether a live request needs a ceiling.
A credit ceiling controls one execution request. It does not change a provider connection, a sender policy, or the workspace plan. For a specific request budget, read Spend caps and budgets. For changes to billing, membership, or API keys, read Owner actions.
Read the catalog credit class
The catalog contains three credit classes: free, action, and dynamic. A class describes the catalog category. It is not a promise that every capability in a broad subject area has the same price or execution rule.
Search for the outcome first, fetch the exact capability contract, then read its cost policy. This is important for an agent as well as a person: a capability id without its current contract does not provide an input schema, an estimate, or a permission to invent a price.
| Credit class | Meaning | How to use it |
|---|---|---|
free | A catalog credit class for work that does not consume credits. | Read the fetched contract before assuming a related action is free. |
action | A catalog credit class for a fixed action cost policy. | Use the contract and returned execution controls for the specific action. |
dynamic | A catalog credit class where the contract determines the cost policy. | Use the estimate and quote returned for the unchanged request. |
The available classes are deliberately a short list. Do not translate them into a made-up allowance, a per-seat balance, or a provider price. The capability contract and the returned estimate remain the source for the actual operation.
Get a quote before a priced live run
A live call that needs a price returns quote_required with an estimate. The caller then reruns the same call with unchanged parameters, the returned quote, and a max_credits ceiling. The server binds the quote to that rerun.
This sequence keeps discovery and execution separate. A search response tells you what a capability is. A fetched contract tells you the input and policy. A priced live request supplies the estimate path. Do not substitute another capability, alter the parameters, or assume that a prior estimate applies to a changed request.
Architect can use the same catalog path as the other doors. It should report the fetched contract and quote rather than state an unverified price. A person can then decide the ceiling to send in the execution envelope.
Keep credits in the execution envelope
The ceiling and quote sit beside params in the canonical run input. They are execution-envelope controls. A capability’s own fields stay inside params, exactly as the fetched schema describes them.
| Field | Type | When required | Meaning |
|---|---|---|---|
mode | Execution control | Required by a mutating call | Names the requested execution mode. The server does not default a mutation to live. |
max_credits | Nonnegative number | When the fetched contract says live needs a credit ceiling | A run-wide ceiling beside params, not a capability parameter. |
quote_hash | Quote value | For a priced live rerun after quote_required | The value minted by the prior dry run for the same unchanged request. |
params | Capability-specific object | As published by the fetched contract | The operation input. Do not move execution controls into this object. |
Keeping these values outside params lets a caller reuse a published capability schema without adding budget fields that the capability does not own. It also means a contract can state when a ceiling is required for a live call without changing the operation’s business inputs.
For the server, max_credits is an optional finite nonnegative number. A caller should still only send it when the fetched capability contract calls for a live credit ceiling. A number is not evidence that a capability is priced.
Workspace billing plans
Dreamstate lists Growth at $99 per month with a 3-day free trial. Pro is $249 per month. These are plan prices, not a statement of credit allowances, seats, provider usage, or a price for any individual catalog capability.
Billing checkout, seats, tier changes, cancellation, credit purchase, and overage affect the workspace’s money or access. They are root capabilities with the signed-in owner-session and fresh owner-action authorization rule. The rule is security for workspace ownership and billing changes, not a normal step for a priced run.
Do not try to perform a workspace billing change through a broad API key. Follow the owner-action route, retain its idempotency key for any retry, and inspect the resulting response before assuming the plan or billing state changed.
Separate cost from provider setup
A provider can need a connected workspace account, a workspace credential, or the customer’s own provider key. That readiness is owned by the integrations domain. It can block provider-backed execution, but it does not rewrite the cost policy in a capability contract.
A missing LinkedIn or email account can block running or sending a step without blocking the work of drafting a workbook, sequence, or workflow. Build the workspace system, confirm the provider readiness, then discover and run the exact capability that performs the provider-backed task.
When a live request returns an error, use its stable code and repair data. quote_required asks for the quote flow. credentials_required identifies missing provider credentials. They are different conditions and need different repairs.
When it goes wrong
If a priced live request returns quote_required, do not reinterpret it as a successful run. Preserve the intended capability and parameters, obtain the returned quote, set a ceiling, and rerun the unchanged request. If the request changed, start the quote flow again for the changed input.
If a provider says credentials_required, inspect the connection or credential state under integrations. Do not add a credential to a chat prompt or capability parameter. Connecting and disconnecting credentials are owner actions because they change who can reach an external system.
If you need to change the plan, checkout, seats, billing tier, cancellation, or credit purchase, do not present it as an ordinary credit run. Return to the signed-in workspace session and use the owner-action flow. For a request retry, preserve the idempotency key rather than starting a duplicate money or access change.
For every other refusal, inspect the envelope’s error code, message, details, and repair. The exact fetched contract is still the source of truth for whether the operation is available, which modes it accepts, and which execution controls it requires.