The API

Every Archetype instance exposes a versioned REST API built on Django REST Framework. All routes are mounted under /api/v1/ by api/config/urls.py, and each instance serves its own live OpenAPI schema and an interactive Swagger UI — so the reference below is a map, and the schema on your host is the source of truth.

Replace archetype.example.org with your instance host in every example. On a local dev stack the base URL is http://localhost:8000.

How the API is mounted

config/urls.py includes one URLconf per feature app under the /api/v1/ prefix. The feature apps live in api/apps/*:

Prefix	App	Purpose
/api/v1/version/, /api/v1/site-labels/, /api/v1/app-settings/	common	Build version, customisable UI labels, public site settings
/api/v1/auth/	users	Token login/logout, profile, user management
/api/v1/search/	search	Meilisearch-backed search, suggest, facets, export
/api/v1/manuscripts/	manuscripts	Item parts, images, image texts
/api/v1/scribes/…, /api/v1/hands/…	scribes	Scribes and hands
/api/v1/manuscripts/graphs/…, /api/v1/annotations/…	annotations	Annotation graphs (read and write)
/api/v1/annotations-w3c/	annotation_standards	W3C Web Annotation output
/api/v1/iiif/	annotation_standards	IIIF Presentation manifests and Content Search
/api/v1/symbols_structure/	symbols_structure	Allographs and positions (characters, components, features under management)
/api/v1/media/	publications	Publications, events, carousel items, partners
/api/v1/pages/	pages	Editable site pages
/api/v1/worksets/	worksets	User-owned lightbox worksets
/api/v1/uploads/	uploads	Chunked image uploads (superuser only)

See Core endpoints for the read paths integrators reach for most.

Public vs. management (backoffice) split

Every app follows a dual pattern. Read-oriented public endpoints (item-parts, scribes, hands, manuscripts/graphs, search/<index_type>/) are anonymously readable. Write/admin endpoints are registered under a management/ sub-path (for example /api/v1/manuscripts/management/item-parts/, /api/v1/auth/management/users/, /api/v1/management/scribes/hands/).

The global default is DRF’s IsAuthenticatedOrReadOnly (config/settings.py), so anonymous clients get read access to public routes. Management viewsets extend BasePrivilegedViewSet, which pins permission_classes = [IsSuperuser] — they are usable only by a superuser token and are what the Next.js backoffice drives. A few exceptions sit outside that split: site-labels/ and app-settings/ are publicly readable but superuser-writable, annotations/graphs/ is a write-only surface for any authenticated user, and worksets/ are owner-scoped (a public workset can be retrieved anonymously). Anonymous requests are also rate-limited in non-DEBUG deployments (DRF_THROTTLE_ANON_RATE / DRF_THROTTLE_USER_RATE).

Authentication

Auth is DRF TokenAuthentication, with Djoser’s token login/logout views. There are no sessions or JWTs — you present a token in the Authorization header.

Obtain a token with username + password:

curl -X POST https://archetype.example.org/api/v1/auth/token/login \
  -H "Content-Type: application/json" \
  -d '{"username": "USERNAME", "password": "PASSWORD"}'
# → {"auth_token": "e1c2...abcd"}

Then send it on authenticated (or management) requests. Note the DRF Token scheme, not Bearer:

curl https://archetype.example.org/api/v1/auth/management/users/ \
  -H "Authorization: Token e1c2...abcd"

Related account endpoints:

• POST /api/v1/auth/token/login — create a token (throttled to 10 requests/minute per client)
• POST /api/v1/auth/token/logout — invalidate the current token (send the header)
• GET /api/v1/auth/profile — the authenticated user’s profile

Create the first superuser with Django’s createsuperuser (run it in the api container, e.g. just bash then python manage.py createsuperuser). See For contributors for local dev login.

OpenAPI schema and Swagger UI

Every instance publishes its own contract — no external hosting required:

• Schema (JSON): https://archetype.example.org/api/v1/schema/
• Swagger UI: https://archetype.example.org/api/v1/docs/

The schema is assembled from per-app apps/*/schema.yaml files. Not every route is described there: the standards routes (annotations-w3c/, iiif/) and the search list, detail, export and suggest routes have no schema entries — see Endpoints for those. Fetch it as a machine-readable spec:

curl https://archetype.example.org/api/v1/schema/ -o archetype-openapi.json

Swagger UI only loads a same-origin schema; the default is /api/v1/schema/ on that host.

Locally, bring the backend up with just up from api/, then browse http://localhost:8000/api/v1/docs/.

For running an instance over your own material, see Load your own corpus. To work on the API itself, see For contributors.