Derive

Derive Collections API

Shareable groups of artifacts, each with its own members.

GitHub OpenAPI

Operations 19

GET /v1/collections/{id} Get one collection through standing or its world link #
PATCH /v1/collections/{id} Rename a collection #
DELETE /v1/collections/{id} Delete a collection #
GET /v1/collections List the active workspace's collections (members only) #
POST /v1/collections Create a collection #
PUT /v1/collections/{id}/favorite Star a collection #
DELETE /v1/collections/{id}/favorite Unstar a collection #
PATCH /v1/collections/{id}/access Change a collection's workspace and link access #
POST /v1/collections/{id}/unlock Unlock a password-protected collection link #
PUT /v1/collections/{id}/items/{shortId} Add an artifact to a collection #
DELETE /v1/collections/{id}/items/{shortId} Remove an artifact from a collection #
GET /v1/artifacts/{shortId}/collection-suggestions Collections where work similar to this artifact already lives (members only) #
POST /v1/bulk/collections Add many artifacts to one or more collections (per-artifact share-gated) #
GET /v1/collections/{id}/members List a collection's members #
PUT /v1/collections/{id}/members Add or update a collection member #
DELETE /v1/collections/{id}/members/{userId} Remove a collection member #
DELETE /v1/collections/{id}/invites/{inviteId} Revoke a pending collection invitation #
GET /v1/collection-invites/{token} Preview a collection invitation #
POST /v1/collection-invites/{token}/accept Accept a collection invitation #

Specifications

⚙
OpenAPI
https://artifacts.apis.io/derive-to/openapi/derive-to-collections-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://artifacts.apis.io/derive-to/json-schema/derive-to-artifact-schema.json
📊
JSONSchema
https://artifacts.apis.io/derive-to/json-schema/derive-to-job-schema.json
📊
JSONSchema
https://artifacts.apis.io/derive-to/json-schema/derive-to-context-analysis-info-schema.json
📊
JSONSchema
https://artifacts.apis.io/derive-to/json-schema/derive-to-agent-schema.json
📊
JSONSchema
https://artifacts.apis.io/derive-to/json-schema/derive-to-comment-schema.json
📊
JSONSchema
https://artifacts.apis.io/derive-to/json-schema/derive-to-collection-schema.json

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/derive-to:derive-to-collections-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

derive-to-collections-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Derive Collections 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: Collections
  description: Shareable groups of artifacts, each with its own members.
paths:
  /v1/collections/{id}:
    get:
      tags:
      - Collections
      summary: Get one collection through standing or its world link
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      responses:
        '200':
          description: The collection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
      operationId: getV1CollectionsById
      x-operation-id-source: derived
    patch:
      tags:
      - Collections
      summary: Rename a collection
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      responses:
        '200':
          description: The updated collection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
      operationId: patchV1CollectionsById
      x-operation-id-source: derived
    delete:
      tags:
      - Collections
      summary: Delete a collection
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      responses:
        '204':
          description: The collection was deleted.
      operationId: deleteV1CollectionsById
      x-operation-id-source: derived
  /v1/collections:
    get:
      tags:
      - Collections
      summary: List the active workspace's collections (members only)
      responses:
        '200':
          description: The workspace's collections, each with its item count and origin.
          content:
            application/json:
              schema:
                type: object
                properties:
                  collections:
                    type: array
                    items:
                      $ref: '#/components/schemas/Collection'
                required:
                - collections
      operationId: getV1Collections
      x-operation-id-source: derived
    post:
      tags:
      - Collections
      summary: Create a collection
      responses:
        '201':
          description: The created collection (empty, manual).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
      operationId: postV1Collections
      x-operation-id-source: derived
  /v1/collections/{id}/favorite:
    put:
      tags:
      - Collections
      summary: Star a collection
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      responses:
        '200':
          description: The new starred state.
          content:
            application/json:
              schema:
                type: object
                properties:
                  starred:
                    type: boolean
                required:
                - starred
      operationId: putV1CollectionsByIdFavorite
      x-operation-id-source: derived
    delete:
      tags:
      - Collections
      summary: Unstar a collection
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      responses:
        '200':
          description: The new starred state.
          content:
            application/json:
              schema:
                type: object
                properties:
                  starred:
                    type: boolean
                required:
                - starred
      operationId: deleteV1CollectionsByIdFavorite
      x-operation-id-source: derived
  /v1/collections/{id}/access:
    patch:
      tags:
      - Collections
      summary: Change a collection's workspace and link access
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      responses:
        '200':
          description: The new access.
          content:
            application/json:
              schema:
                type: object
                properties:
                  workspace_access:
                    type: string
                    enum:
                    - none
                    - member
                    description: The collection's new workspace share scope.
                  link_role:
                    type: string
                    enum:
                    - none
                    - viewer
                    - commenter
                    - editor
                  locked:
                    type: boolean
                required:
                - workspace_access
                - link_role
                - locked
      operationId: patchV1CollectionsByIdAccess
      x-operation-id-source: derived
  /v1/collections/{id}/unlock:
    post:
      tags:
      - Collections
      summary: Unlock a password-protected collection link
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      responses:
        '200':
          description: Unlocked.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                required:
                - ok
      operationId: postV1CollectionsByIdUnlock
      x-operation-id-source: derived
  /v1/collections/{id}/items/{shortId}:
    put:
      tags:
      - Collections
      summary: Add an artifact to a collection
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      - schema:
          type: string
        required: true
        name: shortId
        in: path
      responses:
        '200':
          description: The artifact was added.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                required:
                - ok
      operationId: putV1CollectionsByIdItemsByShortId
      x-operation-id-source: derived
    delete:
      tags:
      - Collections
      summary: Remove an artifact from a collection
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      - schema:
          type: string
        required: true
        name: shortId
        in: path
      responses:
        '204':
          description: The artifact was removed.
      operationId: deleteV1CollectionsByIdItemsByShortId
      x-operation-id-source: derived
  /v1/artifacts/{shortId}/collection-suggestions:
    get:
      tags:
      - Collections
      summary: Collections where work similar to this artifact already lives (members only)
      parameters:
      - schema:
          type: string
        required: true
        name: shortId
        in: path
      responses:
        '200':
          description: Suggested collections, best first. Empty whenever there's no signal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  suggestions:
                    type: array
                    items:
                      $ref: '#/components/schemas/CollectionSuggestion'
                required:
                - suggestions
      operationId: getV1ArtifactsByShortIdCollectionSuggestions
      x-operation-id-source: derived
  /v1/bulk/collections:
    post:
      tags:
      - Collections
      summary: Add many artifacts to one or more collections (per-artifact share-gated)
      responses:
        '200':
          description: How many artifacts were added / skipped / failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkSummary'
      operationId: postV1BulkCollections
      x-operation-id-source: derived
  /v1/collections/{id}/members:
    get:
      tags:
      - Collections
      summary: List a collection's members
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      responses:
        '200':
          description: The collection's creator and its members.
          content:
            application/json:
              schema:
                type: object
                properties:
                  created_by:
                    type: string
                    description: User id of the collection's creator.
                  members:
                    type: array
                    items:
                      $ref: '#/components/schemas/ArtifactMember'
                  invites:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        email:
                          type: string
                        role:
                          type: string
                          enum:
                          - viewer
                          - commenter
                          - editor
                          - owner
                        created_at:
                          type: string
                        expires_at:
                          type: string
                      required:
                      - id
                      - email
                      - role
                      - created_at
                      - expires_at
                required:
                - created_by
                - members
                - invites
      operationId: getV1CollectionsByIdMembers
      x-operation-id-source: derived
    put:
      tags:
      - Collections
      summary: Add or update a collection member
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      responses:
        '201':
          description: The member added directly, or a pending emailed invite.
          content:
            application/json:
              schema:
                anyOf:
                - type: object
                  properties:
                    kind:
                      type: string
                      enum:
                      - member
                    member:
                      $ref: '#/components/schemas/ArtifactMember'
                  required:
                  - kind
                  - member
                - type: object
                  properties:
                    kind:
                      type: string
                      enum:
                      - invite
                    invite:
                      type: object
                      properties:
                        id:
                          type: string
                        email:
                          type: string
                        role:
                          type: string
                          enum:
                          - viewer
                          - commenter
                          - editor
                          - owner
                        created_at:
                          type: string
                        expires_at:
                          type: string
                      required:
                      - id
                      - email
                      - role
                      - created_at
                      - expires_at
                    accept_url:
                      type: string
                  required:
                  - kind
                  - invite
                  - accept_url
      operationId: putV1CollectionsByIdMembers
      x-operation-id-source: derived
  /v1/collections/{id}/members/{userId}:
    delete:
      tags:
      - Collections
      summary: Remove a collection member
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      - schema:
          type: string
        required: true
        name: userId
        in: path
      responses:
        '204':
          description: The member was removed.
      operationId: deleteV1CollectionsByIdMembersByUserId
      x-operation-id-source: derived
  /v1/collections/{id}/invites/{inviteId}:
    delete:
      tags:
      - Collections
      summary: Revoke a pending collection invitation
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      - schema:
          type: string
        required: true
        name: inviteId
        in: path
      responses:
        '204':
          description: The invitation was revoked.
      operationId: deleteV1CollectionsByIdInvitesByInviteId
      x-operation-id-source: derived
  /v1/collection-invites/{token}:
    get:
      tags:
      - Collections
      summary: Preview a collection invitation
      parameters:
      - schema:
          type: string
        required: true
        name: token
        in: path
      responses:
        '200':
          description: The collection and role the token grants.
          content:
            application/json:
              schema:
                type: object
                properties:
                  title:
                    type: string
                  role:
                    type: string
                    enum:
                    - viewer
                    - commenter
                    - editor
                    - owner
                  email:
                    type: string
                  inviter:
                    type:
                    - string
                    - 'null'
                required:
                - title
                - role
                - email
                - inviter
      operationId: getV1CollectionInvitesByToken
      x-operation-id-source: derived
  /v1/collection-invites/{token}/accept:
    post:
      tags:
      - Collections
      summary: Accept a collection invitation
      parameters:
      - schema:
          type: string
        required: true
        name: token
        in: path
      responses:
        '200':
          description: The collection joined and granted role.
          content:
            application/json:
              schema:
                type: object
                properties:
                  collection_id:
                    type: string
                  role:
                    type: string
                    enum:
                    - viewer
                    - commenter
                    - editor
                    - owner
                required:
                - collection_id
                - role
      operationId: postV1CollectionInvitesByTokenAccept
      x-operation-id-source: derived
components:
  schemas:
    Collection:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        created_by:
          type: string
          description: Creator's user id ("anon" if created anonymously).
        created_at:
          type: string
        count:
          type: number
          description: Number of artifacts in the collection.
        workspace_access:
          type: string
          enum:
          - none
          - member
          description: 'Workspace share scope: "member" (all members) or "none" (invite-only).'
        link_role:
          type: string
          enum:
          - none
          - viewer
          - commenter
          - editor
          description: What merely holding the canonical collection link grants.
        password_protected:
          type: boolean
          description: Whether the collection world link requires a password.
        url:
          type: string
          description: Canonical share URL for this collection.
        my_role:
          type:
          - string
          - 'null'
          enum:
          - viewer
          - commenter
          - editor
          - owner
          - null
          description: Caller's effective role on the collection. Null if none.
        can_share:
          type: boolean
          description: Whether the caller has standing (not merely a world-link role) to change collection sharing.
        starred:
          type: boolean
          description: Whether the caller starred this collection — it pins to their sidebar.
        last_activity:
          type: string
        my_last_activity:
          type: string
        preview:
          type: array
          items:
            type: object
            properties:
              short_id:
                type: string
              title:
                type:
                - string
                - 'null'
              current_version:
                type: number
              has_preview:
                type: boolean
              updated_at:
                type: string
              author_name:
                type:
                - string
                - 'null'
              author_login:
                type:
                - string
                - 'null'
              author_avatar:
                type:
                - string
                - 'null'
            required:
            - short_id
            - title
            - current_version
            - has_preview
            - updated_at
            - author_name
            - author_login
            - author_avatar
          description: A few of the collection's most recent artifacts, for the filmstrip the Collections view renders. A preview strip, not a listing.
        active:
          type: boolean
          description: Whether the caller has worked in this collection recently — published, commented, or been added. Derived from acts that leave a row; reading is not recorded.
      required:
      - id
      - title
      - created_by
      - created_at
      - count
    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
    CollectionSuggestion:
      type: object
      properties:
        id:
          type: string
          description: The suggested collection's id.
        score:
          type: number
          description: Summed neighbor-similarity votes — an ordering signal, not a probability.
      required:
      - id
      - score
    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