Derive Sharing API

openapi: 3.2.0
info:
  title: Derive Sharing 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: Sharing
  description: Per-artifact collaborator roles (shares) layered over the workspace baseline.
paths:
  /v1/artifacts/{shortId}/access-request:
    post:
      tags:
      - Sharing
      summary: Ask the people who can share an artifact to grant you access
      description: 202 for every outcome once the caller is authenticated and the body validates — missing artifact, no access, already readable, or already asked. The response deliberately does not reveal which.
      parameters:
      - schema:
          type: string
        required: true
        name: shortId
        in: path
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                note:
                  type: string
                  maxLength: 280
                  description: 'Optional message to the approvers: who you are, why you need it.'
      responses:
        '202':
          description: The request was accepted. Says nothing about what followed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    enum:
                    - true
                required:
                - ok
        '400':
          description: The note is longer than the limit.
        '401':
          description: Authenticated as a principal with no human behind it (a static agent token). A grant needs an account to attach to.
        '403':
          description: No credential at all. Anonymous writes to /v1/* are refused app-wide, before this route is reached.
      operationId: postV1ArtifactsByShortIdAccessRequest
      x-operation-id-source: derived
  /v1/artifacts/{shortId}/members:
    get:
      tags:
      - Sharing
      summary: List an artifact's collaborators (collaborators only)
      parameters:
      - schema:
          type: string
        required: true
        name: shortId
        in: path
      responses:
        '200':
          description: The workspace default role and the artifact's members.
          content:
            application/json:
              schema:
                type: object
                properties:
                  default_role:
                    type: string
                    enum:
                    - viewer
                    - commenter
                    - editor
                    - owner
                    description: Workspace baseline role applied to anyone without an explicit share.
                  members:
                    type: array
                    items:
                      $ref: '#/components/schemas/ArtifactMember'
                    description: Collaborators with an explicit per-artifact role share.
                  invites:
                    type: array
                    items:
                      $ref: '#/components/schemas/ArtifactInvite'
                    description: Pending emailed invites — share-capable callers (editor+) only; empty otherwise (invitee emails stay need-to-know).
                required:
                - default_role
                - members
                - invites
      operationId: getV1ArtifactsByShortIdMembers
      x-operation-id-source: derived
    put:
      tags:
      - Sharing
      summary: Share an artifact with a person at a role — or email an invite
      parameters:
      - schema:
          type: string
        required: true
        name: shortId
        in: path
      responses:
        '201':
          description: Either the member added directly (existing account), or the pending invite + accept link (unknown email).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShareResult'
      operationId: putV1ArtifactsByShortIdMembers
      x-operation-id-source: derived
  /v1/artifacts/{shortId}/members/{userId}:
    delete:
      tags:
      - Sharing
      summary: Remove a collaborator from an artifact
      parameters:
      - schema:
          type: string
        required: true
        name: shortId
        in: path
      - schema:
          type: string
        required: true
        name: userId
        in: path
      responses:
        '204':
          description: The collaborator was removed.
      operationId: deleteV1ArtifactsByShortIdMembersByUserId
      x-operation-id-source: derived
  /v1/artifacts/{shortId}/invites/{id}:
    delete:
      tags:
      - Sharing
      summary: Revoke a pending emailed invite
      parameters:
      - schema:
          type: string
        required: true
        name: shortId
        in: path
      - schema:
          type: string
        required: true
        name: id
        in: path
      responses:
        '204':
          description: The invite was revoked.
      operationId: deleteV1ArtifactsByShortIdInvitesById
      x-operation-id-source: derived
  /v1/artifact-invites/{token}:
    get:
      tags:
      - Sharing
      summary: Preview an artifact invitation (the accept page reads this)
      parameters:
      - schema:
          type: string
        required: true
        name: token
        in: path
      responses:
        '200':
          description: The artifact + role the token grants.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactInvitePreview'
      operationId: getV1ArtifactInvitesByToken
      x-operation-id-source: derived
  /v1/artifact-invites/{token}/accept:
    post:
      tags:
      - Sharing
      summary: Accept an artifact invitation (the signed-in token holder is shared in)
      parameters:
      - schema:
          type: string
        required: true
        name: token
        in: path
      responses:
        '200':
          description: The artifact joined + the granted role.
          content:
            application/json:
              schema:
                type: object
                properties:
                  short_id:
                    type: string
                  role:
                    type: string
                    enum:
                    - viewer
                    - commenter
                    - editor
                    - owner
                required:
                - short_id
                - role
      operationId: postV1ArtifactInvitesByTokenAccept
      x-operation-id-source: derived
components:
  schemas:
    ArtifactInvitePreview:
      type: object
      properties:
        title:
          type:
          - string
          - 'null'
          description: The artifact's title; null if untitled.
        role:
          type: string
          enum:
          - viewer
          - commenter
          - editor
          - owner
          description: The role this invite grants.
        email:
          type: string
          description: The email address the invite was addressed to.
        inviter:
          type:
          - string
          - 'null'
          description: The inviter's display name; null if unknown.
      required:
      - title
      - role
      - email
      - inviter
    ArtifactMember:
      type: object
      properties:
        user_id:
          type: string
        handle:
          type:
          - string
          - 'null'
          description: Public @handle; null when the user has none.
        name:
          type:
          - string
          - 'null'
          description: Display name; null when unset.
        profession:
          type:
          - string
          - 'null'
          description: Joined only on workspace-member payloads; absent on artifact/collection lists.
        role:
          type: string
          enum:
          - viewer
          - commenter
          - editor
          - owner
          description: 'Permission tier, ascending: viewer < commenter < editor < owner.'
      required:
      - user_id
      - handle
      - name
      - role
    ShareResult:
      anyOf:
      - type: object
        properties:
          kind:
            type: string
            enum:
            - member
            description: The person already had an account — shared directly.
          member:
            $ref: '#/components/schemas/ArtifactMember'
        required:
        - kind
        - member
      - type: object
        properties:
          kind:
            type: string
            enum:
            - invite
            description: No account with that email — a pending invite was created and emailed.
          invite:
            $ref: '#/components/schemas/ArtifactInvite'
          accept_url:
            type: string
            description: The link the invitee follows to accept.
        required:
        - kind
        - invite
        - accept_url
    ArtifactInvite:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
          description: The invitee's email (share-capable callers only).
        role:
          type: string
          enum:
          - viewer
          - commenter
          - editor
          - owner
          description: The role accepting will grant.
        created_at:
          type: string
        expires_at:
          type: string
          description: When the invite expires (7-day TTL).
      required:
      - id
      - email
      - role
      - created_at
      - expires_at