Dispatch issue

POST/workspaces/{organizationId}/issues/{id}/dispatch

Authorization

AuthorizationBearer token · headerrequired

Workspace API key (Authorization: Bearer <key>). Issue keys under Settings → Developer or POST /workspaces/{organizationId}/tokens.

Path parameters

organizationIdstringrequired

idstringrequired

Request body

application/json

agentIdstring

providerstring

modelstring

repostring | null

branchstring | null

instructionsstring

stepKeystring

min length 1

preflightboolean

secondaryReposobject[]

max items 5

Show properties

Array of object

repostringrequired

matches ^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$

accessstring

default: "read"

Allowed:readwrite

modestring

Allowed:buildplanimplement_plan

effortstring

Allowed:lowmediumhighmax

maxDurationinteger

Wall-clock run budget in minutes; past it the lane is canceled and escalated on the issue

min 1 · max 1440

resultSchemastring | object

JSON Schema (draft-07) the lane's final output must validate against, or "lane" for the built-in {verdict, summary, filesChanged} shape. The validated value lands on session.structuredResult.

Show properties

Any of:

string

string

object

object

Responses

201

Session created

idstringrequired

organizationIdstringrequired

issueIdstringrequired

agentIdstringrequired

providerstringrequired

actorIdstringrequired

actorTypestringrequired

Allowed:useragent

statusstringrequired

Allowed:createdrunningstalewaitingcompletedfailedcanceled

resultstring | nullrequired

urlstring | nullrequired

providerSessionIdstring | nullrequired

prUrlstring | nullrequired

prStatestring | nullrequired

branchstring | nullrequired

purposestring | null

secondaryReposstring | null

maxDurationMinutesinteger | null

effortstring | null

Allowed:lowmediumhighmaxnull

labelstring | null

resultSchemaobject | null

structuredResultany | null

resultSchemaErrorsstring[] | null

createdAtstringrequired

updatedAtstringrequired

lastProgressAtstring | null

lastStateHashstring | null

awaitingActivityIdstring | null

awaitingEscalatedAtstring | null

pausednumber

stepKeystring | null

planobject[] | null

Show properties

Array of object

contentstringrequired

min length 1 · max length 500

statusstringrequired

Allowed:pendinginProgresscompletedcanceled

guidanceobject[] | null

Show properties

Array of object

idstringrequired

namestringrequired

scopestringrequired

Allowed:workspaceteamstatusstep

scopeKeystring | nullrequired

versionintegerrequired

derivedStatusstring | null

Allowed:stalledneeds_inputnull

awaitingFirstAckboolean

firstActivityAtstring | null

queuedAfterstring | null

receiptobject | null

Show properties

idstringrequired

organizationIdstringrequired

sessionIdstringrequired

issueIdstringrequired

agentIdstringrequired

stepKeystring | nullrequired

dealIdstring | nullrequired

statusstringrequired

modelstring | nullrequired

effortstring | nullrequired

inputTokensinteger | nullrequired

outputTokensinteger | nullrequired

totalTokensinteger | nullrequired

toolCallsinteger | nullrequired

costMicrosinteger | nullrequired

externalSpendMicrosinteger | nullrequired

totalCostMicrosinteger | nullrequired

costSourcestring | nullrequired

Allowed:reportedrate_mapnull

capExceededintegerrequired

stopReasonstring | nullrequired

startedAtstring | nullrequired

endedAtstring | nullrequired

durationMsinteger | nullrequired

createdAtstringrequired

updatedAtstringrequired

activitiesobject[]

Show properties

Array of object

idstringrequired

sessionIdstringrequired

actorIdstring | nullrequired

typestringrequired

Allowed:thoughtresponseerrorelicitationpromptactionstatusartifact

messagestringrequired

payloadany | null

parentIdstring | nullrequired

startedAtstring | nullrequired

endedAtstring | nullrequired

durationMsnumber | nullrequired

createdAtstringrequired

preflightobjectrequired

Show properties

readybooleanrequired

missingstring[]required

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer tokenRemember on this deviceInclude my values in samples

Parameters

organizationIdpath*idpath*

Bodyapplication/json

Request body

Request

curl -X POST 'https://pile.nyc/workspaces/string/issues/string/dispatch' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "agentId": "string",
  "provider": "string",
  "model": "string",
  "repo": "string",
  "branch": "string",
  "instructions": "string",
  "stepKey": "string",
  "preflight": true,
  "secondaryRepos": [
    {
      "repo": "string",
      "access": "read"
    }
  ],
  "mode": "build",
  "effort": "low",
  "maxDuration": 1,
  "resultSchema": "lane"
}'

const response = await fetch("https://pile.nyc/workspaces/string/issues/string/dispatch", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"agentId\": \"string\",\n  \"provider\": \"string\",\n  \"model\": \"string\",\n  \"repo\": \"string\",\n  \"branch\": \"string\",\n  \"instructions\": \"string\",\n  \"stepKey\": \"string\",\n  \"preflight\": true,\n  \"secondaryRepos\": [\n    {\n      \"repo\": \"string\",\n      \"access\": \"read\"\n    }\n  ],\n  \"mode\": \"build\",\n  \"effort\": \"low\",\n  \"maxDuration\": 1,\n  \"resultSchema\": \"lane\"\n}"
});

import requests

response = requests.post(
    "https://pile.nyc/workspaces/string/issues/string/dispatch",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"agentId\": \"string\",\n  \"provider\": \"string\",\n  \"model\": \"string\",\n  \"repo\": \"string\",\n  \"branch\": \"string\",\n  \"instructions\": \"string\",\n  \"stepKey\": \"string\",\n  \"preflight\": true,\n  \"secondaryRepos\": [\n    {\n      \"repo\": \"string\",\n      \"access\": \"read\"\n    }\n  ],\n  \"mode\": \"build\",\n  \"effort\": \"low\",\n  \"maxDuration\": 1,\n  \"resultSchema\": \"lane\"\n}",
)

Response

{
  "id": "string",
  "organizationId": "string",
  "issueId": "string",
  "agentId": "string",
  "provider": "string",
  "actorId": "string",
  "actorType": "user",
  "status": "created",
  "result": "string",
  "url": "string",
  "providerSessionId": "string",
  "prUrl": "string",
  "prState": "string",
  "branch": "string",
  "purpose": "string",
  "secondaryRepos": "string",
  "maxDurationMinutes": 0,
  "effort": "low",
  "label": "string",
  "resultSchema": {
    "property1": null,
    "property2": null
  },
  "structuredResult": null,
  "resultSchemaErrors": [
    "string"
  ],
  "createdAt": "string",
  "updatedAt": "string",
  "lastProgressAt": "string",
  "lastStateHash": "string",
  "awaitingActivityId": "string",
  "awaitingEscalatedAt": "string",
  "paused": 0,
  "stepKey": "string",
  "plan": [
    {
      "content": "string",
      "status": "pending"
    }
  ],
  "guidance": [
    {
      "id": "string",
      "name": "string",
      "scope": "workspace",
      "scopeKey": "string",
      "version": 0
    }
  ],
  "derivedStatus": "stalled",
  "awaitingFirstAck": true,
  "firstActivityAt": "string",
  "queuedAfter": "string",
  "receipt": {
    "id": "string",
    "organizationId": "string",
    "sessionId": "string",
    "issueId": "string",
    "agentId": "string",
    "stepKey": "string",
    "dealId": "string",
    "status": "string",
    "model": "string",
    "effort": "string",
    "inputTokens": 0,
    "outputTokens": 0,
    "totalTokens": 0,
    "toolCalls": 0,
    "costMicros": 0,
    "externalSpendMicros": 0,
    "totalCostMicros": 0,
    "costSource": "reported",
    "capExceeded": 0,
    "stopReason": "string",
    "startedAt": "string",
    "endedAt": "string",
    "durationMs": 0,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "activities": [
    {
      "id": "string",
      "sessionId": "string",
      "actorId": "string",
      "type": "thought",
      "message": "string",
      "payload": null,
      "parentId": "string",
      "startedAt": "string",
      "endedAt": "string",
      "durationMs": 0,
      "createdAt": "string"
    }
  ],
  "preflight": {
    "ready": true,
    "missing": [
      "string"
    ]
  }
}