putty
API ReferenceEngine

Start a run

Accepts an instruction and queues a run against the project. The response is returned as soon as the run is recorded, not when it completes: the client then follows progress on `GET /projects/{projectId}/runs/{runId}/events` (paged) or the SSE stream. A project has at most one queued-or-running run at a time; starting a second answers 409 until the first finishes or is cancelled. Name a `recipe` to run one explicitly; a recipe this deployment has disabled is refused with 403 `recipe_disabled` and nothing is queued.

POST
/projects/{projectId}/runs

Accepts an instruction and queues a run against the project. The response is returned as soon as the run is recorded, not when it completes: the client then follows progress on GET /projects/{projectId}/runs/{runId}/events (paged) or the SSE stream. A project has at most one queued-or-running run at a time; starting a second answers 409 until the first finishes or is cancelled. Name a recipe to run one explicitly; a recipe this deployment has disabled is refused with 403 recipe_disabled and nothing is queued.

Path Parameters

projectId*string

The project to run the instruction against.

Request Body

application/json

The instruction to execute.

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/projects/string/runs" \  -H "Content-Type: application/json" \  -d '{    "prompt": "string"  }'
{  "id": "string",  "projectId": "string",  "status": "queued",  "prompt": "string",  "model": "string",  "recipeId": "string",  "steps": 0,  "tokensIn": 0,  "tokensOut": 0,  "sandboxMs": 0,  "error": "string",  "startedAt": "string",  "finishedAt": "string",  "createdAt": "string"}

List a project's runs GET

Returns the project's runs, newest first, with their token and sandbox-time counters. Use it to render run history; use the events endpoint for what happened inside one run.

Read a run GET

Returns one run's status and counters. Poll this, or follow the events endpoint, while a run is in flight.