Create agent session children

POST/workspaces/{organizationId}/agent/sessions/{sessionId}/children

Authorization

AuthorizationBearer token · headerrequired

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

Path parameters

organizationIdstringrequired

sessionIdstringrequired

Request body

application/json

titlestringrequired

min length 1

descriptionstring

agentIdstring

modelstring

repostring

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

stepKeystring

min length 1

Responses

201

Child session created and dispatched

sessionobjectrequired

Show properties

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

issueobjectrequired

Show properties

idstringrequired

identifierstring | nullrequired

titlestringrequired

descriptionstring | nullrequired

statusstringrequired

prioritystringrequired

repostring | nullrequired

branchstring | nullrequired

parentIdstring | nullrequired

createdAtstringrequired

updatedAtstringrequired

400

Bad request

404

Session or parent issue not found

429

Too many active child sessions

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer tokenRemember on this deviceInclude my values in samples

Parameters

organizationIdpath*sessionIdpath*

Bodyapplication/json

titlestring*descriptionstringagentIdstringmodelstringrepostringeffortstringmaxDurationintegerWall-clock run budget in minutes; past it the lane is canceled and escalated on the issuestepKeystring

Request

curl -X POST 'https://pile.nyc/workspaces/string/agent/sessions/string/children' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "title": "string",
  "description": "string",
  "agentId": "string",
  "model": "string",
  "repo": "string",
  "effort": "low",
  "maxDuration": 1,
  "stepKey": "string"
}'

const response = await fetch("https://pile.nyc/workspaces/string/agent/sessions/string/children", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"title\": \"string\",\n  \"description\": \"string\",\n  \"agentId\": \"string\",\n  \"model\": \"string\",\n  \"repo\": \"string\",\n  \"effort\": \"low\",\n  \"maxDuration\": 1,\n  \"stepKey\": \"string\"\n}"
});

import requests

response = requests.post(
    "https://pile.nyc/workspaces/string/agent/sessions/string/children",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"title\": \"string\",\n  \"description\": \"string\",\n  \"agentId\": \"string\",\n  \"model\": \"string\",\n  \"repo\": \"string\",\n  \"effort\": \"low\",\n  \"maxDuration\": 1,\n  \"stepKey\": \"string\"\n}",
)

Response

{
  "session": {
    "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"
      }
    ]
  },
  "issue": {
    "id": "string",
    "identifier": "string",
    "title": "string",
    "description": "string",
    "status": "string",
    "priority": "string",
    "repo": "string",
    "branch": "string",
    "parentId": "string",
    "createdAt": "string",
    "updatedAt": "string"
  }
}