Collections API

Create, browse, update, and delete collections. A collection is identified by :owner/:slug.

GET /api/collections

No auth required

Browse public collections with optional search.

Query parameters

`q`	Search by collection name
`limit`	Max results (default 50, max 100)
`offset`	Pagination offset

Response 200

[
  {
    "id": "uuid",
    "slug": "pubpub-archive",
    "name": "PubPub Archive",
    "description": "Full archive of PubPub publications",
    "ownerSlug": "knowledge-futures",
    "ownerName": "Knowledge Futures",
    "latestVersion": "v3.2.0",
    "createdAt": "2026-01-15T00:00:00.000Z",
    "updatedAt": "2026-04-01T00:00:00.000Z"
  }
]

POST /api/accounts/:owner/collections

Auth: write scope

Create a new collection under an account. You must own the account or be a member of the org.

Request

{
  "slug": "my-dataset",
  "name": "My Dataset",
  "public": true
}

Response 201

{
  "id": "uuid",
  "owner": "yourname",
  "slug": "my-dataset",
  "name": "My Dataset"
}

GET /api/collections/:owner/:slug

No auth for public collections

Get collection metadata and latest version summary.

Response 200

{
  "id": "uuid",
  "slug": "pubpub-archive",
  "name": "PubPub Archive",
  "description": "Full archive of PubPub publications",
  "public": true,
  "ownerSlug": "knowledge-futures",
  "ownerName": "Knowledge Futures",
  "createdAt": "2026-01-15T00:00:00.000Z",
  "updatedAt": "2026-04-01T00:00:00.000Z",
  "latestVersion": {
    "semver": "v3.2.0",
    "recordCount": 4521,
    "fileCount": 892,
    "totalBytes": 1073741824,
    "metadata": { "description": "Full archive...", "readme": "..." },
    "createdAt": "2026-04-01T00:00:00.000Z",
    "message": "April sync"
  }
}

PATCH /api/collections/:owner/:slug

Auth: write scope

Update collection metadata. Pass only the fields to change.

Request

{
  "name": "New Name",
  "public": false
}

Response 200

{"ok": true}

DELETE /api/collections/:owner/:slug

Auth: admin scope

Delete a collection and all its versions, records, and file references. Files themselves are not deleted (they may be referenced by other collections).

Response 200

{"ok": true}

GET /api/accounts/:owner/collections

No auth required

List all collections belonging to an account. Non-owners see only public collections.

Response 200

[
  {
    "id": "uuid",
    "slug": "pubpub-archive",
    "name": "PubPub Archive",
    "public": true,
    "createdAt": "2026-01-15T00:00:00.000Z",
    "updatedAt": "2026-04-01T00:00:00.000Z"
  }
]

PATCH /api/collections/:owner/:slug/metadata

Auth: write scope

Update version metadata by creating a new minor version bump. The request body is a JSON object whose fields are merged with the previous version's metadata. Use this to update description, readme, license, or any other metadata fields without pushing new records.

Request

{
  "description": "Updated description of the archive",
  "readme": "# My Collection\nNew readme content.",
  "license": "CC-BY-4.0"
}

Fields

`description`	Short description of the collection.
`readme`	Markdown readme content.
`license`	License identifier (e.g. `"CC-BY-4.0"`).
`...`	Any other key-value pairs. All fields are merged into the previous version's metadata object.

Response 201

{
  "semver": "v3.2.1",
  "hash": "e5f6a7b8...",
  "metadata": {
    "description": "Updated description of the archive",
    "readme": "# My Collection\nNew readme content.",
    "license": "CC-BY-4.0"
  }
}

Errors

422 No versions exist yet. Push a version first before updating metadata.

POST /api/collections/:owner/:slug/fork

Auth: write scope

Fork a public collection into a target organization. Creates a new collection under the target org with the source's latest version. Records, schemas, and files are referenced (not copied); zero additional storage.

Request

{
  "targetOrg": "my-org",
  "slug": "my-fork"
}

Fields

`targetOrg`	Required. Slug of the organization to fork into. You must be a member of this org.
`slug`	Optional slug for the new collection. Defaults to the source collection's slug.

Response 201

{
  "id": "uuid",
  "owner": "my-org",
  "slug": "my-fork",
  "name": "PubPub Archive",
  "forkedFrom": {
    "owner": "knowledge-futures",
    "slug": "pubpub-archive",
    "version": "v3.2.0"
  },
  "version": {
    "semver": "v1.0.0",
    "recordCount": 4521
  }
}

Errors

`404`	Source collection not found, not public, or target org not found.
`409`	A collection with the same slug already exists in the target org.
`422`	Source collection has no versions to fork.