Platform API: Your first durable agent

Create an AI engineer with its own machine, memory, and work history — in five minutes, with curl.

The Prodedify Platform API gives you durable AI engineers. An agent is not a chat session: it is a long-lived resource with its own isolated machine (that hibernates when idle and resumes in ~1–2 seconds), its own memory (it remembers every prior run), and its own work history.

Create it once. Put it to work through one API call. Tomorrow it picks up where it left off.

Prerequisites

An organization-scoped platform key (prod_sk_...). Organization admins create them under Organization Settings → Platform keys. The key is shown once — store it securely.

export PRODEDIFY_API_KEY="prod_sk_..."
export API="https://api.prodedify.com/api/v1/platform"

All requests authenticate with a bearer header:

Authorization: Bearer prod_sk_...

1. Create an agent

curl -X POST "$API/agents" \
  -H "Authorization: Bearer $PRODEDIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Docs Engineer",
    "instructions": "You are a careful engineer. Keep replies brief.",
    "tier": "lite"
  }'

{
  "id": "b70cc507-...",
  "name": "Docs Engineer",
  "status": "active",
  "machine": { "status": "none", "resume_count": 0 },
  ...
}

The machine shows none — it provisions lazily on the first run that needs one, and stays with the agent afterwards.

2. Start a run

curl -X POST "$API/agents/{agent_id}/runs" \
  -H "Authorization: Bearer $PRODEDIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-first-run" \
  -d '{"input": "Create a file at /home/user/demo/hello.txt containing: hello platform"}'

The response is 202 Accepted with a stream_url. The optional Idempotency-Key header makes retries safe: resending the same key returns the original run instead of starting a duplicate.

3. Watch it work

curl -N "$API/runs/{run_id}/stream" \
  -H "Authorization: Bearer $PRODEDIFY_API_KEY"

Events arrive as server-sent events in the versioned platform.v1 schema:

id: 1718037900000-0
data: {"schema":"platform.v1","type":"tool_call_start","data":{"name":"file_write"},...}

data: {"schema":"platform.v1","type":"status","data":{"status":"provisioning_sandbox"},...}
data: {"schema":"platform.v1","type":"status","data":{"status":"sandbox_ready"},...}
data: {"schema":"platform.v1","type":"file_created","data":{"path":"/home/user/demo/hello.txt"},...}
data: {"schema":"platform.v1","type":"token","data":{"text":"Created the file..."},...}
data: {"schema":"platform.v1","type":"done","data":{"credits":{...}},...}

If your connection drops, reconnect with the last id: you received in a Last-Event-ID header — the stream resumes from that exact cursor.

4. The part that matters: it remembers

Start a second run — no context in the prompt:

curl -X POST "$API/agents/{agent_id}/runs" \
  -H "Authorization: Bearer $PRODEDIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "What does the file you created earlier contain? Verify from disk."}'

The agent recalls the prior run, reads the file from the same machine (no re-provisioning), and answers. That continuity — conversation memory plus a persistent filesystem — is what makes platform agents durable.

5. The machine

curl "$API/agents/{agent_id}/machine" \
  -H "Authorization: Bearer $PRODEDIFY_API_KEY"

{ "status": "active", "resume_count": 1, "expires_at": "2026-07-10T..." }

Idle machines hibernate automatically (you stop paying for compute). They resume lazily on the next run, or explicitly in ~1–2 seconds:

curl -X POST "$API/agents/{agent_id}/machine/wake" \
  -H "Authorization: Bearer $PRODEDIFY_API_KEY"

Endpoint summary

Method	Path	Scope
`POST`	`/agents`	`agents:write`
`GET`	`/agents` · `/agents/{id}`	`agents:read`
`PATCH` / `DELETE`	`/agents/{id}`	`agents:write`
`GET`	`/agents/{id}/machine`	`agents:read`
`POST`	`/agents/{id}/machine/wake`	`agents:write`
`POST`	`/agents/{id}/runs`	`runs:execute`
`GET`	`/runs/{id}` · `/runs/{id}/stream`	`runs:read`
`POST`	`/runs/{id}/cancel`	`runs:execute`
`GET`	`/agents/{id}/memory`	`memory:read`
`POST`	`/agents/{id}/memory/query`	`memory:read`
`POST`	`/agents/{id}/memory/facts`	`memory:write`
`GET`	`/agents/{id}/files?path=...`	`agents:read`

Memory

Beyond conversation history, agents accumulate structured memory — decisions and knowledge, shared across all of your organization's platform agents:

# Seed a fact the agents should always know
curl -X POST "$API/agents/{agent_id}/memory/facts" \
  -H "Authorization: Bearer $PRODEDIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"summary": "Authentication uses Better Auth", "category": "architecture"}'

# Ask what the agents know
curl -X POST "$API/agents/{agent_id}/memory/query" \
  -H "Authorization: Bearer $PRODEDIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "how do we handle authentication?"}'

Query results are similarity-ranked across decisions and learned knowledge. Categories: architecture, tooling, scope, priority, design, process.

Reading files off the machine

curl "$API/agents/{agent_id}/files?path=/home/user/demo/hello.txt" \
  -H "Authorization: Bearer $PRODEDIFY_API_KEY"

Hibernated machines auto-resume for the read. Use &encoding=base64 for binary files.

AG-UI protocol

Building a frontend on the AG-UI protocol? Request it on the stream:

curl -N "$API/runs/{run_id}/stream?format=agui" \
  -H "Authorization: Bearer $PRODEDIFY_API_KEY"

Events arrive as agui/v1 (TEXT_MESSAGE_CONTENT, TOOL_CALL_START, RUN_FINISHED, ...) instead of platform.v1.

Platform keys carry explicit scopes — a key missing a required scope gets a 403 naming exactly what is missing.

The machine-readable spec for this surface lives at /api/v1/public/platform/openapi.json.

Platform API: Your first durable agent

On this page