Collections REST API Reference#

Collection management endpoints require authentication through an OIDC session cookie or per-user API key. The public shared-token endpoint is the exception. Base URL: https://ookcite-api.turtletech.us

Limits#

Plan	Collections	Entries/collection
Free	4	200
Academic	10	1,000
Business	20	4,000

Single-entry add, batch add, and BibTeX/RIS import are available to every signed-in plan up to its entry limit. Merge and batch move require an Academic or Business plan.

Collection CRUD#

Method	Path	Description
GET	/api/v1/collections	List all collections (returns CollectionSummary[])
POST	/api/v1/collections	Create collection (body: `{name: string}`)
GET	/api/v1/collections/{id}	Get full collection with entries
PATCH	/api/v1/collections/{id}	Update name, default_style, description
DELETE	/api/v1/collections/{id}	Delete collection

Entries#

Method	Path	Description
POST	/api/v1/collections/{id}/entries	Add single entry (body: `{metadata: CitationMetadata}`)
POST	/api/v1/collections/{id}/entries/batch	Add multiple entries (body: `{entries: CitationMetadata[]}`)
PATCH	/api/v1/collections/{id}/entries/{eid}	Update entry note, tags, or review status
PUT	/api/v1/collections/{id}/entries/{eid}/metadata	Replace citation metadata
POST	/api/v1/collections/{id}/entries/{eid}/merge	Merge metadata into an entry
DELETE	/api/v1/collections/{id}/entries/{eid}	Remove entry
PATCH	/api/v1/collections/{id}/reorder	Reorder entries (body: `{entry_ids: string[]}`)

Organization#

Method	Path	Description
PATCH	/api/v1/collections/{id}/tags	Set tags (body: `{tags: string[]}`)
POST	/api/v1/collections/{id}/check-duplicates	Check for duplicate entries (body: `{metadata: CitationMetadata}`)
POST	/api/v1/collections/batch-move	Move entries between collections

Import & Export#

Method	Path	Description
POST	/api/v1/collections/{id}/import	Upload .bib or .ris file (multipart/form-data)
GET	/api/v1/collections/{id}/export.bib	Download BibTeX with Better BibTeX keys

Sharing#

Creating and revoking share links is available to every signed-in plan.

Method	Path	Description
POST	/api/v1/collections/{id}/share	Generate read-only share link
DELETE	/api/v1/collections/{id}/share	Revoke share link
GET	/api/v1/shared/{token}	Public: get shared collection (no auth required)

Migration#

The collection merge endpoint requires an Academic or Business plan.

Method	Path	Description
POST	/api/v1/collections/merge	Merge localStorage collections into server account

Response Types#

CollectionSummary#

{
  "id": "uuid",
  "name": "My References",
  "created_at": "2026-04-05T12:00:00Z",
  "updated_at": "2026-04-05T14:30:00Z",
  "entry_count": 42,
  "tags": ["physics", "2026"],
  "share_token": null
}

CollectionEntry#

{
  "id": "uuid",
  "added_at": "2026-04-05T12:00:00Z",
  "metadata": { "...CitationMetadata..." },
  "note": null,
  "sort_order": 0,
  "review_status": "clean"
}