Derive Workspace API

openapi: 3.2.0
info:
  title: Derive Workspace 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: Workspace
  description: 'The workspace itself: members, settings, invitations, and switching.'
paths:
  /v1/workspace:
    get:
      tags:
      - Workspace
      summary: 'The active workspace: name, the caller''s role, and the member directory'
      responses:
        '200':
          description: The workspace + its members.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Workspace'
                - type: object
                  properties:
                    multi:
                      type: boolean
                    assistant:
                      type: boolean
                      description: 'Whether the built-in Derive can answer in this workspace: this deploy has a model and does not exclude the workspace. Budget and rate limits are checked per ask.'
                  required:
                  - multi
                  - assistant
      operationId: getV1Workspace
      x-operation-id-source: derived
    patch:
      tags:
      - Workspace
      summary: Rename the workspace (Admin only)
      responses:
        '200':
          description: The new name.
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                required:
                - name
      operationId: patchV1Workspace
      x-operation-id-source: derived
  /v1/workspace/members:
    put:
      tags:
      - Workspace
      summary: Add a member (by @handle or email) or change their role (Admin only)
      responses:
        '201':
          description: The added/updated member.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactMember'
      operationId: putV1WorkspaceMembers
      x-operation-id-source: derived
  /v1/workspace/members/{userId}:
    patch:
      tags:
      - Workspace
      summary: Change a member's role (Admin only; keeps at least one admin)
      parameters:
      - schema:
          type: string
        required: true
        name: userId
        in: path
      responses:
        '200':
          description: The member's new role.
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_id:
                    type: string
                  role:
                    type: string
                    enum:
                    - viewer
                    - commenter
                    - editor
                    - owner
                required:
                - user_id
                - role
      operationId: patchV1WorkspaceMembersByUserId
      x-operation-id-source: derived
    delete:
      tags:
      - Workspace
      summary: Remove a member (Admin only; keeps at least one admin)
      parameters:
      - schema:
          type: string
        required: true
        name: userId
        in: path
      responses:
        '204':
          description: The member was removed (idempotent).
      operationId: deleteV1WorkspaceMembersByUserId
      x-operation-id-source: derived
  /v1/workspace/invites:
    post:
      tags:
      - Workspace
      summary: Invite by email — adds an existing account directly, else a pending invite
      responses:
        '201':
          description: Either the member added directly, or the pending invite + accept link.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InviteResult'
      operationId: postV1WorkspaceInvites
      x-operation-id-source: derived
    get:
      tags:
      - Workspace
      summary: Pending invitations for the workspace (Admin only)
      responses:
        '200':
          description: The pending invites (no tokens).
          content:
            application/json:
              schema:
                type: object
                properties:
                  invites:
                    type: array
                    items:
                      $ref: '#/components/schemas/Invite'
                required:
                - invites
      operationId: getV1WorkspaceInvites
      x-operation-id-source: derived
  /v1/workspace/invites/{id}/resend:
    post:
      tags:
      - Workspace
      summary: Rotate a pending invitation and return its acceptance link (Admin only)
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      responses:
        '201':
          description: The replacement pending invitation and acceptance link.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InviteResult'
      operationId: postV1WorkspaceInvitesByIdResend
      x-operation-id-source: derived
  /v1/workspace/invites/{id}:
    delete:
      tags:
      - Workspace
      summary: Revoke a pending invitation (Admin only)
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      responses:
        '204':
          description: The invitation was revoked.
      operationId: deleteV1WorkspaceInvitesById
      x-operation-id-source: derived
  /v1/invites/{token}:
    get:
      tags:
      - Workspace
      summary: Preview an invitation (the accept page reads this)
      parameters:
      - schema:
          type: string
        required: true
        name: token
        in: path
      responses:
        '200':
          description: The workspace + role the token grants.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvitePreview'
      operationId: getV1InvitesByToken
      x-operation-id-source: derived
  /v1/invites/{token}/accept:
    post:
      tags:
      - Workspace
      summary: Accept an invitation (the signed-in token holder joins)
      parameters:
      - schema:
          type: string
        required: true
        name: token
        in: path
      responses:
        '200':
          description: The workspace joined + the caller's effective role.
          content:
            application/json:
              schema:
                type: object
                properties:
                  org_id:
                    type: string
                  role:
                    type: string
                    enum:
                    - viewer
                    - commenter
                    - editor
                    - owner
                required:
                - org_id
                - role
      operationId: postV1InvitesByTokenAccept
      x-operation-id-source: derived
  /v1/workspace/settings:
    get:
      tags:
      - Workspace
      summary: The workspace's integration toggles (any member)
      responses:
        '200':
          description: The workspace settings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgSettings'
      operationId: getV1WorkspaceSettings
      x-operation-id-source: derived
    patch:
      tags:
      - Workspace
      summary: Update the workspace's integration toggles (Admin only)
      responses:
        '200':
          description: The merged settings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgSettings'
      operationId: patchV1WorkspaceSettings
      x-operation-id-source: derived
  /v1/workspaces:
    get:
      tags:
      - Workspace
      summary: The caller's workspaces + which one this request resolved to
      responses:
        '200':
          description: The caller's workspaces and the active id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspaces'
      operationId: getV1Workspaces
      x-operation-id-source: derived
    post:
      tags:
      - Workspace
      summary: Create a workspace (the creator becomes its Admin and is switched in)
      responses:
        '201':
          description: The created workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceSummary'
      operationId: postV1Workspaces
      x-operation-id-source: derived
  /v1/workspace/switch:
    post:
      tags:
      - Workspace
      summary: Switch the active workspace (must be a member)
      responses:
        '200':
          description: The new active workspace id.
          content:
            application/json:
              schema:
                type: object
                properties:
                  active:
                    type: string
                required:
                - active
      operationId: postV1WorkspaceSwitch
      x-operation-id-source: derived
  /v1/workspaces/{id}:
    delete:
      tags:
      - Workspace
      summary: Delete an empty workspace you own (switches away if it was active)
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      responses:
        '200':
          description: The deleted id + the new active workspace (or null).
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted:
                    type: string
                  active:
                    type:
                    - string
                    - 'null'
                required:
                - deleted
                - active
      operationId: deleteV1WorkspacesById
      x-operation-id-source: derived
  /v1/workspace/join-link:
    get:
      tags:
      - Workspace
      summary: The workspace's join link (Admin only); 404 when none exists
      responses:
        '200':
          description: The current link.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceJoinLink'
      operationId: getV1WorkspaceJoinLink
      x-operation-id-source: derived
    post:
      tags:
      - Workspace
      summary: Create the workspace's join link, or rotate it (Admin only)
      responses:
        '201':
          description: The fresh link. Any previous link stops working.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceJoinLink'
      operationId: postV1WorkspaceJoinLink
      x-operation-id-source: derived
    delete:
      tags:
      - Workspace
      summary: Revoke the workspace's join link (Admin only)
      responses:
        '204':
          description: Revoked (or there was none).
      operationId: deleteV1WorkspaceJoinLink
      x-operation-id-source: derived
  /v1/join/{token}:
    get:
      tags:
      - Workspace
      summary: Preview a join link (the join page reads this)
      parameters:
      - schema:
          type: string
        required: true
        name: token
        in: path
      responses:
        '200':
          description: The workspace and role the link grants.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JoinLinkPreview'
      operationId: getV1JoinByToken
      x-operation-id-source: derived
    post:
      tags:
      - Workspace
      summary: Join the workspace through its link (signed-in holder)
      parameters:
      - schema:
          type: string
        required: true
        name: token
        in: path
      responses:
        '200':
          description: The workspace joined and the caller's role in it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JoinResult'
      operationId: postV1JoinByToken
      x-operation-id-source: derived
  /v1/workspace/activity:
    get:
      tags:
      - Workspace
      summary: Recent activity across the workspace, for the home
      parameters:
      - schema:
          type: integer
          minimum: 1
          maximum: 30
          description: The window in days (default 7, max 30).
        required: false
        description: The window in days (default 7, max 30).
        name: days
        in: query
      responses:
        '200':
          description: The window's versions, comments and review rounds, over visible artifacts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceActivity'
      operationId: getV1WorkspaceActivity
      x-operation-id-source: derived
components:
  schemas:
    WorkspaceActivity:
      type: object
      properties:
        since:
          type: string
          description: The window's start (ISO).
        artifacts:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              short_id:
                type: string
              title:
                type: string
            required:
            - id
            - short_id
            - title
          description: The artifacts the rows below belong to — only those the viewer can read.
        versions:
          type: array
          items:
            $ref: '#/components/schemas/ActivityVersion'
        comments:
          type: array
          items:
            $ref: '#/components/schemas/Comment'
        rounds:
          type: array
          items:
            $ref: '#/components/schemas/ReviewRound'
          description: Pending rounds (any age) and rounds opened or settled in the window.
      required:
      - since
      - artifacts
      - versions
      - comments
      - rounds
    ReviewRound:
      type: object
      properties:
        id:
          type: string
        artifact_id:
          type: string
        version:
          type: number
          description: The artifact version this round is reviewing.
        requested_by:
          type: string
          description: Who asked for the review (usually the agent that published).
        requested_by_name:
          type:
          - string
          - 'null'
          description: The requester's name when the round opened (a row from before the name was kept is named from the directory, while the agent exists).
        requested_by_kind:
          type: string
          enum:
          - user
          - agent
          description: What kind of principal asked, from the recorded id.
        requested_for:
          type: string
          description: The person asked to answer this round.
        state:
          type: string
          enum:
          - pending
          - sent_back
          description: 'Round state: pending, or sent_back (the answers came back — a note saying go IS the go-signal).'
        note:
          type:
          - string
          - 'null'
          description: Free-text note attached to the round; null if none.
        resolved_by_name:
          type:
          - string
          - 'null'
          description: The human who settled the round; null while pending, or when the store has no name for the resolver.
        created_at:
          type: string
        resolved_at:
          type:
          - string
          - 'null'
          description: When it was sent back; null while pending.
      required:
      - id
      - artifact_id
      - version
      - requested_by
      - requested_by_name
      - requested_by_kind
      - requested_for
      - state
      - note
      - resolved_by_name
      - created_at
      - resolved_at
    Mention:
      type: object
      properties:
        id:
          type: string
          description: Id of the mentioned person or agent.
        name:
          type: string
      required:
      - id
      - name
    Workspace:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        role:
          type: string
          enum:
          - viewer
          - commenter
          - editor
          - owner
          description: The caller's role in this workspace (owner = Admin).
        members:
          type: array
          items:
            $ref: '#/components/schemas/ArtifactMember'
      required:
      - id
      - name
      - role
      - members
    InviteResult:
      anyOf:
      - type: object
        properties:
          kind:
            type: string
            enum:
            - member
            description: The invitee already had an account and was added directly.
          member:
            $ref: '#/components/schemas/ArtifactMember'
        required:
        - kind
        - member
      - type: object
        properties:
          kind:
            type: string
            enum:
            - invite
            description: No account yet — a pending invite was created instead.
          invite:
            $ref: '#/components/schemas/Invite'
          accept_url:
            type: string
            description: The link the invitee follows to accept.
        required:
        - kind
        - invite
        - accept_url
    JoinLinkPreview:
      type: object
      properties:
        workspace:
          type: string
        role:
          type: string
          enum:
          - viewer
          - commenter
          - editor
          - owner
        inviter:
          type:
          - string
          - 'null'
          description: Display name of the Admin who made the link.
        expires_at:
          type: string
      required:
      - workspace
      - role
      - inviter
      - expires_at
    ActivityVersion:
      type: object
      properties:
        artifact_id:
          type: string
        n:
          type: number
        author:
          type: string
          description: The person's byline, healed to their live name.
        handle:
          type:
          - string
          - 'null'
        agent:
          type:
          - object
          - 'null'
          properties:
            id:
              type: string
            name:
              type: string
          required:
          - id
          - name
          description: The agent that produced this version on the author's behalf; null for the person's own.
        message:
          type:
          - string
          - 'null'
        name:
          type:
          - string
          - 'null'
        created_at:
          type: string
      required:
      - artifact_id
      - n
      - author
      - handle
      - agent
      - message
      - name
      - created_at
    JoinResult:
      type: object
      properties:
        org_id:
          type: string
        role:
          type: string
          enum:
          - viewer
          - commenter
          - editor
          - owner
          description: The caller's role in the workspace after the call.
        already_member:
          type: boolean
          description: True when the caller was already a member; their role is never changed.
      required:
      - org_id
      - role
      - already_member
    InvitePreview:
      type: object
      properties:
        workspace:
          type: string
          description: Name of the workspace this invite joins.
        role:
          type: string
          enum:
          - viewer
          - commenter
          - editor
          - owner
          description: The role this invite grants (owner = Admin).
        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:
      - workspace
      - role
      - email
      - inviter
    WorkspaceJoinLink:
      type: object
      properties:
        id:
          type: string
        role:
          type: string
          enum:
          - viewer
          - commenter
          - editor
          - owner
          description: 'The role a joiner receives: commenter (Viewer) or editor (Creator).'
        url:
          type: string
          description: The shareable URL. The token rides only here.
        created_at:
          type: string
        expires_at:
          type: string
          description: Fixed 30 days from creation; rotate to extend.
        join_count:
          type: integer
          description: How many people have joined through this link.
      required:
      - id
      - role
      - url
      - created_at
      - expires_at
      - join_count
    Workspaces:
      type: object
      properties:
        multi:
          type: boolean
          description: Whether multi-workspace mode is enabled.
        active:
          type: string
          description: Id of the workspace this request resolved to.
        account:
          $ref: '#/components/schemas/AccountSummary'
        workspaces:
          type: array
          items:
            $ref: '#/components/schemas/WorkspaceSummary'
      required:
      - multi
      - active
      - account
      - workspaces
    OrgSettings:
      type: object
      properties:
        emailNotifications:
          type: boolean
          description: When true, send workspace email notifications.
        defaultWorkspaceAccess:
          type: string
          enum:
          - none
          - member
          description: 'Access a new publish lands with: none, or member (factory default).'
        defaultLinkRole:
          type: string
          enum:
          - none
          - viewer
          - commenter
          - editor
          description: 'Share-link role a new publish lands with (factory default: none).'
        defaultListed:
          type: string
          enum:
          - none
          - workspace
          - public
          description: 'Listing a new publish lands with: none (default), workspace, or public.'
        whiteLabel:
          type: boolean
          description: Hide the Made-with-Derive marks on public artifacts and embeds, and honor the bare ?chrome=none embed.
        chatSources:
          type: array
          items:
            type: string
          description: 'Connection ids that @Derive replies (in comments and Slack) may reach through the call tool. Empty means none: connecting a server does not by itself let a reply use it. Agents are unaffected: each declares its own sources.'
        agentWrites:
          type: boolean
          description: 'The one agent-write switch, on by default. Off: no agent job is claimed, dispatched, or opened by a schedule, an @Derive reply cannot publish, and any agent-credentialed publish is refused at the API.'
        defaultAgentId:
          type: string
          description: 'The workspace''s default agent: the fallback actor for users with no connected agent. Absent = none.'
        brandprint:
          type: object
          properties:
            collectionId:
              type:
              - string
              - 'null'
              maxLength: 64
            profileId:
              type:
              - string
              - 'null'
              maxLength: 64
          description: The workspace's Brandprint (conventions collection + brand-profile artifact); absent until set.
      required:
      - emailNotifications
      - defaultWorkspaceAccess
      - defaultLinkRole
      - defaultListed
      - whiteLabel
      - chatSources
      - agentWrites
    Invite:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
        role:
          type: string
          enum:
          - viewer
          - commenter
          - editor
          - owner
          description: The role the invitee will receive (owner = Admin).
        created_at:
          type: string
        expires_at:
          type: string
          description: When the invite expires (7-day TTL).
      required:
      - id
      - email
      - role
      - created_at
      - expires_at
    AccountSummary:
      type:
      - object
      - 'null'
      properties:
        id:
          type: string
        handle:
          type:
          - string
          - 'null'
          description: The account's @handle; null if unclaimed.
        name:
          type:
          - string
          - 'null'
      required:
      - id
      - handle
      - name
      description: The owner's identity (id + handle); null for anonymous callers.
    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
    Comment:
      type: object
      properties:
        id:
          type: string
        artifact_id:
          type: string
          description: The artifact the comment is on.
        thread_id:
          type: string
          description: The thread this comment belongs to; equals id for the thread's root comment.
        base_version:
          type: number
          description: Artifact version this comment was anchored against.
        path:
          type:
          - string
          - 'null'
          description: File within a bundle the comment targets; null if not file-scoped.
        anchor:
          type:
          - string
          - 'null'
          description: Serialized text-quote or element anchor locating the comment; null if unanchored.
        body_md:
          type: string
          description: Comment body in Markdown; blanked when the comment is deleted.
        author:
          type: string
          description: Author's display name; "anonymous" for an anonymous poster.
        author_id:
          type:
          - string
          - 'null'
          description: 'Stable id of the author: a user id, an agent id, or "derive" for an @Derive reply; null for anonymous or legacy rows.'
        author_kind:
          type: string
          enum:
          - user
          - agent
          - anonymous
          description: What kind of principal wrote it, from the recorded id.
        options:
          type:
          - array
          - 'null'
          items:
            type: string
          description: 'On a question''s root comment: the choices it offers. A reply (a choice or other words) answers it.'
        resolution:
          type:
          - object
          - 'null'
          properties:
            at:
              type: string
            by:
              type:
              - string
              - 'null'
              description: The resolver's display name at the time.
            by_id:
              type:
              - string
              - 'null'
            by_kind:
              type:
              - string
              - 'null'
              enum:
              - user
              - agent
              - null
            version:
              type:
              - number
              - 'null'
              description: The version whose publish resolved the thread; null for a hand resolve.
          required:
          - at
          - by
          - by_id
          - by_kind
          - version
          description: 'On a resolved thread''s root: who settled it, when, and by which version.'
        state:
          type: string
          enum:
          - open
          - resolved
          - outdated
          description: 'Thread state: open, resolved, or outdated (the quoted text changed).'
        created_at:
          type: string
        anchored:
          type: boolean
          description: Whether the anchor still resolves against the current version (list only).
        reactions:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Emoji → list of reactor display names.
        edited:
          type: boolean
          description: True if the body was edited after posting.
        edited_at:
          type:
          - string
          - 'null'
          description: When the comment was last edited; null if never.
        deleted:
          type: boolean
          description: True if soft-deleted; the row stays but the body is blanked.
        mentions:
          type: array
          items:
            $ref: '#/components/schemas/Mention'
          description: Users or agents @mentioned in the comment body.
      required:
      - id
      - artifact_id
      - thread_id
      - base_version
      - path
      - anchor
      - body_md
      - author
      - author_kind
      - state
      - created_at
    WorkspaceSummary:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        role:
          type: string
          enum:
          - viewer
          - commenter
          - editor
          - owner
          description: The caller's role in this workspace (owner = Admin).
        personal:
          type: boolean
          description: True for the auto-provisioned personal workspace (id ws_p_<userId>).
      required:
      - id
      - name
      - role
      - personal