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.

Embedded agents are agents you invoke from your own application or backend over Phrony’s HTTP API — the same workspace-scoped execution, LLM provider credentials, integrations, and policies as a dashboard session, with your product owning the user journey. That path depends on an API trigger on the agent (and an API key scoped to that agent + trigger).

​
How you wire it up

  1. Deploy a version of the agent in the Phrony dashboard so a deployed snapshot is what the platform runs for this line of work.
  2. Create an API trigger on that agent. Only API triggers get HTTP start URLs; each row carries limits, optional IP allowlists, and the trigger id you bind into API key scopes.
  3. Create an API key in Settings and give it a scope that includes that agent and that API trigger. The key is a single secret (prefix phk_) you send on every call. If you need to upload files for runs (see below), turn on Allow file uploads for that key (off by default).
  4. Use the API at https://api.phrony.com (Phrony Cloud’s API host). The agent’s Access tab shows the same base URL plus your agentId and triggerId for scoping the API key.
Requests validate the key: for POST /v1/agents/{agentId}/runs the key must match the agentId in the path and the trigger encoded in the key’s scope. For GET /v1/runs/{runId} and optional conversation or stream paths, the same key must still authorize access to that run.

​
API surface (embedded)

StepMethodPathPurpose
Start a runPOST/v1/agents/{agentId}/runsBody: { "input": { ... } } (input is optional). Returns 202 with sessionId, runId, and status.
Poll status / resultGET/v1/runs/{runId}Status, output, optional error.
List sessions (optional)GET/v1/agents/{agentId}/sessions?skip=0&take=10Paginated sessions for the agent.
Conversation / stream (optional)GET/v1/runs/{runId}/conversation, /v1/runs/{runId}/streamTimeline and SSE; same X-API-Key as above.
Get upload URLPOST/v1/file-library/presignOptional: get a time-limited URL to PUT the file (requires file uploads on the key).
Complete uploadPOST/v1/file-library/finalizeOptional: after PUT succeeds, register the file for the workspace.
All of these send the header X-API-Key: <your phk_ key>. The host is https://api.phrony.com with no extra path prefix before v1 (for example https://api.phrony.com/v1/agents/…).

​
API redaction (output-only mode)

Sessions started through an API trigger respect the trigger setting Expose step timeline to API clients. It defaults to on, so GET /v1/runs/{runId}/conversation and GET /v1/runs/{runId}/stream can surface the same kind of step-by-step timeline your team sees in the dashboard (within the limits of your key and product behavior). When that setting is off, Phrony applies redaction to those two external routes only (calls using your X-API-Key):
SurfaceWhat changes
GET .../conversationThe payload becomes output-only: timeline items are trimmed to completion-level rows (for example session and root run completed). In that JSON, per-run output, error, and input are cleared, and session-level input and startContext are nulled so prompts and execution metadata are not echoed to API clients.
GET .../stream (SSE)Step-detail events, user task / HITL-style events, and similar low-level engine signals are filtered out so clients cannot reconstruct the full trace from the stream.
Dashboard and cockpit views are unchanged: operators still see the full session timeline for the same run. GET /v1/runs/{runId} (poll for status and final result) is not rewritten by this redaction path—it returns run fields as implemented for your workspace. If your policy must not expose model output even on that poll, enforce that in your own backend or discuss stricter deployment options with your team.

​
File uploads with an API key

To attach binary or document inputs stored in your workspace (the same file library as the dashboard), use the /v1/file-library steps below. Uploads are off for a key until you enable Allow file uploads in Settings → API keys (create or edit the key). If uploads are not enabled, POST /v1/file-library/* returns 403. Flow:
  1. POST /v1/file-library/presign with JSON: filename, mediaType, and maxContentLength (bytes — the most this upload is allowed to be; your plan’s storage limit is checked here). The response includes objectKey, uploadUrl, httpMethod (PUT), requiredHeaders, and expiresInSeconds.
  2. PUT the file bytes to uploadUrl using exactly the requiredHeaders from the response (including Content-Type and encryption headers). For browser or fetch uploads, do not require a fixed Content-Length in the signed request.
  3. POST /v1/file-library/finalize with objectKey from step 1, the same maxContentLength, and optional filename / mediaType for labels in the file library.
  4. Start a run with POST /v1/agents/{agentId}/runs and pass a file in input where your agent expects it. Use the shape below: set filename to the file name only from the upload (the part after the last / in objectKey — for example a1b2c3d4-e5f6-7890-abcd-ef1234567890.pdf), not a full path. The phronyFile field marks the object as a stored file for the runtime:
{
  "input": {
    "document": {
      "phronyFile": true,
      "filename": "a1b2c3d4-e5f6-7890-abcd-ef1234567890.pdf",
      "mediaType": "application/pdf"
    }
  }
}
Phrony matches filename to the file in your workspace before the run runs. In input you normally send only filename and mediaType as shown; you do not need to pass long storage paths from the client. Use the same X-API-Key for presign, finalize, and POST /v1/agents/{agentId}/runs. Your plan’s file-storage limits apply the same as in the product UI.

​
Examples

Use https://api.phrony.com as the base URL, or the base URL your team uses for self-hosted or staging. Get AGENT_ID and the trigger to scope your key from the agent’s API trigger → Access tab; create PHRONY_API_KEY under Settings. After you start a run, take runId from the JSON response to poll. Each tab shows the same flow: start a run, then poll by runId. 
# 1) Start a run (empty object if your input schema has no required fields)
curl -sS -X POST "https://api.phrony.com/v1/agents/${AGENT_ID}/runs" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${PHRONY_API_KEY}" \
  -d '{"input":{}}'

# 2) Poll until the run finishes (use runId from the JSON body of step 1)
curl -sS "https://api.phrony.com/v1/runs/${RUN_ID}" \
  -H "X-API-Key: ${PHRONY_API_KEY}"
The start-run body is an optional JSON object input (plain object) — match the shape to your deployed agent version input contract (schema or ad hoc keys).