API

Discovery and ops

Versioned API

PUT /v1/agents/{id} also takes slug, model (auto or a broker wire_id), memory_model (auto means the agent's own model), harness_id, max_turns, skills: [{ skill_id, version_id? }], and tools: ["search", …]. max_turns is the model steps one Agent Harness V1 evaluation may take. The minimum is 10. Omit it on create to use 10, and on update to keep the stored value. A higher value is kept. A null skill pin means latest. An empty tools list grants nothing extra. Always-granted tools (remember, recall on V1) come with the harness and are dropped from stored grants. A tool not on the pinned harness, or a skill on a harness with allows_skills=false, is a 422. A save that changes instructions, model, memory model, skills, harness, or tools bumps generation. The agent record also includes workspace_conversation_id when the harness has opened a transcript. contributes_to_knowledge defaults to false. The harness copies that value onto workspace conversations it opens. A save that omits the field leaves the stored value. Changing run_type or harness_id on a running agent is a 409; stop it first.

Raw PUT /v1/agents/{id} is not a partial-update contract: callers must supply name, instructions, project_id, practice, and conversation_id to preserve their values. The Foundry tools read the latest definition and merge the supplied fields before making that PUT.

GET /v1/harnesses includes always_granted. GET /v1/tools?harness_id= marks those tools with always_granted: true. The store and thoughts renderer live in services/foundry/internal/harness/memory; V1 (cmd/harnessV1) decides when to call them.

Every agent record includes created_by, slug, email, and last_heartbeat_at (set when the harness posts a log line). created_by is the creator's FID, or agent:<id> when an agent created it. email is ${slug}@ai.flow.life in prod and ${slug}@dev-ai.flow.life in every other environment. The slug is unique. A create without slug proposes one from name. call_secret_pending is true when a one-time secret is waiting. The hash is never returned. A log row is { kind, message, created_at } with kind of started, heartbeat, wake, error, skill, info, or warn. A skill line names the tool (ran send_sms) and does not include the result. info and warn are the work cycle: config, granted tools, skips, and parse checks. The same lines are printed to harness stdout.

send_email, send_sms, send_announcement, git_commit, and open_pull_request take an optional sources argument: a list of {kind, id}, where kind is evidence (a workspace record_id) or insight (an intelligence insight id). It names the records or insights the message or change was based on. It is optional because an agent can also act on the web, its prompt, or its own reasoning, and no call is refused for leaving it out. After a successful call, the harness posts the sources to POST /v1/agents/{id}/action-sources. It adds any UUID written into the message body, subject, commit message, or pull request title and body, since agents already put insight ids there and the send path removes them before delivery. Each row also stores read_in_run: whether a read tool such as search or get_insight returned that id earlier in the same run. A Harness V1 run is one evaluation, and a coding run is one task. GET /v1/observer/sources?ids= lists the actions that cited any of up to 200 ids, newest first, for the agents the caller may list. The Network Observer uses it to draw a record's path. GET /v1/agents/{id}/sources lists what one agent cited, together with every agent below it in its parent chain, such as its ephemeral and coding agents. Each row's agent_id names the agent that cited it. The caller needs at least the viewer role on the agent. The Sources tab on the Agents page and the Sources section of an ephemeral agent read this route, and link each source to its insight page or to the record in Evidence Review. Each row also has "Show path" for the record's path on the Network Observer. An insight row reads the insight's citations and shows one link for each workspace record it quotes.

The Conversation tab shows the workspace conversation the harness writes for that agent, and links to the same thread on the Conversations page. An ephemeral agent shows its own conversation on the Ephemeral tab.

POST /v1/agents/on-demand/{slug} is the public call path for a persistent on-demand agent. It does not start a harness pod. The caller needs a Cloudflare Access JWT (Cf-Access-Jwt-Assertion) and the one-time secret in X-Flow-On-Demand-Secret. The secret is consumed on a successful call. Start sets desired_state=running so the path accepts calls; Stop turns it off.

The audit log is foundry's own (same pattern as ADR 0043): foundry-api's publisher writes one sentence per agent or skill outbox event. auditListener writes the same row from the bus. The command that changed the row does not write the audit row.

Enveloped All /v1/* JSON uses the Response envelopeResponse envelope: The template service wraps every JSON response in {header, payload}. A success payload is {data} (a record or a list) plus optional meta.pagination; accounting still returns bare bodies and RFC 9457 errors until the divergence is resolved..

Every agent has one owner, owner_fid, the person it acts as. Other people get editor or viewer access through the members routes. A viewer reads. An editor does everything except delete and archive, sharing and tools included. Only the owner deletes or archives. A swarm member or coding agent follows the agent at the top of its parent chain. Someone with no access gets 404, the same as for an agent that does not exist; a member without the role gets 403 with code insufficient_role. Every agent record carries caller_role. A platform admin reads every agent and changes none, unless the request sends X-Flow-As-Member: true. See docs/decisions/0078-foundry-agents-have-members.md↗.

CedarCedar: The authorization engine; each service embeds a Cedar policy and evaluates every mutating request against the actor's principal record. still gates the action itself: staff manage, start, and run. A person can also call with a broker credential they minted for themselves. The JWT's email is the caller, the same as their Access session. communications and the scheduler use a service token. The shared service token is also what the harness uses: it reads the inbox, posts runs and logs, and calls the agent endpoints behind any Foundry tools the agent is granted. With X-Flow-Agent-Id, a service-token call acts as that agent's owner; the Foundry tools always send it. Without it, the service token keeps the access it had before agents had members. Communications also reads GET /v1/agents/by-slug/{slug} to attach inbound mail. The scheduler POSTs /wake only. The same scheduler token may also POST /internal/jobs/daily-briefs and /internal/jobs/weekly-coaching. See Daily briefs.

Daily briefs

Weekly coaching

For the agent-desktop "You" page (ADR 0111). Every route but the job is the caller's own and takes no person, so nobody, including a manager or a platform admin, can read another person's coaching. The agent never reads it.

A report holds two parts. Meeting time is counted in code. A one-line summary gives the coached week's recorded meetings, their length and how many the person spoke in. Zoom records carry no end, so a meeting's length runs to its last line. Then, from the past four weeks of meetings the person was in, calls in a personal room left out: for a recurring meeting, how often it met, for how long, how often they spoke, and how many decision claims intelligence drew from it. A series is raised when it took at least two hours and they spoke in at most a quarter of the meetings read, or when it met at least three times with no decisions. How you communicate is one model call over the person's own lines from the week's meetings and threads, for the people in COACH_COMMUNICATION_RECIPIENTS. It looks for a decision without an owner or date, an ask without an owner or deadline, a repeated question, and a meeting they ran that ended without next steps. Code keeps at most three points, and only those whose quote is at the line named, is the person's own words (or the end of a meeting they ran), and names nobody else.

A third part covers what other people said about the person that week (ADR 0116): lines naming them from records they may open, as on the "You" page, read with the lines around each. One model call looks for someone waiting on them, credit, a concern, and a misunderstanding, at most one point of each. The quote keeps its speaker's name; the suggestion names nobody. The report carries these as about_you, and the job's answer as about_you and about_you_points.

Headers

Events carry ids, lifetime, run type, and reason: agent.started, agent.stopped, agent.woken, swarm.dismissed, agent.skills_changed, agent.tools_changed, skill.created, skill.versioned. agent.member_added, agent.member_role_changed, and agent.member_removed carry the agent id, the principal, and the role. No bodies.