> ## 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.

# Create a task

> TaskCreate creates a new task in an agent's checklist.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/agent/task/create
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/task/create:
    post:
      tags:
        - MurmurService
      summary: Create a task
      description: TaskCreate creates a new task in an agent's checklist.
      operationId: MurmurService_TaskCreate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/murmurApiV1TaskCreateRequest'
        required: true
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1TaskCreateResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googleRpcStatus'
components:
  schemas:
    murmurApiV1TaskCreateRequest:
      type: object
      properties:
        agentId:
          $ref: '#/components/schemas/v1AgentId'
        task:
          $ref: '#/components/schemas/murmurAgentV1TaskCreateRequest'
    v1TaskCreateResponse:
      type: object
      properties:
        taskId:
          type: string
      description: TaskCreateResponse returns the ID of the newly created task.
    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.
    murmurAgentV1TaskCreateRequest:
      type: object
      properties:
        subject:
          type: string
        description:
          type: string
        activation:
          $ref: '#/components/schemas/v1TaskActivation'
      description: Creates a new task on the agent's checklist.
    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
    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.
    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_<key_id>.<secret>'

````