Build · Create · Engineering
OpenAPI endpoint reference
A complete, well-formed reference for one endpoint: method, path, parameters (with every path placeholder covered), the required status codes, and a consistent request body.
You receive: A structured endpoint reference (JSON) that passes the method, path-parameter, response-code, and body checks.
Part of Ship MVP
Example
A sample of what this play produces. Your result is generated for your inputs.
Method
POST
Path
/v1/workspaces/{workspaceId}/runs
Summary
Commission a run of a play in a workspace
Description
Starts a run of the named play inside the workspace. The intake is pre-filled from the workspace's stored facts; any field you pass here overrides the stored value for this run only. The run holds the play's credit price (250 to 1,000 credits per play, $10 to $40 at 4 cents a credit) from the workspace balance when it is accepted into the queue; the hold is spent only when the run is accepted. Results land as a structured deliverable in the workspace after the play's acceptance check passes.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| workspaceId | path | true | string | Identifier of the workspace that holds the venture's facts and credit balance. Runs read intake defaults from, and land deliverables into, this workspace. |
| Idempotency-Key | header | false | string | Client-generated key. Retrying a request with the same key returns the original run instead of commissioning (and holding credits for) a second one. |
| dry_run | query | false | boolean | When true, validates the intake and returns the resolved parameters and credit price without starting the run or holding credits. |
Responses
| Status | Description |
|---|---|
| 201 | Run commissioned. The body carries the run id, the resolved intake (workspace facts plus overrides), the credit price held, and a status of queued. |
| 400 | Invalid request: the play id is unknown, a required intake field is missing after workspace fill-in, or an override fails the play's intake schema. No credits are held. |
| 402 | Insufficient credits: the workspace balance is below the play's credit price. The body names the price and the current balance. No run is created. |
| 404 | No workspace with this id is visible to the caller. |
Request body
- Content type
- application/json
- Schema fields
Name Type Required Description play_id string true Identifier of the play to run, from the catalog of 265 plays. intake_overrides object false Field-by-field overrides of the intake values pre-filled from workspace facts. Keys must match the play's intake schema. note string false Free-text note attached to the run for the workspace's own record.
Opens soon
STUD opens runs for everyone soon, on every play at once.
Scope of the check
What's verified: STUD verifies the submitted endpoint reference (JSON) is well-formed and complete: the HTTP method and path are valid and match your intake, every {placeholder} in the path has a required path parameter, parameters are typed and non-duplicated, the required status codes are all documented, and a request body is present and typed exactly when one is required. STUD does NOT call the endpoint or verify the descriptions are accurate; it checks the reference's structure.
Get early access to STUD the day it goes live.