Resource guide

An agent is a folder that shapes its sessions

Agent registration marks a workspace folder as an agent with a stable slug. An optional name is the human-facing label; when it is unset, clients display the registered folder name. An optional icon is a safe path relative to that folder, such as icon.png or assets/icon.png—not an image URL or embedded bytes. The folder's contents are the agent's behavior: an AGENTS.md file is its system prompt, an .agents/skills directory holds its own skills, and an agent.json file may configure an onboarding experience, whether the agent is trainable, and a suggestedFirstMessage — text the agent's empty default chat opens with, shown as a message from the agent; a client may send it with the user's first message, and creation then records it as the agent's first message in the session's history, quoted to the agent so the user's reply lands in context. Any session whose working directory resolves to this folder (or a descendant) adopts that prompt, those skills, and a memory store isolated to the agent. Identity belongs to the registration, not to the files: never write a slug, id, or path into agent.json.

{
  "path": "agents/investor-update",
  "slug": "investor-update",
  "name": "Investor Update",
  "icon": "icon.png"
}

Sessions resolve to the nearest agent

A session belongs to the agent that is the nearest registered ancestor of its working directory; a session started at the drive root belongs to the default agent and behaves exactly as before agents existed. The session records which agent it resolved to, so clients can attribute a session to its agent without re-deriving it. That attribution is a snapshot taken when the session is created: renaming or deleting an agent later never rewrites the history of sessions it already ran.

Each registered agent also has its own server-resolved default session alias. Its first message starts the session at the agent anchor, so ordinary cwd attribution binds it to that agent; it never shares identity with the separate drive-root default. As with the root alias, reads are lazy and permanent session deletion clears the binding.

The default agent has a name too

The drive root is an agent like any other, and it can be renamed — but it has no registration to carry the name, so the name lives on the workspace and the rename is addressed at the reserved slug root rather than a registration's own. root is reserved in every namespace for exactly this reason: no workspace, app, publish, or agent may claim it, so the address can never be ambiguous. Everything else about the default agent reads the same as a registered one.

Reconcile, do not duplicate

List existing agents before creating one from automation. Metadata updates change name and icon on the existing slug and never touch the folder's path identity. Registering a path that is already an agent updates only the fields the request carries: an omitted name or icon keeps the stored one rather than clearing it, so a re-registration cannot silently undo a rename. There is no way to clear a name back to the slug — send the name you want. Deleting an agent removes the registration but deliberately leaves the agent's isolated memory and logs in place, so a re-registration at the same path can resume its history. Disable an agent when it should stay registered but stop shaping new sessions. Disablement removes the agent from future launch resolution without stopping sessions that are already running; re-enabling it restores launch resolution. Use deletion only when the registration itself should disappear.

Shared agents arrive as replicas

Sharing an agent's folder materializes a replica agent in the recipient's workspace, tagged with its origin, running on the recipient's own computer. A replica starts with fresh, empty observational memory. The agent's curated .agents/memories files are ordinary shared content and travel with the folder, while its private observational memory and logs never do. Treat a replica as read-through configuration that converges to the origin, not something to edit in place, and expect origin edits to fan out to it automatically.

Onboarding gates an agent until its workspace completes it

An agent that needs setup before it is useful declares onboarding in agent.json. Until the workspace marks that agent onboarded, clients collapse it to a single onboarding action; the agent's sessions and apps stay out of reach, while training and management do not. Two kinds exist. {"kind":"chat"} runs a conversation whose system prompt is assembled from two layers: the agent's optional ONBOARDING.md, then a Duet-owned block that instructs the agent to mark itself onboarded once the interview is complete — but never on its first turn and never before the user has replied at least once, so a thin or missing ONBOARDING.md cannot produce an agent that unlocks itself before the user has said anything. ONBOARDING.md is optional like AGENTS.md; what never happens is a fall back to AGENTS.md, which would run the agent's ordinary persona while the user believes they are being onboarded. {"kind":"app","app":"<path>"} opens one of the agent's own apps, addressed by a path relative to the agent folder — never an app slug, because a replica's slug may be suffixed to avoid a collision while its path is preserved. Such an app is hidden once onboarding completes unless it sets hideAfterOnboarded to false, and it stays reachable by direct link either way.

An app onboarding cannot connect an integration. Every provider's authorization page refuses to render in an iframe, and an onboarding app runs inside one, so the page can only open a separate browser tab — which returns to the app's own address rather than into the product, stranding the user on a bare copy of the app. Connections belong to a chat onboarding, whose script hands the user an authorize URL built with a redirectTo path inside the product. Reserve app onboarding for settings, inputs, and uploads a page genuinely handles better than a conversation.

Whichever kind runs, it ends by calling the onboarded endpoint itself; that call is what reveals the full agent, and nothing else performs it. A chat onboarding does not write that instruction itself — Duet appends it as a system-prompt block after ONBOARDING.md, already resolved to that agent — so ONBOARDING.md is purely the interview. Stating precisely what counts as done is what keeps an agent from completing before the user has supplied anything. An onboarding app has no session and no agent slug, so it completes through its own route addressed by nothing but its credential — Duet resolves which agent's folder the app lives in — and it must declare the agents scope to hold it. Onboarding conversations are ordinary resumable sessions that no list or search returns, and reopening the action returns to the same one rather than starting another.

Completion is per workspace and never travels across a share: each recipient of a shared agent onboards their own replica, and neither side's completion affects the other. Adding onboarding to an agent that is already installed elsewhere therefore re-locks it for every workspace that has not completed it. "trainable": false is the companion setting, removing the training surface for agents that have no use for it; it changes no memory behavior, and the default agent is always trainable.

{
  "onboarded": true
}

Keep policy on the server

The agents scope permits access to this resource but does not replace workspace roles. Viewers can list and inspect agents; editors can register, rename, disable, re-enable, and delete them. Configure agent behavior by writing the folder's AGENTS.md, .agents/skills, and agent.json through the files API—those are ordinary workspace content—rather than through this resource, which owns only the registration.

Agents

19 operations

GET/v1/ws/{workspaceSlug}/agents

List workspace agents

Scope: ws:{workspaceSlug}:agents
Request: No JSON request body
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "anchorId": { "type": "string" }, "anchorPath": { "type": "string", "minLength": 1 }, "anchorState": { "type": "string", "enum": [ "active", "broken", "orphaned" ] }, "slug": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[^[\\]<>`\\p{Cc}]*$" }, "icon": { "type": "string" }, "sourceShareId": { "type": "string" }, "sourceAgentId": { "type": "string" }, "listingSubscriptionId": { "type": "string" }, "disabledAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "onboardedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "updatedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "workspaceId", "anchorId", "anchorPath", "anchorState", "slug", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "agents" ], "additionalProperties": false }
Delivery: Standard response
Retry: Not declared idempotent

POST/v1/ws/{workspaceSlug}/agents

Scope: ws:{workspaceSlug}:agents
Request: Request JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "slug": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[^[\\]<>`\\p{Cc}]*$" }, "icon": { "type": "string" }, "apps": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "slug": { "type": "string" }, "command": { "type": "string", "minLength": 1 }, "apiScopes": { "type": "array", "items": { "type": "string", "enum": [ "files:read", "files:write", "memory", "sessions", "agents", "services", "integrations", "apps", "share", "publish", "members" ] } }, "installCommand": { "type": "string", "minLength": 1 }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "icon": { "type": "string" } }, "required": [ "path", "slug", "command", "apiScopes" ] } } }, "required": [ "path", "slug" ] }
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "anchorId": { "type": "string" }, "anchorPath": { "type": "string", "minLength": 1 }, "anchorState": { "type": "string", "enum": [ "active", "broken", "orphaned" ] }, "slug": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[^[\\]<>`\\p{Cc}]*$" }, "icon": { "type": "string" }, "sourceShareId": { "type": "string" }, "sourceAgentId": { "type": "string" }, "listingSubscriptionId": { "type": "string" }, "disabledAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "onboardedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "updatedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "workspaceId", "anchorId", "anchorPath", "anchorState", "slug", "createdAt", "updatedAt" ], "additionalProperties": false }, "apps": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "path": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "created", "updated", "unchanged" ] } }, "required": [ "slug", "path", "status" ], "additionalProperties": false } } }, "required": [ "agent", "apps" ], "additionalProperties": false }
Delivery: Standard response
Retry: Not declared idempotent

PATCH/v1/ws/{workspaceSlug}/agents/root

Rename the default agent (the drive root's own agent)

Scope: ws:{workspaceSlug}:agents
Request: Request JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[^[\\]<>`\\p{Cc}]*$" } }, "required": [ "name" ] }
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[^[\\]<>`\\p{Cc}]*$" } }, "required": [ "name" ], "additionalProperties": false }
Delivery: Standard response
Retry: Not declared idempotent

PATCH/v1/ws/{workspaceSlug}/agents/{agentSlug}

Update agent display metadata

Scope: ws:{workspaceSlug}:agents
Request: Request JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[^[\\]<>`\\p{Cc}]*$" }, "icon": { "type": "string" } } }
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "anchorId": { "type": "string" }, "anchorPath": { "type": "string", "minLength": 1 }, "anchorState": { "type": "string", "enum": [ "active", "broken", "orphaned" ] }, "slug": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[^[\\]<>`\\p{Cc}]*$" }, "icon": { "type": "string" }, "sourceShareId": { "type": "string" }, "sourceAgentId": { "type": "string" }, "listingSubscriptionId": { "type": "string" }, "disabledAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "onboardedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "updatedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "workspaceId", "anchorId", "anchorPath", "anchorState", "slug", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "agent" ], "additionalProperties": false }
Delivery: Standard response
Retry: Not declared idempotent

POST/v1/ws/{workspaceSlug}/agents/{agentSlug}/disabled

Disable or re-enable an agent for future session launches

Scope: ws:{workspaceSlug}:agents
Request: Request JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "disabled": { "type": "boolean" } }, "required": [ "disabled" ] }
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "anchorId": { "type": "string" }, "anchorPath": { "type": "string", "minLength": 1 }, "anchorState": { "type": "string", "enum": [ "active", "broken", "orphaned" ] }, "slug": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[^[\\]<>`\\p{Cc}]*$" }, "icon": { "type": "string" }, "sourceShareId": { "type": "string" }, "sourceAgentId": { "type": "string" }, "listingSubscriptionId": { "type": "string" }, "disabledAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "onboardedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "updatedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "workspaceId", "anchorId", "anchorPath", "anchorState", "slug", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "agent" ], "additionalProperties": false }
Delivery: Standard response
Retry: Declared idempotent

POST/v1/ws/{workspaceSlug}/agents/{agentSlug}/onboarded

Mark this workspace's copy of an agent onboarded, or clear it to re-onboard

Scope: ws:{workspaceSlug}:agents
Request: Request JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "onboarded": { "type": "boolean" } }, "required": [ "onboarded" ] }
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "anchorId": { "type": "string" }, "anchorPath": { "type": "string", "minLength": 1 }, "anchorState": { "type": "string", "enum": [ "active", "broken", "orphaned" ] }, "slug": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[^[\\]<>`\\p{Cc}]*$" }, "icon": { "type": "string" }, "sourceShareId": { "type": "string" }, "sourceAgentId": { "type": "string" }, "listingSubscriptionId": { "type": "string" }, "disabledAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "onboardedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "updatedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "workspaceId", "anchorId", "anchorPath", "anchorState", "slug", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "agent" ], "additionalProperties": false }
Delivery: Standard response
Retry: Declared idempotent

POST/v1/ws/{workspaceSlug}/agent/sessions/{sessionId}/onboarded

Mark the session's agent onboarded from inside its onboarding conversation

Scope: ws:{workspaceSlug}:agents
Request: Request JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "onboarded": { "type": "boolean" } }, "required": [ "onboarded" ] }
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "anchorId": { "type": "string" }, "anchorPath": { "type": "string", "minLength": 1 }, "anchorState": { "type": "string", "enum": [ "active", "broken", "orphaned" ] }, "slug": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[^[\\]<>`\\p{Cc}]*$" }, "icon": { "type": "string" }, "sourceShareId": { "type": "string" }, "sourceAgentId": { "type": "string" }, "listingSubscriptionId": { "type": "string" }, "disabledAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "onboardedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "updatedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "workspaceId", "anchorId", "anchorPath", "anchorState", "slug", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "agent" ], "additionalProperties": false }
Delivery: Standard response
Retry: Declared idempotent

POST/v1/ws/{workspaceSlug}/app/onboarded

Mark the calling app's own agent onboarded, addressed by the app's credential

Scope: ws:{workspaceSlug}:agents
Request: Request JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "onboarded": { "type": "boolean" } }, "required": [ "onboarded" ] }
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "anchorId": { "type": "string" }, "anchorPath": { "type": "string", "minLength": 1 }, "anchorState": { "type": "string", "enum": [ "active", "broken", "orphaned" ] }, "slug": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[^[\\]<>`\\p{Cc}]*$" }, "icon": { "type": "string" }, "sourceShareId": { "type": "string" }, "sourceAgentId": { "type": "string" }, "listingSubscriptionId": { "type": "string" }, "disabledAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "onboardedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "updatedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "workspaceId", "anchorId", "anchorPath", "anchorState", "slug", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "agent" ], "additionalProperties": false }
Delivery: Standard response
Retry: Declared idempotent

POST/v1/ws/{workspaceSlug}/agents/{agentSlug}/onboarding-session

Open this workspace's onboarding conversation for an agent, creating it if needed

Scope: ws:{workspaceSlug}:sessions
Request: No request body
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "sessionId": { "type": "string", "minLength": 1 } }, "required": [ "sessionId" ], "additionalProperties": false }
Delivery: Standard response
Retry: Declared idempotent

DELETE/v1/ws/{workspaceSlug}/agents/{agentSlug}

Unregister an agent while preserving its local state

Scope: ws:{workspaceSlug}:agents
Request: No JSON request body
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ], "additionalProperties": false }
Delivery: Standard response
Retry: Declared idempotent

GET/v1/ws/{workspaceSlug}/marketplace/subscriptions

List marketplace agent subscriptions for a workspace.

Scope: ws:{workspaceSlug}:agents
Request: No JSON request body
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subscriptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "agentId": { "type": "string", "minLength": 1 }, "anchorId": { "type": "string", "minLength": 1 }, "listingId": { "type": "string", "minLength": 1 }, "agentName": { "type": "string" }, "path": { "type": "string" }, "mode": { "type": "string", "enum": [ "subscribe", "clone_once" ] }, "state": { "type": "string", "enum": [ "installing", "active", "error", "detached" ] }, "appliedEtag": { "type": "string", "minLength": 1 }, "acknowledgedEtag": { "type": "string", "minLength": 1 }, "lastAppliedAt": { "type": "number", "minimum": 0 }, "lastErrorCode": { "type": "string", "minLength": 1 } }, "required": [ "id", "listingId", "agentName", "path", "mode", "state" ], "additionalProperties": false } } }, "required": [ "subscriptions" ], "additionalProperties": false }
Delivery: Standard response
Retry: Not declared idempotent

POST/v1/ws/{workspaceSlug}/listings

Offer one of this workspace's agents on the marketplace.

Scope: ws:{workspaceSlug}:agents
Request: Request JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agentSlug": { "type": "string" }, "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "agentSlug" ] }
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "listing": { "type": "object", "properties": { "_id": { "type": "string", "minLength": 1 } }, "required": [ "_id" ], "additionalProperties": {} } }, "required": [ "listing" ], "additionalProperties": false }
Errors: Error body JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string", "enum": [ "publishing_disabled", "listing_anchor_subscribed", "listing_already_exists", "reserved_title", "listing_not_found" ] } }, "required": [ "error" ], "additionalProperties": false }
Delivery: Standard response
Retry: Not declared idempotent

DELETE/v1/ws/{workspaceSlug}/listings/{listingId}

Remove a listing from the catalog; existing subscribers keep pulling.

Scope: ws:{workspaceSlug}:agents
Request: No JSON request body
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ], "additionalProperties": false }
Errors: Error body JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string", "enum": [ "publishing_disabled", "listing_anchor_subscribed", "listing_already_exists", "reserved_title", "listing_not_found" ] } }, "required": [ "error" ], "additionalProperties": false }
Delivery: Standard response
Retry: Declared idempotent

POST/v1/ws/{workspaceSlug}/marketplace/subscriptions

Install a marketplace listing and synchronously pull it.

Scope: ws:{workspaceSlug}:agents
Request: Request JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "listingId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[^[\\]<>`\\p{Cc}]*$" }, "path": { "type": "string" } }, "required": [ "listingId" ] }
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subscription": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "agentId": { "type": "string", "minLength": 1 }, "anchorId": { "type": "string", "minLength": 1 }, "listingId": { "type": "string", "minLength": 1 }, "agentName": { "type": "string" }, "path": { "type": "string" }, "mode": { "type": "string", "enum": [ "subscribe", "clone_once" ] }, "state": { "type": "string", "enum": [ "installing", "active", "error", "detached" ] }, "appliedEtag": { "type": "string", "minLength": 1 }, "acknowledgedEtag": { "type": "string", "minLength": 1 }, "lastAppliedAt": { "type": "number", "minimum": 0 }, "lastErrorCode": { "type": "string", "minLength": 1 } }, "required": [ "id", "listingId", "agentName", "path", "mode", "state" ], "additionalProperties": false } }, "required": [ "subscription" ], "additionalProperties": false }
Errors: Error body JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "const": "path_exists" }, "path": { "type": "string" }, "renameRequired": { "type": "boolean", "const": true } }, "required": [ "error", "path", "renameRequired" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string", "const": "agent_limit_exceeded" } }, "required": [ "error" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string", "const": "pull_failed" } }, "required": [ "error" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string", "const": "install_failed" } }, "required": [ "error" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string", "const": "listing_unavailable" } }, "required": [ "error" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string", "const": "listing_removed" } }, "required": [ "error" ], "additionalProperties": false } ] }
Delivery: Standard response
Retry: Not declared idempotent

POST/v1/ws/{workspaceSlug}/onboarding

Complete one-time workspace onboarding and install optional starter agents.

Scope: ws:{workspaceSlug}:agents
Request: Request JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "anyOf": [ { "type": "object", "properties": { "duetName": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[^[\\]<>`\\p{Cc}]*$" }, "purpose": { "type": "string", "minLength": 1, "maxLength": 1000 }, "goal": { "type": "string", "minLength": 1, "maxLength": 100 }, "selectedNames": { "maxItems": 50, "type": "array", "items": { "type": "string" } } }, "required": [ "duetName", "selectedNames" ] }, { "type": "object", "properties": { "duetName": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[^[\\]<>`\\p{Cc}]*$" }, "purpose": { "type": "string", "minLength": 1, "maxLength": 1000 }, "goal": { "type": "string", "minLength": 1, "maxLength": 100 }, "skip": { "type": "boolean", "const": true } }, "required": [ "duetName", "skip" ] } ] }
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "duetName": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[^[\\]<>`\\p{Cc}]*$" }, "onboardedAt": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "results": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "ok": { "type": "boolean", "const": true }, "subscription": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "agentId": { "type": "string", "minLength": 1 }, "anchorId": { "type": "string", "minLength": 1 }, "listingId": { "type": "string", "minLength": 1 }, "agentName": { "type": "string" }, "path": { "type": "string" }, "mode": { "type": "string", "enum": [ "subscribe", "clone_once" ] }, "state": { "type": "string", "enum": [ "installing", "active", "error", "detached" ] }, "appliedEtag": { "type": "string", "minLength": 1 }, "acknowledgedEtag": { "type": "string", "minLength": 1 }, "lastAppliedAt": { "type": "number", "minimum": 0 }, "lastErrorCode": { "type": "string", "minLength": 1 } }, "required": [ "id", "listingId", "agentName", "path", "mode", "state" ], "additionalProperties": false } }, "required": [ "name", "ok", "subscription" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string" }, "ok": { "type": "boolean", "const": false }, "campaign": { "type": "boolean", "const": true }, "failure": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "const": "path_exists" }, "path": { "type": "string" }, "renameRequired": { "type": "boolean", "const": true } }, "required": [ "error", "path", "renameRequired" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string", "const": "agent_limit_exceeded" } }, "required": [ "error" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string", "const": "pull_failed" } }, "required": [ "error" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string", "const": "install_failed" } }, "required": [ "error" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string", "const": "listing_unavailable" } }, "required": [ "error" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string", "const": "listing_removed" } }, "required": [ "error" ], "additionalProperties": false } ] } }, "required": [ "name", "ok", "failure" ], "additionalProperties": false } ] } }, "pullError": { "type": "string", "const": "pull_failed" } }, "required": [ "duetName", "onboardedAt", "results" ], "additionalProperties": false }
Delivery: Standard response
Retry: Not declared idempotent

POST/v1/ws/{workspaceSlug}/onboarding/recommendations

Recommend four official agents for the stated workspace purpose; empty when no confident pick exists.

Scope: ws:{workspaceSlug}:agents
Request: Request JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "purpose": { "type": "string", "minLength": 1, "maxLength": 1000 }, "tagHints": { "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "sales", "marketing", "engineering", "customer-support", "operations", "people", "product", "personal" ] } } }, "required": [ "purpose" ] }
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "recommendations": { "anyOf": [ { "minItems": 4, "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "agentName": { "type": "string" }, "reason": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "agentName", "reason" ], "additionalProperties": false } }, { "minItems": 0, "maxItems": 0, "type": "array", "items": { "type": "object", "properties": { "agentName": { "type": "string" }, "reason": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "agentName", "reason" ], "additionalProperties": false } } ] } }, "required": [ "recommendations" ], "additionalProperties": false }
Delivery: Standard response
Retry: Not declared idempotent

POST/v1/ws/{workspaceSlug}/marketplace/subscriptions/clone

Clone a marketplace listing once into a caller-chosen path.

Scope: ws:{workspaceSlug}:agents
Request: Request JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "listingId": { "type": "string", "minLength": 1 }, "path": { "type": "string" } }, "required": [ "listingId", "path" ] }
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subscription": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "agentId": { "type": "string", "minLength": 1 }, "anchorId": { "type": "string", "minLength": 1 }, "listingId": { "type": "string", "minLength": 1 }, "agentName": { "type": "string" }, "path": { "type": "string" }, "mode": { "type": "string", "enum": [ "subscribe", "clone_once" ] }, "state": { "type": "string", "enum": [ "installing", "active", "error", "detached" ] }, "appliedEtag": { "type": "string", "minLength": 1 }, "acknowledgedEtag": { "type": "string", "minLength": 1 }, "lastAppliedAt": { "type": "number", "minimum": 0 }, "lastErrorCode": { "type": "string", "minLength": 1 } }, "required": [ "id", "listingId", "agentName", "path", "mode", "state" ], "additionalProperties": false } }, "required": [ "subscription" ], "additionalProperties": false }
Errors: Error body JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "const": "path_exists" }, "path": { "type": "string" }, "renameRequired": { "type": "boolean", "const": true } }, "required": [ "error", "path", "renameRequired" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string", "const": "agent_limit_exceeded" } }, "required": [ "error" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string", "const": "pull_failed" } }, "required": [ "error" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string", "const": "install_failed" } }, "required": [ "error" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string", "const": "listing_unavailable" } }, "required": [ "error" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string", "const": "listing_removed" } }, "required": [ "error" ], "additionalProperties": false } ] }
Delivery: Standard response
Retry: Not declared idempotent

POST/v1/ws/{workspaceSlug}/marketplace/subscriptions/{subscriptionId}/acknowledge

Acknowledge the currently applied version of a subscription.

Scope: ws:{workspaceSlug}:agents
Request: No request body
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subscription": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "agentId": { "type": "string", "minLength": 1 }, "anchorId": { "type": "string", "minLength": 1 }, "listingId": { "type": "string", "minLength": 1 }, "agentName": { "type": "string" }, "path": { "type": "string" }, "mode": { "type": "string", "enum": [ "subscribe", "clone_once" ] }, "state": { "type": "string", "enum": [ "installing", "active", "error", "detached" ] }, "appliedEtag": { "type": "string", "minLength": 1 }, "acknowledgedEtag": { "type": "string", "minLength": 1 }, "lastAppliedAt": { "type": "number", "minimum": 0 }, "lastErrorCode": { "type": "string", "minLength": 1 } }, "required": [ "id", "listingId", "agentName", "path", "mode", "state" ], "additionalProperties": false } }, "required": [ "subscription" ], "additionalProperties": false }
Delivery: Standard response
Retry: Declared idempotent

DELETE/v1/ws/{workspaceSlug}/marketplace/subscriptions/{subscriptionId}

Detach a marketplace subscription while preserving local files.

Scope: ws:{workspaceSlug}:agents
Request: No JSON request body
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ], "additionalProperties": false }
Delivery: Standard response
Retry: Declared idempotent