Derive Jobs API

openapi: 3.2.0
info:
  title: Derive Jobs API
  version: 1.0.0
  description: 'Derive''s HTTP API. Every response shape here is the single source of truth for the web client — generated from the same Zod schemas that back this reference, so the docs never drift from the running API.


    **Auth:** a session cookie (browser) or a bearer token (agents and the CLI). Most write routes are scoped to the caller''s active workspace. The `/v1` paths are the stable product surface; `/openapi.json` serves this spec and `/docs` renders it.'
tags:
- name: Jobs
  description: 'One unit of agent work: someone asked, a schedule fired, or a graph opened a node. People ask, follow, answer, cancel, and retry; runners pull and report.'
paths:
  /v1/jobs:
    get:
      tags:
      - Jobs
      summary: List jobs in the active workspace, newest first
      parameters:
      - schema:
          type: string
        required: false
        name: agent
        in: query
      - schema:
          type: string
          description: Only tasks from this trigger; none selects work without a trigger.
        required: false
        description: Only tasks from this trigger; none selects work without a trigger.
        name: trigger
        in: query
      - schema:
          type: string
          description: Comma-separated statuses.
        required: false
        description: Comma-separated statuses.
        name: status
        in: query
      - schema:
          type: string
          description: Comma-separated kinds.
        required: false
        description: Comma-separated kinds.
        name: kind
        in: query
      - schema:
          type: string
        required: false
        name: parent
        in: query
      - schema:
          type: string
          description: 'Keyset cursor: created_at of the last row seen.'
        required: false
        description: 'Keyset cursor: created_at of the last row seen.'
        name: before
        in: query
      - schema:
          type: string
        required: false
        name: limit
        in: query
      - schema:
          type: string
          description: '1: only jobs you asked, or on agents you manage (the inbox).'
        required: false
        description: '1: only jobs you asked, or on agents you manage (the inbox).'
        name: mine
        in: query
      - schema:
          type: string
          description: 'A report page''s short id: the job that report is for.'
        required: false
        description: 'A report page''s short id: the job that report is for.'
        name: report
        in: query
      - schema:
          type: string
          description: 'A page''s short id: only the jobs you asked about that page.'
        required: false
        description: 'A page''s short id: only the jobs you asked about that page.'
        name: subject
        in: query
      responses:
        '200':
          description: Jobs.
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobs:
                    type: array
                    items:
                      $ref: '#/components/schemas/Job'
                required:
                - jobs
      operationId: getV1Jobs
      x-operation-id-source: derived
    post:
      tags:
      - Jobs
      summary: Ask an agent to do something.
      responses:
        '200':
          description: An open job already holding this dedupe key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAsked'
        '201':
          description: The new job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAsked'
      operationId: postV1Jobs
      x-operation-id-source: derived
  /v1/jobs/{id}:
    get:
      tags:
      - Jobs
      summary: One job with its transcript
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      responses:
        '200':
          description: The job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobDetail'
      operationId: getV1JobsById
      x-operation-id-source: derived
  /v1/jobs/{id}/messages:
    post:
      tags:
      - Jobs
      summary: 'Write to a job. Running: appended for the next turn. Settled: the job reopens'
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      responses:
        '200':
          description: The job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobDetail'
      operationId: postV1JobsByIdMessages
      x-operation-id-source: derived
  /v1/jobs/{id}/cancel:
    post:
      tags:
      - Jobs
      summary: Cancel an open job (and its children)
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      responses:
        '200':
          description: The job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
      operationId: postV1JobsByIdCancel
      x-operation-id-source: derived
  /v1/jobs/{id}/attach:
    post:
      tags:
      - Jobs
      summary: Let your SSH key into your running interactive session's machine
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                public_key:
                  type: string
                  pattern: ^(ssh-ed25519|ecdsa-sha2-nistp256|ssh-rsa) [A-Za-z0-9+/=]+( \S+)?$
                  description: An OpenSSH public key. Private keys are refused.
              required:
              - public_key
      responses:
        '200':
          description: Where to connect. Attach with `tmux attach -t derive` once connected.
          content:
            application/json:
              schema:
                anyOf:
                - type: object
                  properties:
                    host:
                      type: string
                    port:
                      type: number
                    user:
                      type: string
                    host_key:
                      type:
                      - string
                      - 'null'
                      description: Pin this in known_hosts.
                    tmux_session:
                      type: string
                  required:
                  - host
                  - port
                  - user
                  - host_key
                  - tmux_session
                - type: object
                  properties:
                    transport:
                      type: string
                      enum:
                      - websocket
                    user:
                      type: string
                      enum:
                      - ortam
                    host_key:
                      type: string
                    certificate:
                      type: string
                    certificate_expires_at:
                      type: string
                      format: date-time
                    tunnel_path:
                      type: string
                    claim:
                      type: string
                      format: date-time
                    tmux_session:
                      type: string
                  required:
                  - transport
                  - user
                  - host_key
                  - certificate
                  - certificate_expires_at
                  - tunnel_path
                  - claim
                  - tmux_session
      operationId: postV1JobsByIdAttach
      x-operation-id-source: derived
  /v1/jobs/{id}/retry:
    post:
      tags:
      - Jobs
      summary: Run a failed or lost job again
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      responses:
        '200':
          description: The job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
      operationId: postV1JobsByIdRetry
      x-operation-id-source: derived
  /v1/jobs/{id}/answer:
    post:
      tags:
      - Jobs
      summary: Answer a job that is waiting on a person
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      responses:
        '200':
          description: The job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
      operationId: postV1JobsByIdAnswer
      x-operation-id-source: derived
components:
  schemas:
    JobAsked:
      allOf:
      - $ref: '#/components/schemas/JobDetail'
      - type: object
        properties:
          waiting_for:
            type:
            - object
            - 'null'
            properties:
              machine:
                type: string
                enum:
                - owner
              owner:
                type:
                - string
                - 'null'
                description: 'Whose machine: the agent''s creator.'
              seen_at:
                type:
                - string
                - 'null'
                description: When that runner last polled; null if never.
            required:
            - machine
            - owner
            - seen_at
            description: Set when nothing will pick this task up until a runner comes back.
        required:
        - waiting_for
    Job:
      type: object
      properties:
        id:
          type: string
        chat_context:
          type:
          - object
          - 'null'
          properties:
            selection:
              type:
              - string
              - 'null'
            model_id:
              type:
              - string
              - 'null'
            saving:
              type: boolean
          required:
          - selection
          - model_id
          - saving
        agent_id:
          type: string
        kind:
          type: string
          enum:
          - ask
          - scheduled
          - graph
          - node
        status:
          type: string
          enum:
          - queued
          - running
          - needs_you
          - succeeded
          - failed
          - cancelled
          - lost
        machine_phase:
          type:
          - string
          - 'null'
          enum:
          - creating
          - provisioning
          - starting
          - ready
          - launching
          - running
          - stopping
          - parked
          - deleting
          - released
          - null
          description: 'Where the task''s cloud machine is. `parked`: stopped with its files, resumable.'
        machine_waiting:
          type:
          - string
          - 'null'
          description: Why the machine is waiting to start, in the provider's words (a start limit).
        task:
          type: object
          properties:
            session:
              type: boolean
            repo:
              type: string
          description: 'How the task runs: an interactive session, and the repository it works in.'
        instruction:
          type: string
        asked_by:
          type:
          - string
          - 'null'
        attended:
          type: boolean
        parent_id:
          type:
          - string
          - 'null'
        node_id:
          type:
          - string
          - 'null'
        trigger_id:
          type:
          - string
          - 'null'
        origin:
          anyOf:
          - type: object
            properties:
              kind:
                type: string
                enum:
                - slack
              requested_by:
                type: string
              team_id:
                type: string
              channel:
                type: string
              thread_ts:
                type: string
              message_ts:
                type: string
            required:
            - kind
            - requested_by
            - team_id
            - channel
            - thread_ts
            - message_ts
          - type: object
            properties:
              kind:
                type: string
                enum:
                - github
              requested_by:
                type: string
              repository:
                type: string
              number:
                type:
                - number
                - 'null'
              delivery_id:
                type: string
              comment_id:
                type: number
              ack_comment_id:
                type: number
            required:
            - kind
            - requested_by
            - repository
            - number
            - delivery_id
          - {}
          description: 'Where the task was asked for, when that was outside Derive: a Slack thread or a GitHub event. `requested_by` is that system''s handle, for display only.'
        subject:
          anyOf:
          - type: object
            properties:
              kind:
                type: string
                enum:
                - artifact
              id:
                type: string
            required:
            - kind
            - id
          - type: object
            properties:
              kind:
                type: string
                enum:
                - collection
              id:
                type: string
            required:
            - kind
            - id
          - type: object
            properties:
              kind:
                type: string
                enum:
                - tag
              tag:
                type: string
            required:
            - kind
            - tag
          - {}
        needs:
          type:
          - object
          - 'null'
          properties:
            kind:
              type: string
              enum:
              - review
              - decision
              - escalation
              - effect
            question_id:
              type: string
            target_id:
              type: string
            target_version:
              type: number
            question:
              type: string
            options:
              type: array
              items:
                type: string
            review_round_id:
              type: string
            asked_times:
              type: number
            first_asked_at:
              type: string
          required:
          - kind
          - question
        result:
          type: object
          properties:
            claim_ledger_version:
              type: number
              enum:
              - 1
            attempt_offset:
              type: integer
              minimum: 0
            git:
              type: object
              properties:
                repo:
                  type: string
                  maxLength: 300
                branch:
                  type:
                  - string
                  - 'null'
                  maxLength: 300
                commit:
                  type:
                  - string
                  - 'null'
                  maxLength: 64
              required:
              - repo
              - branch
              - commit
              description: Where the latest turn left the task's repository.
            compute:
              type: array
              items:
                type: object
                properties:
                  turn:
                    type: string
                  provider:
                    type: string
                    enum:
                    - ortam
                    - boat
                  sandbox_id:
                    type: string
                  started_at:
                    type: string
                  stopped_at:
                    type: string
                  billable_seconds:
                    type:
                    - number
                    - 'null'
                    minimum: 0
                  cost_micro_usd:
                    type:
                    - integer
                    - 'null'
                    minimum: 0
                required:
                - turn
                - provider
                - sandbox_id
                - started_at
                - stopped_at
                - billable_seconds
                - cost_micro_usd
            runs:
              type: array
              items:
                type: object
                properties:
                  attempt:
                    type: integer
                    minimum: 0
                  provider:
                    type: string
                    maxLength: 80
                  model:
                    type: string
                    maxLength: 200
                  runner_version:
                    type: string
                    maxLength: 80
                  harness_version:
                    type:
                    - string
                    - 'null'
                    maxLength: 100
                  skill:
                    type: object
                    properties:
                      short_id:
                        type: string
                        maxLength: 64
                      version:
                        type: integer
                        exclusiveMinimum: 0
                    required:
                    - short_id
                    - version
                  input_tokens:
                    type:
                    - integer
                    - 'null'
                    minimum: 0
                  cached_input_tokens:
                    type:
                    - integer
                    - 'null'
                    minimum: 0
                  output_tokens:
                    type:
                    - integer
                    - 'null'
                    minimum: 0
                  duration_ms:
                    type: integer
                    minimum: 0
                  model_cost_micro_usd:
                    type:
                    - integer
                    - 'null'
                    minimum: 0
                  harness_estimate_micro_usd:
                    type:
                    - integer
                    - 'null'
                    minimum: 0
                  api_estimate_micro_usd:
                    type:
                    - integer
                    - 'null'
                    minimum: 0
                  price_version:
                    type:
                    - string
                    - 'null'
                  turn_id:
                    type: string
                  actor_id:
                    type:
                    - string
                    - 'null'
                required:
                - attempt
                - provider
                - model
                - input_tokens
                - cached_input_tokens
                - output_tokens
                - duration_ms
                - model_cost_micro_usd
              maxItems: 600
            effects:
              type: array
              items:
                type: object
                properties:
                  kind:
                    type: string
                    enum:
                    - page
                    - pr
                    - email
                    - rows
                    - other
                  label:
                    type: string
                  ref:
                    type: string
                  version:
                    type: number
                  url:
                    type: string
                required:
                - kind
                - label
            evidence:
              type: array
              items:
                type: object
                properties:
                  label:
                    type: string
                  url:
                    type: string
                  ref:
                    type: string
                required:
                - label
            failure:
              type: object
              properties:
                reason:
                  type: string
                retryable:
                  type: boolean
              required:
              - reason
              - retryable
            summary:
              type: string
              maxLength: 2000
              description: One line saying what the run did, kept to 200 characters. Derived from the report when the runner sends none; empty when the run said nothing.
            superseded_by:
              type: string
            route:
              type: array
              items:
                type: object
                properties:
                  node_id:
                    type: string
                  attempt:
                    type: number
                  selected:
                    type: array
                    items:
                      type: string
                  decision:
                    type: string
                required:
                - node_id
                - attempt
        scheduled_for:
          type:
          - string
          - 'null'
        started_at:
          type:
          - string
          - 'null'
        finished_at:
          type:
          - string
          - 'null'
        lease_until:
          type:
          - string
          - 'null'
        attempt:
          type: number
        cost_micro_usd:
          type:
          - number
          - 'null'
        report_artifact_id:
          type:
          - string
          - 'null'
        report_short_id:
          type:
          - string
          - 'null'
          description: The job's report page, once it has one.
        created_at:
          type: string
        updated_at:
          type: string
      required:
      - id
      - chat_context
      - agent_id
      - kind
      - status
      - task
      - instruction
      - asked_by
      - attended
      - parent_id
      - node_id
      - trigger_id
      - origin
      - subject
      - needs
      - result
      - scheduled_for
      - started_at
      - finished_at
      - lease_until
      - attempt
      - cost_micro_usd
      - report_artifact_id
      - report_short_id
      - created_at
      - updated_at
    JobDetail:
      allOf:
      - $ref: '#/components/schemas/Job'
      - type: object
        properties:
          messages:
            type: array
            items:
              $ref: '#/components/schemas/JobMessage'
          turns:
            type: array
            items:
              type: object
              properties:
                id:
                  type: string
                ordinal:
                  type: number
                actor_id:
                  type:
                  - string
                  - 'null'
                body_md:
                  type: string
                status:
                  type: string
                  enum:
                  - queued
                  - running
                  - succeeded
                  - failed
                  - needs_you
                  - cancelled
                body_result_md:
                  type:
                  - string
                  - 'null'
                effects:
                  type: array
                  items:
                    type: object
                    properties:
                      kind:
                        type: string
                        enum:
                        - page
                        - pr
                        - email
                        - rows
                        - other
                      label:
                        type: string
                      ref:
                        type: string
                      version:
                        type: number
                      url:
                        type: string
                    required:
                    - kind
                    - label
                started_at:
                  type:
                  - string
                  - 'null'
                finished_at:
                  type:
                  - string
                  - 'null'
                resumable:
                  type: boolean
                execution:
                  type: object
                  properties:
                    provider:
                      type: string
                      enum:
                      - codex
                      - claude-code
                    model:
                      type:
                      - string
                      - 'null'
                    effort:
                      type:
                      - string
                      - 'null'
                    account_id:
                      type:
                      - string
                      - 'null'
                    agent_name:
                      type: string
                    skill:
                      type:
                      - object
                      - 'null'
                      properties:
                        artifact_id:
                          type: string
                        version:
                          type: number
                      required:
                      - artifact_id
                      - version
                    sandbox:
                      type: object
                      properties:
                        provider:
                          type: string
                          enum:
                          - boat
                          - ortam
                        connection_id:
                          type:
                          - string
                          - 'null'
                        account_id:
                          type:
                          - string
                          - 'null'
                      required:
                      - provider
                      - connection_id
                      - account_id
                  required:
                  - provider
                  - model
                  - account_id
                  - skill
              required:
              - id
              - ordinal
              - actor_id
              - body_md
              - status
              - body_result_md
              - effects
              - started_at
              - finished_at
              - resumable
              - execution
          events:
            type: array
            items:
              type: object
              properties:
                turn_id:
                  type: string
                seq:
                  type: number
                kind:
                  type: string
                label:
                  type:
                  - string
                  - 'null'
                created_at:
                  type: string
              required:
              - turn_id
              - seq
              - kind
              - created_at
        required:
        - messages
    JobMessage:
      type: object
      properties:
        id:
          type: string
        author_kind:
          type: string
          enum:
          - asker
          - agent
        author_id:
          type: string
        body_md:
          type: string
        progress:
          type: boolean
        model:
          type:
          - object
          - 'null'
          properties:
            id:
              type: string
            label:
              type: string
          required:
          - id
          - label
        tools:
          type: array
          items:
            type: string
        created_at:
          type: string
      required:
      - id
      - author_kind
      - author_id
      - body_md
      - progress
      - model
      - tools
      - created_at