> ## Documentation Index > Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt > Use this file to discover all available pages before exploring further. # Spawn an agent > Spawn starts an agent task. If the agent is already running, returns AlreadyExists — use QueueAdd to send a follow-up instead. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/agent/spawn openapi: 3.0.0 info: title: Murmur REST API description: >- PRE-ALPHA: INTERFACE SUBJECT TO CHANGE WITHOUT NOTICE. The murmur REST API lets you spawn agents, track their progress, manage their task lists, and read and write catalog resources from any HTTP client. version: v1 servers: - url: https://api.murmur.dev security: - ApiKey: [] tags: - name: MurmurService paths: /v1/agent/spawn: post: tags: - MurmurService summary: Spawn an agent description: >- Spawn starts an agent task. If the agent is already running, returns AlreadyExists — use QueueAdd to send a follow-up instead. operationId: MurmurService_Spawn requestBody: content: application/json: schema: $ref: '#/components/schemas/murmurApiV1SpawnRequest' required: true responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/murmurApiV1SpawnResponse' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/googleRpcStatus' components: schemas: murmurApiV1SpawnRequest: type: object properties: agentId: $ref: '#/components/schemas/v1AgentId' description: type: string serviceProfile: type: string description: >- Service profile name. When set, the agent runs with the named service profile's identity and credentials (a bot spawn). When empty, the agent runs as the calling developer. gitName: type: string description: >- Git identity — optional. Defaults to the caller's stored profile, then the caller's username. gitEmail: type: string sshPublicKeys: type: array items: type: string plaintextSecrets: type: object additionalProperties: type: string description: >- Plaintext secrets, keyed by environment-variable name. The server encrypts them and merges them into the agent's secrets ahead of every other source. Highest precedence. idleTimeout: type: string model: type: string fastMode: type: boolean codingAgent: type: string backend: type: string skipChecks: type: array items: type: string suggestTerminateMode: $ref: '#/components/schemas/v1SuggestTerminateMode' resurrect: type: boolean appendSystemPrompt: type: string forkFrom: type: string forceNew: type: boolean tasks: type: array items: $ref: '#/components/schemas/v1Task' expectedOutput: type: string description: |- Expected output artifact. Free-form — known shorthands are expanded into agent behavior: "pr" → open a pull request "push" → push changes, no PR "respond" → just respond, no code changes "diff" → produce a diff, no commit "report" → produce a written report "none" → no artifact expected Anything else flows through to the agent verbatim. parentAgentId: $ref: '#/components/schemas/v1AgentId' agentConfig: $ref: '#/components/schemas/v1AgentConfig' sessionMode: $ref: '#/components/schemas/v1SessionMode' completionCheck: $ref: '#/components/schemas/v1CompletionCheck' onIdle: $ref: '#/components/schemas/v1OnIdle' dequeueStrategy: $ref: '#/components/schemas/v1DequeueStrategy' repos: type: array items: $ref: '#/components/schemas/murmurAgentV1Repo' description: >- Per-repo branch overrides and/or additional repos to clone. Entries matching workspace repos override their branch config. Entries not matching any workspace repo are extraneous repos to clone. branch: type: string description: |- Working branch for every repo in this spawn. Applied after workspace repos are resolved — per-repo overrides (repos[].branch) take precedence when both are set. purpose: type: string description: |- One-sentence human-readable goal for this agent. Displayed in the dashboard for context. Not interpreted by the system. Max 240 chars. reasoningEffort: type: string reasoningSummary: type: string verbosity: type: string serviceTier: type: string suppressedEventClasses: type: array items: $ref: '#/components/schemas/v1FollowUpEventClass' description: >- Follow-up event classes the spawned agent ignores, enforced at event delivery. Empty (the default) means react to every class. Must not contain FOLLOW_UP_EVENT_CLASS_UNSPECIFIED. tags: type: array items: type: string description: >- Tags to attach to the spawned agent, each a tag name (e.g. "release-blocker") or any text that slugifies to one (e.g. "Release Blocker"). A reference matching an existing tag attaches it; one matching none creates it. Max 8; duplicate-free. outputSchema: type: string description: >- Optional JSON Schema (as a JSON document) constraining the agent's structured output. When set, the agent's task answer is returned as the schema-validated `result` member of the canonical {response, needs_input, result} envelope and surfaced on AgentTaskOutput.structured_output. Empty = the platform default envelope ({response, needs_input}) with no result. Validated at spawn time; a malformed schema is rejected with InvalidArgument. lifecycleConsumers: type: array items: $ref: '#/components/schemas/v1LifecycleConsumerBinding' description: >- Lifecycle-event consumers to attach to the agent. Each consumer kind may appear at most once. imageRef: type: string description: >- Catalog image name (e.g. "python-a1b2c3d4e5f67890"). When set, this agent's VM boots from this image instead of the workspace default. The image must exist and be bootable on the workspace's placement substrate. Not inherited on resurrect — pass it again. disableCurrentBranchForking: type: boolean description: >- Child spawns only: disables the default of basing each inherited repo on the parent's checked-out working branch. When set, each inherited repo resolves to its default branch at clone — the same base a top-level spawn gets — so a parent can spawn a child without pushing its working branch first. A top-level spawn rejects it. murmurApiV1SpawnResponse: type: object properties: agentId: $ref: '#/components/schemas/v1AgentId' shortId: type: string dashboardUrl: type: string description: >- Dashboard URL for the spawned agent. Empty when the server has no public URL configured. googleRpcStatus: type: object properties: code: type: integer format: int32 description: >- Numeric status code for the failure, matching the HTTP status of the response via the standard mapping (e.g. 3 INVALID_ARGUMENT → 400, 5 NOT_FOUND → 404, 7 PERMISSION_DENIED → 403, 16 UNAUTHENTICATED → 401). message: type: string description: Human-readable description of what caused the failure. details: type: array items: $ref: '#/components/schemas/protobufAny' description: >- Machine-readable error details, when the failure carries them. Usually empty. description: The error envelope returned on every non-2xx response. v1AgentId: type: object properties: tenant: $ref: '#/components/schemas/v1Tenant' ownerProvider: $ref: '#/components/schemas/v1Provider' account: type: string description: >- Owner account: username for identity-provider owners, service-profile name for PROVIDER_SERVICE_PROFILE. agent: type: array items: type: string title: |- Agent path — the hierarchy from root to leaf. Root agent: ["fix-bug"] Child: ["fix-bug", "api"] Grandchild: ["fix-bug", "api", "tests"] workspace: type: string description: >- Workspace this agent belongs to; scopes its repos, environment, and base branches. Optional at spawn: when empty, the server selects one, so a returned AgentId always carries a concrete workspace. description: >- Identifies an agent. The identity is (tenant, workspace, owner, agent path); the workspace scopes the agent's repos, environment, and base branches. v1SuggestTerminateMode: type: string enum: - SUGGEST_TERMINATE_MODE_UNSPECIFIED - SUGGEST_TERMINATE_MODE_SUGGEST - SUGGEST_TERMINATE_MODE_IMMEDIATE default: SUGGEST_TERMINATE_MODE_UNSPECIFIED description: >- - SUGGEST_TERMINATE_MODE_UNSPECIFIED: inherit (workspace, then the SUGGEST default) - SUGGEST_TERMINATE_MODE_SUGGEST: advisory only: the dashboard renders a delete button; a human decides - SUGGEST_TERMINATE_MODE_IMMEDIATE: terminate the agent immediately, no delete button v1Task: type: object properties: id: type: string subject: type: string description: type: string status: $ref: '#/components/schemas/v1TaskStatus' blocks: type: array items: type: string title: IDs of tasks this task blocks blockedBy: type: array items: type: string title: IDs of tasks that block this task activation: $ref: '#/components/schemas/v1TaskActivation' persona: type: string description: >- Name of the persona that contributed this task (e.g. "programmer"). Empty for tasks from the spawn request, follow-ups, or task_create. A persona switch removes exactly the persona-tagged tasks and adds the new persona's, leaving all untagged tasks in place. dedupKey: type: string description: >- Stable identity of the external object this task tracks (e.g. a PR review thread). Tasks with the same key are de-duplicated within one delivery batch. Empty for caller-created tasks, which are never de-duplicated. ephemeral: type: boolean description: >- Ephemeral tasks live for exactly one run: created with the follow-up that delivers them and removed when that run completes. Set by the platform on per-thread PR comment and review tasks. description: A checklist item on the agent's task list. v1AgentConfig: type: object properties: name: type: string title: agent persona name (e.g. "programmer") prompt: type: string title: system prompt (markdown body of the agent file) description: type: string title: short description of the agent's role model: type: string title: model override (e.g. "claude-sonnet-4-6") tools: type: array items: type: string title: allowed tools disallowedTools: type: array items: type: string title: disallowed tools maxTurns: type: integer format: int32 title: max conversation turns personaCategory: type: string title: arbitrary display category; empty when uncategorized description: >- An agent persona definition: system prompt, model, and tool configuration. v1SessionMode: type: string enum: - SESSION_MODE_UNSPECIFIED - SESSION_MODE_AUTONOMOUS - SESSION_MODE_STREAMING default: SESSION_MODE_UNSPECIFIED description: |- SessionMode determines how the agent's coding session is executed. - SESSION_MODE_AUTONOMOUS: The agent runs each turn to completion and returns structured output. - SESSION_MODE_STREAMING: Long-lived interactive session; follow-ups stream into the live session. v1CompletionCheck: type: string enum: - COMPLETION_CHECK_UNSPECIFIED - COMPLETION_CHECK_NONE - COMPLETION_CHECK_ASSESSOR default: COMPLETION_CHECK_UNSPECIFIED description: |- CompletionCheck determines whether the agent re-checks completion after a task finishes, before entering idle behavior. - COMPLETION_CHECK_NONE: Proceed directly to idle behavior. - COMPLETION_CHECK_ASSESSOR: Fork session, run completion assessor up to 3 times. v1OnIdle: type: string enum: - ON_IDLE_UNSPECIFIED - ON_IDLE_SLEEP - ON_IDLE_TERMINATE - ON_IDLE_KEEP_ALIVE default: ON_IDLE_UNSPECIFIED description: |- OnIdle determines what happens when the agent has no more work after task completion (and optional completion check). - ON_IDLE_SLEEP: Hibernate/suspend VM, wait for follow-up or cancel. - ON_IDLE_TERMINATE: End the agent and destroy its VM. - ON_IDLE_KEEP_ALIVE: VM stays running, session stays live. Periodic session backup every 30m. v1DequeueStrategy: type: string enum: - DEQUEUE_STRATEGY_UNSPECIFIED - DEQUEUE_STRATEGY_ALL - DEQUEUE_STRATEGY_ONE - DEQUEUE_STRATEGY_FIVE - DEQUEUE_STRATEGY_AUTO default: DEQUEUE_STRATEGY_UNSPECIFIED description: |- Controls how queued follow-up messages are drained between agent turns. - DEQUEUE_STRATEGY_UNSPECIFIED: Default: AUTO. - DEQUEUE_STRATEGY_ALL: Drain all queued follow-ups into one batch. - DEQUEUE_STRATEGY_ONE: Drain one follow-up per turn. - DEQUEUE_STRATEGY_FIVE: Drain up to five follow-ups per turn. - DEQUEUE_STRATEGY_AUTO: Drain up to five follow-ups of one kind per turn — manual follow-ups and auto-generated events are never delivered in the same turn (kind-boundary batching, capped at five). murmurAgentV1Repo: type: object properties: cloneUrl: type: string title: canonical clone URL (always HTTPS, no .git suffix); the PR head repo baseBranch: type: string title: >- base branch on the base repo (base_clone_url when set, else clone_url) — what the PR targets and the working branch is cut from branch: type: string title: working branch the agent operates on branchCreated: type: boolean description: >- True when the platform created the working branch for this run, rather than adopting an existing one. conflictResolution: $ref: '#/components/schemas/v1ConflictResolution' baseCloneUrl: type: string description: >- Optional base repo: the repo the PR is opened against. Empty ⇒ a same-repo PR against clone_url's own base_branch (the default). When set ⇒ a cross-repo PR whose head is (clone_url, branch) and whose base is (base_clone_url, base_branch); clone_url must be a fork of base_clone_url (GitHub permits cross-repo PRs only within a fork network). Event routing (branch/file topics, commit/PR records) and the working branch's base both key to base_clone_url. description: >- A repository and its branch configuration. In workspace catalog entries, clone_url and base_branch are set. On spawn requests, only clone_url is required — an empty base_branch resolves to the repo's default branch. On statuses, all fields are populated. v1FollowUpEventClass: type: string enum: - FOLLOW_UP_EVENT_CLASS_UNSPECIFIED - FOLLOW_UP_EVENT_CLASS_CI - FOLLOW_UP_EVENT_CLASS_PR_COMMENTS default: FOLLOW_UP_EVENT_CLASS_UNSPECIFIED description: >- A user-suppressible category of follow-up event. Only events that wake an already-running agent are classifiable; spawn-trigger and orchestration events are never suppressible. - FOLLOW_UP_EVENT_CLASS_UNSPECIFIED: not a suppressible event - FOLLOW_UP_EVENT_CLASS_CI: ci_result - FOLLOW_UP_EVENT_CLASS_PR_COMMENTS: pr_comment, pr_review v1LifecycleConsumerBinding: type: object properties: eventClasses: type: array items: $ref: '#/components/schemas/v1SubscriptionClass' description: >- Subscription classes to deliver to this consumer. At least one is required; an event is delivered only when its class is listed. Must not contain SUBSCRIPTION_CLASS_UNSPECIFIED. webhook: $ref: '#/components/schemas/v1WebhookConsumerBinding' description: >- Attaches one lifecycle-event consumer to an agent. The binding is set at spawn and carried for the agent's whole life; each subscribed lifecycle event fans out to the matching consumer. protobufAny: type: object properties: '@type': type: string description: >- Identifies the payload type of this detail value; the remaining properties are that type's fields. additionalProperties: {} description: >- A structured detail value. `@type` identifies the payload type; the remaining properties are that type's fields. v1Tenant: type: object properties: provider: $ref: '#/components/schemas/v1Provider' org: type: string title: username or org name description: |- Tenant identifies an organization within a provider. It is the unit of multi-tenant scoping — all resources (agents, pools, VMs) belong to exactly one tenant. v1Provider: type: string enum: - PROVIDER_UNSPECIFIED - PROVIDER_GITHUB_OAUTH - PROVIDER_GITHUB_APP - PROVIDER_GOOGLE_OIDC - PROVIDER_SERVICE_PROFILE default: PROVIDER_UNSPECIFIED description: |- Provider identifies the identity provider type for a tenant namespace. Each provider is a distinct namespace — no cross-provider mixing. - PROVIDER_GITHUB_OAUTH: the namespace of an individual GitHub user — a single login (human or bot, e.g. "alice"), addressed as github_oauth/{login} - PROVIDER_GITHUB_APP: the org/tenant namespace — its account is the org name (github_app/{org}), never a person - PROVIDER_GOOGLE_OIDC: Google Workspace domain - PROVIDER_SERVICE_PROFILE: owner is a CatalogServiceProfile; account is the profile name v1TaskStatus: type: string enum: - TASK_STATUS_UNSPECIFIED - TASK_STATUS_PENDING - TASK_STATUS_IN_PROGRESS - TASK_STATUS_COMPLETED - TASK_STATUS_DELETED default: TASK_STATUS_UNSPECIFIED description: TaskStatus is the lifecycle state of a checklist task. v1TaskActivation: type: object properties: filesModified: $ref: '#/components/schemas/v1FilesModified' description: >- Defines when a task becomes active. At most one condition may be set; unset means always active. v1ConflictResolution: type: string enum: - CONFLICT_RESOLUTION_UNSPECIFIED - CONFLICT_RESOLUTION_MERGE - CONFLICT_RESOLUTION_REBASE - CONFLICT_RESOLUTION_NONE default: CONFLICT_RESOLUTION_UNSPECIFIED description: |- ConflictResolution determines how file-changed conflicts are resolved. - CONFLICT_RESOLUTION_UNSPECIFIED: catalog default — server treats as MERGE - CONFLICT_RESOLUTION_NONE: opt out of file-changed notifications v1SubscriptionClass: type: string enum: - SUBSCRIPTION_CLASS_UNSPECIFIED - SUBSCRIPTION_CLASS_RESULT - SUBSCRIPTION_CLASS_PHASE - SUBSCRIPTION_CLASS_TASK - SUBSCRIPTION_CLASS_CHILD - SUBSCRIPTION_CLASS_CODE - SUBSCRIPTION_CLASS_CI - SUBSCRIPTION_CLASS_PR - SUBSCRIPTION_CLASS_COST default: SUBSCRIPTION_CLASS_UNSPECIFIED description: >- A category of observer-feed events a lifecycle consumer subscribes to. Classes are disjoint: each event maps to exactly one class. Separate from FollowUpEventClass by design — suppression (what an agent ignores) and subscription (what an observer receives) are different in kind. - SUBSCRIPTION_CLASS_RESULT: Terminal phase transitions: COMPLETED, FAILED, CANCELED. - SUBSCRIPTION_CLASS_PHASE: Non-terminal phase transitions: STARTING, RUNNING, IDLE, SLEEPING, etc. - SUBSCRIPTION_CLASS_TASK: Per-turn task completions with cost/token metrics. - SUBSCRIPTION_CLASS_CHILD: Child agent lifecycle events (spawned, completed, failed). - SUBSCRIPTION_CLASS_CODE: Git operations: commits and pushes. - SUBSCRIPTION_CLASS_CI: CI check results (discovered, passed, failed, timed_out). - SUBSCRIPTION_CLASS_PR: PR opened by this agent (own working branch PR). - SUBSCRIPTION_CLASS_COST: Cost update after each turn (cumulative totals). v1WebhookConsumerBinding: type: object properties: url: type: string description: HTTPS URL where murmur POSTs lifecycle events. Must be https://. callerContext: type: string description: >- Opaque caller context echoed verbatim in every delivery (WebhookEvent.caller_context). Max 4096 bytes. Optional. signingKey: type: string format: byte description: >- Signing key for webhook deliveries, minted by the consumer. Required; must be 32-64 bytes. Request-only: the server encrypts it and discards the plaintext before the binding is persisted. signingKeySha256: type: string format: byte description: >- Server-set: SHA-256 of the signing key. Stamped on each delivery as X-Murmur-Signature-Key-Id so the receiver can pick the right key across a rotation. Never caller-set. description: >- Routes lifecycle events to an external HTTPS endpoint as HMAC-signed POSTs: HMAC-SHA256 over the JSON body, sent as X-Murmur-Signature-256: sha256=. The signing key is required at spawn; a binding without one is rejected. v1FilesModified: type: object properties: pattern: type: string title: glob pattern for file paths; empty = any file description: |- FilesModified activates a task when the agent pushes changes. Run-scoped: evaluated against pushes in the current run only. securitySchemes: ApiKey: type: http scheme: bearer description: 'murmur API key: mur_.' ````