Derive Favorites API

openapi: 3.2.0
info:
  title: Derive Favorites 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: Favorites
  description: The caller's favorited artifacts.
paths:
  /v1/artifacts/{shortId}/favorite:
    put:
      tags:
      - Favorites
      summary: Star an artifact
      parameters:
      - schema:
          type: string
        required: true
        name: shortId
        in: path
      responses:
        '200':
          description: Starred.
          content:
            application/json:
              schema:
                type: object
                properties:
                  favorite:
                    type: boolean
                required:
                - favorite
      operationId: putV1ArtifactsByShortIdFavorite
      x-operation-id-source: derived
    delete:
      tags:
      - Favorites
      summary: Unstar an artifact
      parameters:
      - schema:
          type: string
        required: true
        name: shortId
        in: path
      responses:
        '200':
          description: Unstarred.
          content:
            application/json:
              schema:
                type: object
                properties:
                  favorite:
                    type: boolean
                required:
                - favorite
      operationId: deleteV1ArtifactsByShortIdFavorite
      x-operation-id-source: derived
  /v1/artifacts/{shortId}/tags:
    put:
      tags:
      - Favorites
      summary: Set an artifact's browse tags (editors)
      parameters:
      - schema:
          type: string
        required: true
        name: shortId
        in: path
      responses:
        '200':
          description: The normalized tags.
          content:
            application/json:
              schema:
                type: object
                properties:
                  tags:
                    type: array
                    items:
                      type: string
                required:
                - tags
      operationId: putV1ArtifactsByShortIdTags
      x-operation-id-source: derived
  /v1/bulk/tags:
    post:
      tags:
      - Favorites
      summary: Add browse tags to many artifacts (per-artifact editor-gated)
      responses:
        '200':
          description: How many were tagged / skipped / failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkSummary'
      operationId: postV1BulkTags
      x-operation-id-source: derived
  /v1/bulk/favorite:
    post:
      tags:
      - Favorites
      summary: Star or unstar many artifacts (any reader)
      responses:
        '200':
          description: How many were starred / skipped / failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkSummary'
      operationId: postV1BulkFavorite
      x-operation-id-source: derived
  /v1/artifacts/{shortId}/tag-suggestions:
    get:
      tags:
      - Favorites
      summary: Suggest browse tags from similar artifacts + the workspace vocabulary
      parameters:
      - schema:
          type: string
        required: true
        name: shortId
        in: path
      responses:
        '200':
          description: Current tags, suggestions from similar artifacts, and the vocabulary.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagSuggestions'
      operationId: getV1ArtifactsByShortIdTagSuggestions
      x-operation-id-source: derived
components:
  schemas:
    BulkSummary:
      type: object
      properties:
        ok:
          type: number
          description: Artifacts the operation applied to.
        skipped:
          type: number
          description: Not found, or the caller may not do this to it — not an error.
        failed:
          type: number
          description: The write was attempted but threw.
      required:
      - ok
      - skipped
      - failed
    TagSuggestions:
      type: object
      properties:
        current:
          type: array
          items:
            type: string
          description: Tags already on the artifact.
        suggested:
          type: array
          items:
            type: object
            properties:
              tag:
                type: string
              count:
                type: number
            required:
            - tag
            - count
          description: Tags from similar artifacts, most-shared first; excludes current tags.
        vocabulary:
          type: array
          items:
            type: object
            properties:
              tag:
                type: string
              count:
                type: number
            required:
            - tag
            - count
          description: Every tag in the workspace with its usage count, most-used first.
      required:
      - current
      - suggested
      - vocabulary