REST API
Use the REST API to search tools, read schemas, run tools, and inspect runs.
The Dreamstate REST API is at https://api.trydreamstate.com. Use it when your application needs direct HTTP access to the same capability discovery and execution contract used by Architect, the CLI, and MCP. It is not a list of stable business endpoints for each product feature. Search finds the current capability, get returns its exact schema, and run executes that specific contract.
Authenticate the request for the intended workspace, then begin with tool discovery. State-bearing results can provide a web_url to the corresponding object in the web app, while JSON identifiers remain the source of truth for later API requests. This page documents the shared tool routes and run resources. The complete control-field view is in MCP reference.
Search the catalog
GET /api/v1/tools searches the customer capability catalog. The request needs a goal, query terms, or both. Query values are parsed by the same canonical search schema used by the other doors. A search response can include a tool_turn_token and runnable_contracts. A runnable contract marked fetched can be used in the same turn without a separate get call.
Use toolset to restrict discovery to one customer pack. It is a filter for this request, not a persistent API setting. The route rejects an unknown toolset with invalid_request and names the customer pack identifiers available for the repair. It also validates a table-action search against the caller's table-write scope when table_action_mode is present.
| Query field | Type | Required | Meaning | Default |
|---|---|---|---|---|
goal | string | Goal or query_terms | A trimmed goal from 1 through 2,000 characters. | None |
query_terms | string[] | Goal or query_terms | One through 50 trimmed terms, each up to 160 characters. | None |
domains | string[] | Optional | Terms that narrow discovery by domain. | Omitted |
kinds | enum[] | Optional | Up to 20 published search kinds. | Omitted |
available_inputs | string[] | Optional | Inputs already available to the caller. | Omitted |
desired_outputs | string[] | Optional | Outputs requested by the caller. | Omitted |
required_side_effects | string[] | Optional | Effects the caller requires. | Omitted |
excluded_side_effects | string[] | Optional | Effects the caller excludes. | Omitted |
toolset | string | Optional | A customer pack identifier used to scope discovery. | Omitted |
tool_turn_token | string | Optional | A token from an earlier search in the current turn. | Omitted |
agent_session_id | UUID | Optional | An agent session identifier. | Omitted |
table_action_mode | source | column | Optional | Requests a table-action suggestion mode. | Omitted |
cursor | string | Optional | A cursor returned by an earlier page. | Omitted |
limit | integer | Optional | A value from 1 through 50. | 25 in ordinary search |
Search the tables pack for a capability that creates a workbook, then show the exact contract before running it.The response is a discovery result, not a mutation. Read the goal, returned candidates, route information, turn token, and runnable contracts before deciding which item to fetch. A caller that has only a remembered capability name should still search first because catalog availability, schema, execution policy, and workspace scope are resolved for the active request.
Get the exact contract
GET /api/v1/tools/:id reads an exact capability contract. The path supports one id or a comma-separated batch of ids because capability identifiers never contain a comma. Query fields are workspace_id, tool_turn_token, agent_session_id, and detail. Detail accepts compact or full, with compact as the ordinary model-facing contract.
Use compact detail to inspect the input schema, required fields, modes, policies, and an example. Use full detail only when your application needs the full catalog record. For a batch get, the response has contracts whose capabilities are projected using the requested detail. For one get, the response has the capability contract using that detail. Keep the search token when the search delivered one, because the gateway uses it to keep discovery and execution in the same turn.
Retrieve the compact contract for the workbook capability found in this turn. Tell me which inputs are required and which modes it supports.Do not substitute a client alias such as tool_id for the capability path. The REST route has the capability id in its path, while MCP exposes the same concept as capability_id. The output contract is what should determine the next HTTP body, not a copied example from this page.
Run a capability
POST /api/v1/tools/:id/run accepts a strict execution envelope. The selected capability id is in the path. The params object belongs to the selected capability schema, while mode, credits, quote, turn token, and idempotency are execution-envelope controls. The API returns invalid_request if the body fails the published schema and includes a fix_input repair.
Mutating calls must explicitly include smoke_test, dry_run, or live. Smoke test inspects static schema and policy without writing or creating an audit entry. Dry run validates and previews against workspace state without business writes, provider spend, or outward actions. Live executes the selected capability. The route returns mode_required for a mutation with no mode and says that it never defaults to live.
| Body field | Type | Required | Meaning | Default |
|---|---|---|---|---|
params | object | Optional | Capability parameters matching the fetched input schema. | Empty object |
mode | smoke_test | dry_run | live | Mutating capability | The execution mode. The server never defaults a mutation to live. | Capability dependent for reads |
max_credits | number | Optional | A non-negative execution-envelope credit ceiling. | Omitted |
quote_hash | quoted hash | Optional | A quote from a prior priced request. | Omitted |
tool_turn_token | string | Optional | A current discovery-turn token. | Omitted |
idempotency_key | string | Live write dependent | A replay-safety key, 1 through 255 characters. | Omitted |
agent_session_id | UUID | Optional | An agent session identifier. | Omitted |
workflow_id | UUID | Optional | A workflow identifier. | Omitted |
Use dry run for the fetched workbook contract with the name Trial accounts. Show the returned envelope and any run identifier.A successful envelope has ok: true, an executed boolean, effect_count, a return kind, optional data and changed values, optional receipt and execution metadata, optional reversibility, and budget fields. Canonical execution metadata includes capability, run, idempotency, and grant-evaluation identifiers. An error envelope has ok: false, a code, message, repair, optional metadata, budget fields, and optional details.
Inspect runs and pages
The run routes support list, get, events, and cancel. Run list and events use the canonical paging fields: a returned cursor and a limit from 1 through 500, defaulting to 100. Run get accepts an optional wait from zero through 20 seconds on this HTTP call. An Architect streaming runs_get may wait up to 120 seconds by repeating this read. An omitted wait returns the current snapshot immediately, while an unsettled request can return HTTP 202 with the same run id.
A run resource carries the durable run envelope, an exact next decision hint, its kind, a web URL, and a UI URI. The run itself includes status, state version, completed and incomplete snapshots, partial results, cursor state, exhaustion reason, retry frontier, degradation state, permitted operations, and timestamps. A run get additionally reports item counts, credit estimate and actual values, terminal status, and failed items with repair hints.
List active runs, inspect this run, then show event details and the next decision hint if it needs attention.Cancellation is a stateful write. Read the run, then send its current expected_state_version with an optional reason to the cancel operation. If another worker moved the run first, read again and reconcile the new state instead of reusing an old state version. The CLI offers the same run operations when a terminal workflow is more convenient than direct HTTP.
When it goes wrong
An unauthorized response means the request lacks usable authentication. A missing_scope response on a table-action search means the caller needs table-editor access. An invalid_request response means a path, query, or body failed a strict schema. Use the returned repair and legal field names. Do not silently drop a value that carries scope, token, or mode meaning.
If execution returns capability_not_fetched, search again in the current turn, preserve its tool_turn_token, get the missing contract, and retry. If it returns mode_required, supply the mode before retrying. If an idempotency header and body key differ, the API returns idempotency_conflict because it does not pick a winner. Send one key or the same key in both places.
If a result has has_more: true, pass the returned cursor into the next list or events request. If a provider reports degradation, use the run response's retry information and decision hint before opening another request. If a quote is required, keep the original parameters unchanged and add the expected credit ceiling. For detailed error-envelope fields, use Envelope and errors.