Executions

An execution is a plan: a goal, the stages Tessen chose for it, and the state of each. Creating one returns immediately with the plan — the work runs after the response.

POST/api/execution

Start an execution, or resume one that stopped at an approval gate.

Session cookie, or an API key carrying the build scope.

Body

Field	Type	Required	Description
`goal`	`string`	yes	What you want, in words. Between 8 and 2000 characters.
`outcome`	`"website" \| "ebook"`	no	What is being made. Defaults to "website". Anything unrecognised falls back to the default rather than erroring.
`planId`	`string`	no	Resume this plan instead of starting a new one. When present, goal and outcome are ignored.
`approve`	`string[]`	no	Stage ids to approve on a resume. Unknown ids are dropped.

Request

curl -X POST https://cloud.tessen.ai/api/execution \
  -H "Authorization: Bearer tsn_cloud_EXAMPLE" \
  -H "content-type: application/json" \
  -d '{"goal":"a one-page site for a bakery in Lisbon","outcome":"website"}'

Response

HTTP/1.1 202 Accepted

{
  "plan": {
    "id": "<plan id>",
    "goal": "a one-page site for a bakery in Lisbon",
    "project": null,
    "status": "running",
    "progress": 0,
    "resumable": false,
    "warning": null,
    "previewUrl": null,
    "publishedUrl": null,
    "stages": [
      { "id": "understand", "title": "...", "state": "running", "attempts": 1, "error": null }
    ]
  },
  "unavailable": []
}

Errors

Status	When
`400`	The body was not JSON, or the goal was shorter than 8 or longer than 2000 characters.
`401`	No session and no valid key.
`403`	The key does not carry the build scope.
`404`	A planId was given that is not yours or does not exist.
`429`	Your generation limit for the window is reached.
`503`	No stage for that outcome can run here. The body names which outcomes are unavailable rather than the missing credential.

202, not 200. The plan row is written and the response returns before any stage finishes — so the id is watchable from the first millisecond and a crash mid-run is resumable. `unavailable` is reported rather than silently trimmed.

GET/api/execution

Read one of your plans, or your ten most recent.

Session cookie, or an API key carrying the read scope.

Query parameters

Name	Type	Required	Description
`id`	`string`	no	A plan id. Omit to list your ten most recent plans.

Request

curl "https://cloud.tessen.ai/api/execution?id=<plan id>" \
  -H "Authorization: Bearer tsn_cloud_EXAMPLE"

Response

HTTP/1.1 200 OK

{ "plan": { "id": "...", "status": "...", "progress": 0, "stages": [] } }

Errors

Status	When
`401`	No session and no valid key.
`404`	No plan with that id belongs to you. Indistinguishable from one that never existed, deliberately.