Derive Contexts API

openapi: 3.2.0
info:
  title: Derive Contexts 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: Contexts
  description: 'Papers imported from arXiv: each is a read-only Context whose artifact is the paper.'
paths:
  /v1/contexts:
    get:
      tags:
      - Contexts
      summary: List the workspace's imported papers
      responses:
        '200':
          description: The workspace's imported papers, each with its fetch state.
          content:
            application/json:
              schema:
                type: object
                properties:
                  contexts:
                    type: array
                    items:
                      $ref: '#/components/schemas/ContextInfo'
                required:
                - contexts
      operationId: getV1Contexts
      x-operation-id-source: derived
  /v1/contexts/import/arxiv:
    post:
      tags:
      - Contexts
      summary: 'Import a paper from arXiv as a read-only Context: its LaTeX source and BibTeX…'
      responses:
        '200':
          description: 'This workspace already imported that paper: its existing Context.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextInfo'
        '201':
          description: The new Context, already listed, with import.status 'fetching' (or 'pending') until the worker publishes the paper.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextInfo'
      operationId: postV1ContextsImportArxiv
      x-operation-id-source: derived
  /v1/contexts/{id}/import/retry:
    post:
      tags:
      - Contexts
      summary: Queue a failed paper import again (the context's creator or a workspace manager)
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      responses:
        '200':
          description: The Context, its import queued again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextInfo'
      operationId: postV1ContextsByIdImportRetry
      x-operation-id-source: derived
  /v1/contexts/{id}/import/code:
    post:
      tags:
      - Contexts
      summary: Attach, replace or remove the repository implementing an imported paper (the…
      description: 'The repository is fetched into the paper''s own artifact, where an agent reading the paper reads the code beside it; people get a link to it on its own host and never a file listing. Pass `url: null` to remove it, which republishes the paper without the code.'
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type:
                  - string
                  - 'null'
                  maxLength: 2000
                  description: A public GitHub or GitLab repository; null removes the attachment.
              required:
              - url
      responses:
        '200':
          description: The Context, its implementation queued (or removed).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextInfo'
      operationId: postV1ContextsByIdImportCode
      x-operation-id-source: derived
  /v1/contexts/{id}:
    get:
      tags:
      - Contexts
      summary: 'One imported paper: its import status, its document, and its BibTeX.'
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      responses:
        '200':
          description: The imported paper.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ContextInfo'
                - type: object
                  properties:
                    manifest_md:
                      type:
                      - string
                      - 'null'
                      description: The manifest's raw source — the runner's system prompt. Agent branch only.
                    brandprint:
                      $ref: '#/components/schemas/BrandprintConfig'
                    manifest:
                      type:
                      - object
                      - 'null'
                      properties:
                        short_id:
                          type: string
                        title:
                          type:
                          - string
                          - 'null'
                        version:
                          type: number
                        md:
                          type: string
                        pushed_at:
                          type: string
                          description: When this version was published.
                      required:
                      - short_id
                      - title
                      - version
                      - md
                      - pushed_at
                      description: The manifest, framed for a reader rather than a runner. Human branch only.
                    skills:
                      type: array
                      items:
                        $ref: '#/components/schemas/ManifestSkillInfo'
                      description: Every skill the manifest pins, with pin health. Human branch only.
                    repos:
                      type: array
                      items:
                        $ref: '#/components/schemas/ManifestRepoInfo'
                      description: Repo pointers from the manifest's frontmatter. Human branch only.
                    max_run_ms:
                      type:
                      - number
                      - 'null'
                      description: Per-run wall-clock budget; null = the server default. Human branch only.
                    max_concurrency:
                      type: number
                      description: How many sessions the runner may work at once. Human branch only.
                    documents:
                      type: array
                      items:
                        $ref: '#/components/schemas/ManifestDocumentInfo'
                      description: Documents the manifest binds (an imported paper's bundle). Human branch only.
                    bibtex:
                      type:
                      - string
                      - 'null'
                      description: An imported paper's own BibTeX entry (its bundle's CITATION.bib). Human branch only.
      operationId: getV1ContextsById
      x-operation-id-source: derived
    delete:
      tags:
      - Contexts
      summary: Delete an imported paper (its creator or a workspace manager)
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      responses:
        '204':
          description: The imported paper was deleted.
      operationId: deleteV1ContextsById
      x-operation-id-source: derived
  /v1/contexts/{id}/analysis:
    get:
      tags:
      - Contexts
      summary: An imported paper's implementation analysis, and the prompts that start or…
      description: 'The map an agent published from the paper''s contributions to the code that carries them out, with each code reference resolved to the repository''s own host at the commit it read. Derive never writes it: `prompts` are what a person pastes into their own agent. Readable by whoever may ask the Context.'
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      responses:
        '200':
          description: Where the analysis stands, and the analysis when there is one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextAnalysisInfo'
      operationId: getV1ContextsByIdAnalysis
      x-operation-id-source: derived
components:
  schemas:
    BrandprintConfig:
      type: object
      properties:
        profile_short_id:
          type:
          - string
          - 'null'
          description: The workspace brand-profile artifact (an HTML page carrying theme tokens), when set; null otherwise. Not in `members` — it is the headline read, not a note.
        members:
          type: array
          items:
            type: object
            properties:
              short_id:
                type: string
              title:
                type:
                - string
                - 'null'
              version:
                type: number
                description: The member's current version at fetch time (provenance).
              is_skill:
                type: boolean
                description: A skill bundle (materialize into skills/) vs a prose note.
            required:
            - short_id
            - title
            - version
            - is_skill
          description: 'Convention artifacts: skills to materialize, notes to read. Excludes the profile.'
      required:
      - profile_short_id
      - members
    ContextInfo:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        agent_id:
          type: string
          description: The hidden agent made for this imported paper. It is never listed or asked.
        manifest_short_id:
          type:
          - string
          - 'null'
          description: Short id of the linked manifest artifact; null if it can't be resolved.
        created_by:
          type: string
        created_at:
          type: string
        runner_seen_at:
          type:
          - string
          - 'null'
          description: When the runner last polled the queue (~minutely); null = never. Drives online/offline.
        ask_policy:
          type: string
          enum:
          - workspace
          - invited
          description: 'Who in the workspace may ask: any member, or the invited roster. Never outside the workspace.'
        connection_ids:
          type: array
          items:
            type: string
          description: Connections this context may use — its tools, in every lane it runs in.
        description:
          type:
          - string
          - 'null'
          description: The manifest's own first paragraph — frontmatter and a single leading heading stripped, capped. Null when the manifest has none or can't be read.
        skills_count:
          type: number
          description: How many skills the manifest's frontmatter pins.
        manifest_version:
          type:
          - number
          - 'null'
          description: The manifest artifact's current version; null if it can't be resolved.
        import:
          $ref: '#/components/schemas/ContextImportInfo'
      required:
      - id
      - name
      - agent_id
      - manifest_short_id
      - created_by
      - created_at
      - runner_seen_at
      - ask_policy
      - connection_ids
      - import
    AnalysisCodeRef:
      type: object
      properties:
        path:
          type: string
          description: The file's path in the repository.
        symbol:
          type:
          - string
          - 'null'
        lines:
          type:
          - string
          - 'null'
          description: A line, or a range such as `40-88`.
        href:
          type:
          - string
          - 'null'
          description: The file on the repository's own host, with the lines highlighted.
        pinned:
          type: boolean
          description: Whether `href` opens the exact commit the analysis read. A file inside a submodule, or an attachment with no recorded commit, opens a branch instead.
      required:
      - path
      - symbol
      - lines
      - href
      - pinned
    ManifestSkillInfo:
      type: object
      properties:
        short_id:
          type: string
        title:
          type:
          - string
          - 'null'
        pinned:
          type:
          - number
          - 'null'
          description: The pinned version; null = unpinned (runs current).
        current:
          type:
          - number
          - 'null'
          description: The skill artifact's current version; null if it can't be resolved.
        stale:
          type: boolean
          description: True when the pin trails the artifact's current version.
      required:
      - short_id
      - title
      - pinned
      - current
      - stale
    ContextImportInfo:
      type:
      - object
      - 'null'
      properties:
        source:
          type: string
          enum:
          - arxiv
        ref:
          type: string
          description: The bare paper id (`2401.12345`).
        version:
          type:
          - number
          - 'null'
          description: The paper version arXiv resolved the import to; null until fetched.
        status:
          type: string
          enum:
          - pending
          - fetching
          - ready
          - failed
          - dead
          description: 'pending/fetching: the source is on its way; ready: the paper is published and readable; failed: a transient error, retry scheduled; dead: gave up (retry by hand, or discard).'
        error:
          type:
          - object
          - 'null'
          properties:
            code:
              type: string
            detail:
              type:
              - string
              - 'null'
          required:
          - code
          - detail
          description: 'The last failure: a code the client maps to copy, plus a short detail.'
        url:
          type: string
          description: The paper's abstract page on arXiv.
        imported_by:
          type: string
        code:
          type:
          - object
          - 'null'
          properties:
            url:
              type: string
              description: The repository's page on its own host.
            status:
              type: string
              enum:
              - pending
              - ready
              - failed
              description: 'pending: on its way with the paper; ready: stored inside the paper''s artifact, where an agent reads it; failed: see `error`. Independent of the paper''s own status.'
            error:
              type:
              - string
              - 'null'
              description: Why the repository could not be fetched.
            commit:
              type:
              - string
              - 'null'
              description: The commit the repository was fetched at, when its host recorded one. Null until it is ready, and for an attachment made before commits were recorded.
          required:
          - url
          - status
          - error
          - commit
          description: The public repository implementing this paper, when one is attached. Its files live inside the paper's artifact for agents to read; people open the repository on its own host.
      required:
      - source
      - ref
      - version
      - status
      - error
      - url
      - imported_by
      - code
      description: 'Set when this Context was imported (a paper from arXiv): read-only, no runner, no sessions. Null for a Context someone defined.'
    AnalysisPaperRef:
      type: object
      properties:
        section:
          type: string
          description: A page of the paper, or `page#slug` for one heading's part of it.
        label:
          type:
          - string
          - 'null'
        heading:
          type:
          - string
          - 'null'
          description: The heading the section names, when it names one.
      required:
      - section
      - label
      - heading
    ManifestRepoInfo:
      type: object
      properties:
        url:
          type: string
        ref:
          type:
          - string
          - 'null'
      required:
      - url
      - ref
    ManifestDocumentInfo:
      type: object
      properties:
        short_id:
          type: string
        title:
          type:
          - string
          - 'null'
        kind:
          type:
          - string
          - 'null'
          enum:
          - doc
          - bundle
          - null
        role:
          type:
          - string
          - 'null'
          description: 'What the document is to the Context: `paper`, or `analysis` for the paper''s implementation analysis.'
      required:
      - short_id
      - title
      - kind
      - role
    ContextAnalysisInfo:
      type: object
      properties:
        state:
          type: string
          enum:
          - unavailable
          - none
          - ready
          - stale
          - restricted
          description: 'unavailable: no implementation is ready to analyse; none: no analysis yet; ready: it describes what the Context holds; stale: it was made against an arXiv version or commit the Context no longer holds; restricted: one exists that the caller cannot open.'
        stale_reasons:
          type: array
          items:
            type: string
        paper_short_id:
          type:
          - string
          - 'null'
        implementation:
          type:
          - object
          - 'null'
          properties:
            repository:
              type: string
            url:
              type: string
            commit:
              type:
              - string
              - 'null'
          required:
          - repository
          - url
          - commit
        analysis:
          type:
          - object
          - 'null'
          properties:
            short_id:
              type: string
            title:
              type:
              - string
              - 'null'
            version:
              type: number
            updated_at:
              type: string
            agent:
              type:
              - string
              - 'null'
              description: The agent that published this version.
            summary:
              type: string
            made_against:
              type: object
              properties:
                arxiv_version:
                  type:
                  - number
                  - 'null'
                repository:
                  type: string
                commit:
                  type:
                  - string
                  - 'null'
              required:
              - arxiv_version
              - repository
              - commit
            counts:
              type: object
              properties:
                contributions:
                  type: number
                details:
                  type: number
                implemented:
                  type: number
                could_not_map:
                  type: number
                unmapped:
                  type: number
                open_questions:
                  type: number
              required:
              - contributions
              - details
              - implemented
              - could_not_map
              - unmapped
              - open_questions
            contributions:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  title:
                    type: string
                  claim:
                    type: string
                  paper:
                    type: array
                    items:
                      $ref: '#/components/schemas/AnalysisPaperRef'
                  details:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        title:
                          type: string
                        status:
                          type: string
                          enum:
                          - implemented
                          - could_not_map
                        notes:
                          type:
                          - string
                          - 'null'
                        paper:
                          type: array
                          items:
                            $ref: '#/components/schemas/AnalysisPaperRef'
                        code:
                          type: array
                          items:
                            $ref: '#/components/schemas/AnalysisCodeRef'
                      required:
                      - id
                      - title
                      - status
                      - notes
                      - paper
                      - code
                required:
                - id
                - title
                - claim
                - paper
                - details
            unmapped:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  notes:
                    type: string
                  path:
                    type: string
                  symbol:
                    type:
                    - string
                    - 'null'
                  lines:
                    type:
                    - string
                    - 'null'
                  href:
                    type:
                    - string
                    - 'null'
                  pinned:
                    type: boolean
                required:
                - id
                - notes
                - path
                - symbol
                - lines
                - href
                - pinned
            open_questions:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  question:
                    type: string
                required:
                - id
                - question
          required:
          - short_id
          - title
          - version
          - updated_at
          - agent
          - summary
          - made_against
          - counts
          - contributions
          - unmapped
          - open_questions
        prompts:
          type: object
          properties:
            start:
              type:
              - string
              - 'null'
              description: What a person pastes into their agent to write the analysis, while none exists.
            update:
              type:
              - string
              - 'null'
              description: What a person pastes into their agent to check and update it, once it exists.
          required:
          - start
          - update
        can_publish:
          type: boolean
          description: 'Whether the caller''s own agents may start or update it: publishing needs an editor seat or higher.'
      required:
      - state
      - stale_reasons
      - paper_short_id
      - implementation
      - analysis
      - prompts
      - can_publish