Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.phrony.com/llms.txt

Use this file to discover all available pages before exploring further.

The Agents API covers routes under /v1/agents/{agentId}—starting a run and listing sessions. Use a key scoped to the same agentId in the path. For a given run, continue with the Runs API.

​
The start-run response

A successful start returns a JSON object. Field names and optional keys match what the service returns; at minimum you get ids and status to poll with Get run status. 
{
  "sessionId": "00000000-0000-0000-0000-000000000000",
  "runId": "00000000-0000-0000-0000-000000000001",
  "status": "Running",
  "totalTokensUsed": 0,
  "output": null
}

​
POST /v1/agents/{agentId}/runs

Start a new run for the agent. Optional request body with input matching your deployed agent version contract.
  • Auth: Agent-scoped key: {agentId} in the path must match the key’s scope.
  • Status: 202 Accepted on success.
Request body (JSON):
FieldTypeRequiredDescription
inputobjectNoJSON object (string keys). Shape must match your deployed agent version input contract. Omit or use {} when the agent needs no static input.
Response (success, JSON):
FieldTypeRequiredDescription
sessionIdstring (UUID)YesSession for this run.
runIdstring (UUID)YesUse with /v1/runs/{runId} routes.
statusstringYesRuntime status; work may still be in progress after this response.
totalTokensUsednumberYesNon-negative token count.
outputJSON or nullYesParsed when non-empty; otherwise null until (or if) available.
errorstringNoError message if the start path set one.
agentIdstring (UUID)NoSet when useful for the client.
triggerIdstring (UUID) or nullNoThe API trigger when applicable.
duplicateDeliverybooleanNoFor some ingress paths, true when a prior delivery is replayed (not a normal API start).
The API may return additional fields. Rate limits, concurrency limits, and plan checks apply as configured on the API trigger.

​
GET /v1/agents/{agentId}/sessions

List sessions for this agent, with optional pagination and version filter.
Query (optional):
ParameterTypeDescription
skipintegerOffset for pagination (non-negative).
takeintegerPage size.
versionIdstring (UUID)Limit to a specific deployed version.
Response (success, JSON):
FieldTypeDescription
itemsarraySession list item objects (newest or query order, depending on the service).
totalnumberNon-negative; total session rows that match the filter (for pagination).

​
List sessions item

FieldTypeDescription
idstring (UUID)Session id.
tenantIdstring (UUID)Workspace id.
agentIdstring (UUID)Agent id.
agentVersionIdstring (UUID)Version used for the session.
llmModelstring or nullResolved model label for that version, when available.
triggerTypestringHow the session was started (for example api, scheduled, or values your workspace uses).
triggeredBystring or nullWho/what started it (for example an API key id for API runs).
triggerIdstring (UUID) or nullTrigger id when applicable.
triggerNamestring or nullTrigger display name when resolved.
statusstringSession status.
totalTokensUsednumberCumulative token usage.
outputJSON or nullSession-level result when set.
errorstring or nullError when the session failed.
inputJSON or nullStart input from the root run’s snapshot, when available.
startContextobject or nullStart context (user input, version snapshot), when available.
rootRunIdstring (UUID) or nullRoot run in the session (convenience for sub-agent lineages).
startedAtstring (ISO-8601)When the session started.
finishedAtstring (ISO-8601) or nullWhen the session completed, if it has.
runCountnumberNumber of runs in the session.
entryRunIdstring (UUID) or nullA run you can use for run-scoped links (earliest in the session).

​
Examples

​
Start a run and poll run status

Use runId from the POST response with GET /v1/runs/{runId} (see Runs API) until the run reaches a finished state in your use case. 
export PHRONY_API_BASE="${PHRONY_API_BASE:-https://api.phrony.com}"
export PHRONY_API_KEY="phk_..."
export AGENT_ID="00000000-0000-0000-0000-000000000000"

RESP=$(curl -sS -X POST "${PHRONY_API_BASE}/v1/agents/${AGENT_ID}/runs" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${PHRONY_API_KEY}" \
  -d '{"input":{}}')
echo "$RESP"
RUN_ID=$(echo "$RESP" | python3 -c "import json,sys; print(json.load(sys.stdin)['runId'])")
curl -sS "${PHRONY_API_BASE}/v1/runs/${RUN_ID}" \
  -H "X-API-Key: ${PHRONY_API_KEY}"

​
List sessions

Optional query: skip, take, versionId. 
export PHRONY_API_BASE="${PHRONY_API_BASE:-https://api.phrony.com}"
export PHRONY_API_KEY="phk_..."
export AGENT_ID="00000000-0000-0000-0000-000000000000"

curl -sS -G "${PHRONY_API_BASE}/v1/agents/${AGENT_ID}/sessions" \
  --data-urlencode "skip=0" \
  --data-urlencode "take=20" \
  -H "X-API-Key: ${PHRONY_API_KEY}"