Start a task
Starts a task and returns 202 with the task and the id of your first message.
The task runs like any other: it gets a sandbox, can open a pull request, and shows up in the dashboard.
Only prompt is required. title defaults to the prompt's first line, up to 80 characters. repo is optional: omit it to let the agent choose a repository.
Before it makes the task, Sinatra checks that the workspace is connected to GitHub, that billing allows the task, and that the queue has room. A refusal says which in its error code, and a retry with the same key of a start that already made its task is never refused.
Send an Idempotency-Key so a retry is safe. A start retried with the same key returns the same task and never starts a second one. The same key with a different prompt, or a different repository or title if you send them, is 409 idempotency_conflict. Keys belong to the person who sent them. The key becomes the first message's messageId.
If Sinatra saves your request but can't hand it to the agent yet, it answers 503 unavailable with the new taskId and messageId. Retry with the same key, or send a message on that task, which sends your prompt first.
A task started this way counts against the workspace's plan like any other. A running turn takes one of the plan's tasks at a time; past that it's queued. See How the queue works. It also needs model access, like a task delegated from Linear or GitHub. See Models.
/v1/workspaces/{workspaceId}/tasksA personal access token, which starts with sntr_. Create one on the dashboard's CLI & API page (https://app.sinatra.dev/tokens). It acts as you in every workspace you belong to, with your role in each, and expires after at most 365 days. The CLI's browser sign-in sends an OAuth access token here instead.
In: header
Path Parameters
The workspace's id, from GET /v1/me.
Header Parameters
Makes a retry safe. 1 to 128 printable ASCII characters, with no spaces. A request repeated with the same key answers with the first one's result and does the work once; the same key with different content is 409 idempotency_conflict. Keys belong to the person who sent them: two people using the same key start two tasks or send two messages. The key is also the messageId of the message the request sends, which is a start's first message.
^[\x21-\x7e]{1,128}$What to do, as you'd ask a teammate. Up to 100,000 characters, after trimming.
1 <= length <= 100000The task's title, up to 200 characters. Defaults to the prompt's first line, cut to 80 characters.
owner/name of a repository connected to the workspace. Omit it to let the agent choose.
Response Body
curl -X POST "https://api.sinatra.dev/v1/workspaces/string/tasks" \ -H "Idempotency-Key: string" \ -H "Content-Type: application/json" \ -d '{ "prompt": "string" }'{
"task": {
"id": "string",
"status": "string",
"source": "string",
"title": "string",
"repo": "string",
"pullRequest": {
"url": "string",
"merged": true
},
"queued": true,
"createdAt": "2019-08-24T14:15:22Z",
"lastActivityAt": "2019-08-24T14:15:22Z",
"url": "string"
},
"messageId": "string"
}{
"error": "string",
"reason": "string",
"requestId": "string",
"refusal": "string",
"billingUrl": "string",
"settingsUrl": "string",
"plan": "string",
"running": 0,
"queued": 0,
"taskId": "string",
"messageId": "string"
}{
"error": "string",
"reason": "string",
"requestId": "string",
"refusal": "string",
"billingUrl": "string",
"settingsUrl": "string",
"plan": "string",
"running": 0,
"queued": 0,
"taskId": "string",
"messageId": "string"
}{
"error": "string",
"reason": "string",
"requestId": "string",
"refusal": "string",
"billingUrl": "string",
"settingsUrl": "string",
"plan": "string",
"running": 0,
"queued": 0,
"taskId": "string",
"messageId": "string"
}{
"error": "string",
"reason": "string",
"requestId": "string",
"refusal": "string",
"billingUrl": "string",
"settingsUrl": "string",
"plan": "string",
"running": 0,
"queued": 0,
"taskId": "string",
"messageId": "string"
}{
"error": "string",
"reason": "string",
"requestId": "string",
"refusal": "string",
"billingUrl": "string",
"settingsUrl": "string",
"plan": "string",
"running": 0,
"queued": 0,
"taskId": "string",
"messageId": "string"
}{
"error": "string",
"reason": "string",
"requestId": "string",
"refusal": "string",
"billingUrl": "string",
"settingsUrl": "string",
"plan": "string",
"running": 0,
"queued": 0,
"taskId": "string",
"messageId": "string"
}{
"error": "string",
"reason": "string",
"requestId": "string",
"refusal": "string",
"billingUrl": "string",
"settingsUrl": "string",
"plan": "string",
"running": 0,
"queued": 0,
"taskId": "string",
"messageId": "string"
}{
"error": "string",
"reason": "string",
"requestId": "string",
"refusal": "string",
"billingUrl": "string",
"settingsUrl": "string",
"plan": "string",
"running": 0,
"queued": 0,
"taskId": "string",
"messageId": "string"
}{
"error": "string",
"reason": "string",
"requestId": "string",
"refusal": "string",
"billingUrl": "string",
"settingsUrl": "string",
"plan": "string",
"running": 0,
"queued": 0,
"taskId": "string",
"messageId": "string"
}