Visibility
Every agent read returns only agents your key or External App may read: it must holdagents:read at the agent’s home org unit, or at an org unit above it. An agent with no home org unit is never returned, and PERSONAL agents are never returned. An agent an External App creates is homed at the App’s owning org unit, so the App reads it there. An agent an App created before 2026-10-01 stays homed at the deployment root and is returned only when the App holds agents:read there. An agent you may not read answers 404 resource_missing, the same as a missing one.
Resource shape
Agent— exactlyid,agentId,name,description,purpose,version,status,owner,ownedByCaller,tags,executionModel,model,governance,createdAt, andupdatedAt. Every field is present:purpose,version,owner,executionModel,model, andgovernancearenullwhen unset, andtagsis[].modelcarriesdefault,allowOverride, andconstraints(minContextWindow,minTier);governancecarriestieranddataScope.AgentCard— the Agent-to-Agent (A2A) discovery card:a2aVersion("0.2"),name,description,url,provider,version,capabilities(streaming and push notifications are alwaysfalse),skills(eachidandname),inputModes,outputModes, andauthentication.
ownedByCaller, not owner, to tell whether your App created an agent.
Forge agents are Convex-native — there is no separate deployment step. Composition happens at dispatch time via
composeAgentConfig, so a status change takes effect on the next dispatch.Lifecycle
Every agent moves through a status lifecycle:draft → active → optionally inactive or deprecated, and eventually archived. The status filter on listAgents lets external systems target a specific stage.
Operations
Reads:GET /api/v3/agents— listAgents — one page of the agents you may read, oldest first, optionally searched and filtered by status, execution model and tierGET /api/v3/agents/{agentId}— getAgent — fetch a single agent byagentIdor definition idGET /api/v3/agents/{agentId}/card— getAgentCard — fetch the A2A discovery card for an agent
GET /api/v3/agents/{agentId}/configuration— getAgentConfiguration — the configuration the Console’s agent detail page showsGET /api/v3/agents/{agentId}/readiness— getAgentReadiness — the agent’s “Ready to run” reportGET /api/v3/agents/{agentId}/setup-request— getAgentSetupRequest — the agent’s open setup request, if anyGET /api/v3/agent-templates— listAgentTemplates — the platform-wide agent templatesGET /api/v3/agents/{agentId}/procedure-grants— listAgentProcedureGrants — the procedures granted to or denied to the agentGET /api/v3/agents/{agentId}/grants— listAgentGrants — the agent’s tool grants, tool-set rows and permitted capability setGET /api/v3/agents/{agentId}/relationships— getAgentRelationships — who and what the agent is connected toGET /api/v3/agents/{agentId}/knowledge-activity— listAgentKnowledgeActivity — the knowledge cases it recently authored and citedGET /api/v3/agents/{agentId}/readable-scopes— listAgentReadableScopes — the knowledge scopes it reads
listAgents is paged: limit (1–100, default 50) and cursor. Follow meta.nextCursor while meta.hasMore is true. limit counts the agents returned, after visibility and filters; a short page is either the last one (meta.hasMore is false) or one that examined its limit of 200 agents and stopped (meta.hasMore is true). search (a substring of the slug, name, description or purpose), executionModel and tier filter as the Console’s agents page does.
Writes (External App credentials; for create and archive any other credential is 403 forbidden):
POST /api/v3/agents— createAgent — create an agent your App ownsPATCH /api/v3/agents/{agentId}— updateAgent — partial update of an agent your App owns; a platform or Personal key reaches the same operation as agent administrationDELETE /api/v3/agents/{agentId}— deleteAgent — archive an agent your App owns
agents:manage scope only):
POST /api/v3/agents/{agentId}/assign-tool-set— assignAgentToolSet — grant a workspace tool set to an agent your App ownsPOST /api/v3/agents/{agentId}/unassign-tool-set— unassignAgentToolSet — revoke your App’s grant of a tool setPOST /api/v3/agents/{agentId}/assign-skill— assignAgentSkill — grant a workspace skill, optionally overriding its activation modePOST /api/v3/agents/{agentId}/unassign-skill— unassignAgentSkill — revoke your App’s grant of a skill
agents:manage scope only; see Permanent deletion):
POST /api/v3/agents/{agentId}/delete-permanently— deleteAgentPermanently — permanently delete an archived agent your App owns
GET /api/v3/agents/{agentId}/versions— listAgentVersions — an agent’s immutable versions, newest firstGET /api/v3/agents/{agentId}/consumers— listAgentConsumers — the published workflow versions that pin the agentPOST /api/v3/agents/{agentId}/reinstate-version— reinstateAgentVersion — roll an agent back to a prior version: an External App withagents:managefor an agent it owns, or a platform or Personal key as agent administration
POST /api/v3/agents/{agentId}/pause— pauseAgent — pause an active agent (switches:use)POST /api/v3/agents/{agentId}/resume— resumeAgent — resume a paused agent (switches:use)POST /api/v3/agents/{agentId}/terminate— terminateAgent — terminate an agent (switches:use)POST /api/v3/agents/{agentId}/assign-owner— assignAgentOwner — assign the accountable owner (agents:manage)POST /api/v3/agents/{agentId}/acknowledge-review— acknowledgeAgentReview — acknowledge the owner review (agents:manage)POST /api/v3/agents/{agentId}/attest-identity— attestAgentIdentity — attest the agent’s identity, as a person (agents:manage)POST /api/v3/agents/{agentId}/request-setup— requestAgentSetup — ask for the agent’s missing setup (agents:read, 20 an hour)POST /api/v3/agents/create-from-template— createAgentFromTemplate — create a draft agent from a template (agents:manageandagents:write)POST /api/v3/agents/{agentId}/assign-procedure— assignAgentProcedure — grant a procedure you can read (agents:manage)POST /api/v3/agents/{agentId}/unassign-procedure— unassignAgentProcedure — revoke a procedure grant (agents:manage)POST /api/v3/agents/{agentId}/assign-tool— assignAgentTool — grant an active tool (agents:manage)POST /api/v3/agents/{agentId}/unassign-tool— unassignAgentTool — revoke a tool grant (agents:manage)POST /api/v3/agents/{agentId}/replace-exemplars— replaceAgentExemplars — replace a worker agent’s exemplars (agents:write)
GET /api/v3/agent-task-runs— listAgentTaskRuns — the sub-agent tasks agents dispatched, newest firstGET /api/v3/agent-consultations— listAgentConsultations — the questions agents asked other agents, newest first
One agent’s detail
Eight reads open one agent the way the Console’s agent detail page does, and a ninth lists the template gallery.- Who. The per-agent reads (
getConfiguration,getReadiness,getSetupRequestand the five AR-2 reads below) needagents:readat the agent’s home, the same rule asget: a missing, PERSONAL, unhomed or unreadable agent is one404 resource_missing. An unavailable agent store is500, never404.listTemplatesneedsagents:readat the platform scope, since templates are platform-wide; a grant only at an org unit is a recorded403. - Configuration. The identity, model and fallback chain, prompt, run limits, external inference controls, memory settings, and the skills and tool sets the agent holds (granted minus denied, by natural key). Never its LLM-proxy key, owner, user or creator ids, attestation, files, embeddings, synthesis request or exemplars.
- Readiness. Each check’s outcome, gate and message, and the kind of fix that clears it. Never the person, worker, seat, Job or definition hash a fix would use: people make those fixes in the Console.
- Setup request. Which gaps it asks people to fix and how many people it asks, never who;
dataisnullwhen none is open or the agent is ready now. - Grants. Procedure grants (a name only where you hold
workflows:readat the procedure’s home), a page at a time (limit1–200, default 200; continue withmeta.nextCursorwhilemeta.hasMoreistrue; a page may be short while more remain), and tool grants, tool-set rows and the permitted capability set by natural key (500 per list at most, withmeta.partial). - Relationships. The worker, position and Job where you hold
workforce:readat the position’s org unit, Access where you holdgrants:readat the platform scope, and each workflow that uses the agent where you holdworkflows:readat its home; a part you may not read is named inwithheld, hidden workflows are counted. The owner is only whether one is present and active. - Knowledge.
listKnowledgeActivityandlistReadableScopesalso needknowledge:readand return only knowledge your credential may read: unreadable cases are absent and unreadable scopes are counted. - Templates. A name
search(best match first), onecategory, or the whole gallery oldest first, a page at a time:limit1–100 (default 50), and whilemeta.hasMoreistrue,meta.nextCursorascursorwith the samesearchandcategory. Neither list answersmeta.partial. Never who created a template.
Who may write which agent
The route permissionagents:write is necessary, never sufficient. Each write decides authority at the agent’s home, inside the write itself:
- Create homes the new agent at your App’s owning org unit. Your App must be owned by an org unit and hold both
agents:writeandagents:readthere; otherwise the answer is403 forbiddenand nothing is written. The agent gets the worker role at that unit’s company root. No other grant is created. - Update and delete name the agent by its slug (
agentId). This section covers an External App; a platform or Personal key updates an agent as agent administration. An agent your App may not read at its home is404 resource_missing, the same as a missing one. An agent your App does not own, or may not write at its home (agents:writethere), is403 forbidden. - A status is an operator control. A patch that carries
statusalso needsswitches:usegiven at the platform, as the Console’s pause, resume and terminate do; a grant at an org unit is not enough. Without it the answer is403, and nothing is written:permission_deniedwhen the credential holdsswitches:usenowhere,forbiddenwhen it holds it only at an org unit. A same-key retry of a status change also needsswitches:usethen.pausedpauses the agent,activeactivates a draft, anddeprecatedterminates it (not reversible). Each change records the same control audit entry the Console records, naming your App and who gave itswitches:use. An agent never moves back todraft(409 conflict): pause or archive it instead.delete(archive) stays underagents:write. - Operator controls win. The API never changes the status of an agent that is paused (
paused), terminated (deprecated) or archived: that status change is409 invalid_stateand nothing is written. That includes an agent your App paused. Its other fields stay editable. Resume a paused agent withresumeAgentor in the Console. - Delete archives.
DELETE /api/v3/agents/{agentId}archives the agent and its versions, exactly as the Console’s first remove does. Memory and knowledge are kept. Deleting an agent that is already archived is409 invalid_state: delete it permanently withdeleteAgentPermanently.
draft or active on create; draft, active, paused or deprecated on update), or a malformed model or prompt is 400 bad_request. With an Idempotency-Key, a same-key retry returns the recorded result only while your App still owns the agent and may read it at its home; otherwise it is 409. A companion API key is not idempotency-scoped.
Tools and skills
An External App can give an agent it owns one workspace tool set or one skill at a time, and take back what it gave. Theagents:manage scope is opt-in: the built-in Apps never carry it, and an operator grants it deliberately.
- Who. Only an External App, and only on an agent it owns. The App must hold
agents:manageat the agent’s home;agents:writedoes not stand in for it. An agent your App may not read at its home is404 resource_missing; one it does not own, or one withoutagents:manageheld there, is403 forbidden. - What.
toolSetis a workspace tool set’ssetId(thenamelistToolSets returns), andskillIdis a skill’s slug. An unknown tool set or skill is404 resource_missing, and so is an assign of a tool set or skill that is not active. A system (builtin) tool set and a builtin or Anthropic skill are409 conflictin both directions: an operator assigns and revokes those in the Console. - Operator controls win. When an operator denied a tool set or skill for the agent, assigning it is
409 conflict; unassigning it never touches the deny, revokes your App’s own grant if the deny masks one, and otherwise answerschanged: false. The deny is never lifted or removed through the API. Your App only ever writes grants, and takes back only the grants it placed: unassigning a grant an operator placed, or changing its activation mode, is409 conflict. - Idempotent by state. Each result names the agent definition (
id), the agent slug, the target and whether it is now assigned.changedisfalsewhen the requested state already held, so nothing was written. OnassignSkill,activationModeis the override now stored, ornullwhen the skill’s default applies; omitting it clears any earlier override. - Takes effect at once. A change stale-marks the agent’s dispatch configuration in the same write, so the next dispatch composes with it. Assignment is not execution authority: each tool the agent calls is still governed when it runs.
Idempotency-Key, a same-key retry returns the recorded result only while your App still owns the same agent definition and may read it at its home; otherwise it is 409. Every change is audited with your App as the actor.
Versions and rollback
Every change to an agent’s definition mints an immutable version. A node of a published workflow version that pins an agent version runs exactly that version, so rolling the agent back or editing it never changes what that node runs. A node published before pinning (pinnedVersion: null in listAgentConsumers) has no version to run: in a published run it fails its step with agent_version_missing, inline or detached, until the workflow is republished; it never runs the agent’s current definition. A draft run, which has no published version, composes the agent’s current stored definition. Read the consumers before you change the agent.
- Versions.
listAgentVersionsreturnsPrimitiveVersionrows, newest first:versionId,version,status,synthesisTier,createdAt, andactive/canary, which mark the versions the agent’s heads point at. The prompt, model, grants snapshot and hashes are never returned. A page at a time (limit1–100, default 100): continue whilemeta.hasMoreistrue, passingmeta.nextCursorascursorwith the same other parameters; a page may be short while more remain, and the list never answersmeta.partial. - Consumers.
listAgentConsumersreturnsPrimitiveConsumerrows: one per node of a published workflow version that runs the agent, withworkflowId,workflowVersionId,workflowVersion,versionStatus(activeorsuperseded),logicalNodeIdandpinnedVersion(nullfor a node published before pinning). A node is listed when it can run the agent: it has no worker assignment, it is assigned to a specific AGENT worker linked to this agent (or to one with no agent link), or its worker is chosen when the step runs by role or by AGENT worker kind, since the worker picked may run this agent. A node assigned to a person (a specific employee or contractor, the EMPLOYEE or CONTRACTOR worker kind, or an identity claim, which resolves to a person) or to another agent’s specific worker is left out, and one whose assigned worker record cannot be read is left out withmeta.partial: true. Drafts are never listed;version=keeps only nodes pinned to exactly that version. The credential’s scopes must also includeworkflows:read, otherwise403 permission_deniednaming it before anything is read; a workflow you may not read at its home is left out, and one whose home cannot be decided is left out withmeta.partial: true. Paged withlimit(1–50, default 50) and an opaquecursor; a page can be short or empty before the last one. - Rollback.
reinstateAgentVersionmakes an exact prior version active again, as the Console’s rollback does. It needsagents:manageat the agent’s home. An External App may roll back only an agent it owns: an agent your App may not read is404 resource_missing; one it does not own, or withoutagents:managethere, is403 forbidden. A platform or Personal key reaches any agent, decided as agent administration decides it. An agent an operator paused or terminated, or one that is archived, is409 invalid_state, as is a version the lifecycle cannot make active. A version the agent does not have is404 resource_missing; the version already active answersheadChanged: falseand nothing is written, so it does not discard a pending edit to the agent. - Attestation stays with people. The API never attests the restored definition. The agent’s identity attestation names the definition a person attested, so after a rollback it lapses until a person attests the agent again, in the Console or with
attestAgentIdentityand a Personal key, exactly as after an API edit.
id (the agent’s slug), version, and an optional reason of at most 500 characters, recorded in the version’s history; the operation page shows a platform or Personal key’s body. With an Idempotency-Key, an External App’s same-key retry returns the recorded result only while the App still owns the same agent definition and may read it at its home; otherwise it is 409. A platform or Personal key’s same-key repeat does not run again and answers 409 idempotency_result_unavailable. An External App’s rollback runs with the App as the actor. Retiring or reinstating skill, tool and procedure versions stays in the Console.
Permanent deletion
deleteAgentPermanently removes an archived agent for good, exactly as the Console’s second remove does. It cannot be undone.
- Who. Only an External App, only on an agent it owns, with
agents:manageheld at the agent’s home;agents:writedoes not stand in for it. An agent your App may not read at its home is404 resource_missing, the same as a missing one; one it does not own, or withoutagents:managethere, is403 forbidden. - Archive first. Only an archived agent can be deleted permanently. Any other agent is
409 invalid_stateand nothing is written: archive it withdeleteAgentfirst. - What is removed. The agent definition is deleted, and its channel memory and the knowledge in its home namespace are purged in bounded batches that may finish after the response. Until the purge completes, the slug cannot be reused. Version rows stay as audit records, and published workflow versions keep their pins;
listAgentVersionsandlistAgentConsumersanswer404once the agent is gone. - Retries. The body is strict: exactly
id, the agent’s slug. With anIdempotency-Key, a repeated key returns the recorded result while your App still holdsagents:manage(Stored-response replay), and the delete never runs twice. Without a key, read the agent to learn an attempt’s outcome:404means it is gone.
Agent administration
The kill switch, the accountability repairs, the setup request and composition take any credential: a Personal key (acting as its owner, narrowed by its scopes), an External App or a platform API key, each decided at the agent’s home with its own grants. The route’s permission is necessary, never sufficient.- Who. You need the route’s permission at the agent’s home org unit:
switches:useforpause,resumeandterminate;agents:manageforassignOwner,acknowledgeReview,attestIdentity,reinstateAgentVersionand the four grant routes;agents:writeforupdateAgentandreplaceExemplars;agents:readforrequestSetup. A missing, PERSONAL, unhomed or unreadable agent is the same404 resource_missing; the permission missing at the home is a recorded403 permission_denied. ForupdateAgentandreinstateAgentVersion, a platform or Personal key holding the permission nowhere is a recorded403, and one holding it only at another org unit is a recorded404 resource_missing.switches:useis never held by a Forge agent. - The kill switch.
pauseandresumemove an agent betweenactiveandpaused;terminatemoves it todeprecated. Only an active agent can be paused and only a paused one resumed, so a terminated, archived or draft agent is never paused or resumed; an archived agent cannot be terminated. Each of these refusals is409 invalid_state. A call that changes nothing answerschanged: falseand writes no audit event. Eachreason(8 to 1,000 characters) is audited with the key’s owner or the App as the actor. - Accountability.
assignOwnerandacknowledgeRevieweach start a new 90-day review window. Each takes the state you reviewed and refuses the write with409 conflictwhen the agent changed since; an agent with no active owner is409 invalid_state. Only a person can attest an identity:attestIdentityneeds a Personal key. It attests only an approved definition: changes not yet approved are409 invalid_state. No person id or definition hash is returned. - Setup requests.
requestSetupopens one request for the agent’s missing setup, reusing the open one while the same gaps remain. Each credential may ask 20 times an hour (429 rate_limitedwithRetry-After). - Composition.
createFromTemplatecreates a draft agent at an External App’s owning org unit, or at the org unit a Personal key names (default: its owner’s home), and needsagents:manage,agents:writeandagents:readthere; a platform API key has no home and is refused.assignProcedureneedsprocedures:readat the procedure’s home and a procedure grantable as an agent tool;assignToolneeds an active tool and carries no overrides. Both write plain grants: an operator’s deny is a409 conflictand stays in place on unassign.replaceExemplarsreplaces a worker agent’s 2 to 5 exemplars, in a request of at most 256 KiB. - Retries. With an
Idempotency-Key, a repeat returns the recorded answer only while the slug names the same definition and you still may read the agent and hold the route’s permission at its home (agent_write); otherwise it is409. A platform or Personal key’s update or rollback is the exception: its same-key repeat does not run again and answers409 idempotency_result_unavailable.
Delegated work
An agent can hand work to another agent: a task run dispatches a sub-agent (by id, by a capability query, or with inline instructions), and a consultation asks another agent a question. These two lists are the Console’s delegated work page.- Who. You need
agents:readat the platform scope, the key and home the Console’s page uses. A grant only at an org unit answers a recorded403. - Content follows the run. A row’s content (its label, its instructions or question, its capability query, its inputs, its result or answer, and its error) is returned only when the row’s parent is a workflow run you can see:
runs:readat the run’s home and at every company it carries, asGET /api/v3/runs/{runId}decides it. Otherwise those fields arenullandcontentWithheldistrue. A row whose parent is a chat always withholds them; chat content is read through the chat surface. Shown content is returned as recorded except that credential-shaped strings (JWTs, bearer tokens, GitHub tokens) are replaced by a[REDACTED]marker. - What never crosses. The parent chat session, worker ids, workpool jobs, the answer’s agent thread, the audit trail, a task’s tool sets, and a consultation’s attachments (only
attachmentCount). - Personal Agents stay out. A row that names a PERSONAL agent, as the agent that dispatched or asked, the agent asked for, the agent that ran it or the agent consulted, is left out, so a page can hold fewer rows than
limitwhile more remain. - Paging. Rows come newest first, optionally filtered by
status, a page at a time:limit1–100 (default 50), and whilemeta.hasMoreistrue,meta.nextCursorascursorwith the samestatus. Withstatus,foregroundrows come beforebackgroundrows, each newest first (the Console’s order), so an older foreground row can come ahead of a newer background one. A row whose parent run cannot be decided within the request’s limits withholds its content, as a run you cannot see does. Neither list answersmeta.partial. An unavailable agent store answers500, never an empty list. - Not offered. Cancelling, retrying or answering delegated work stays out of the API.
Common workflow
Create a new agent and fetch its A2A discovery card:switches:use), then verify:
Related
- Agents overview — conceptual background on agent definitions, prompts, and tools
- Agent lifecycle — status states and transitions
- Native HTTP quickstart — call these endpoints with
fetchand a bearer token - MCP Server — Discover before calling — the agent reads listed for AI agents; other agent operations go through
forge_call_operation

