API Documentation

The fdoi.us API provides read-only JSON access to covers, tags, artists, and collections. All endpoints are under /fdoi/api/v1/ and return paginated results (24 per page).

Authentication

Anonymous access is read-only. All GET requests work without authentication.

Token authentication is required for write operations (collections, favorites). Include your token in the Authorization header:

Authorization: Token your-token-here

Pagination

List endpoints return paginated JSON. Navigate with the ?page= parameter:

{
    "count": 821,
    "next": "https://www.fdoi.us/fdoi/api/v1/covers/?page=2",
    "previous": null,
    "results": [ ... ]
}

Endpoints

Covers

GET /fdoi/api/v1/covers/

List all visible covers with tags, thumbnail URLs, and metadata.

GET /fdoi/api/v1/covers/{id}/

Cover detail including artist, stamps, date/locations, and image count. {id} is the cover UUID returned in the list response.

Example response (list item)

{
    "id": "c8a5e6f1-9b2c-4d3e-8f7a-1b2c3d4e5f6a",
    "title": "Apollo 11 Moon Landing",
    "description": "First day cover commemorating...",
    "cachet_display": "Artcraft",
    "format": 3,
    "thumbnail_url": "/media/fdc/.../thumbnail.jpg",
    "thumbnail_avif_url": "/media/fdc/.../thumbnail.avif",
    "url": "/fdoi/cover/c8a5e6f1-9b2c-4d3e-8f7a-1b2c3d4e5f6a/",
    "tags": ["space", "apollo", "moon"]
}

Artists

GET /fdoi/api/v1/artists/

List cachet artists with name, bio, and life dates.

GET /fdoi/api/v1/artists/{slug}/

Single artist detail.

Collections

GET /fdoi/api/v1/collections/

List public collections (plus your own private collections if authenticated).

GET /fdoi/api/v1/collections/{id}/

Collection detail with all cover items. Use the collection UUID returned by the list/create endpoints.

POST /fdoi/api/v1/collections/

Create a new collection. Requires authentication.

Favorites

GET /fdoi/api/v1/favorites/mine/

List your favorited covers. Requires authentication.

POST /fdoi/api/v1/favorites/toggle/{id}/

Toggle favorite on/off for a cover. Requires authentication.

Quick Start

# List covers
curl https://www.fdoi.us/fdoi/api/v1/covers/

# Get a specific cover (UUID returned by the list endpoint)
curl https://www.fdoi.us/fdoi/api/v1/covers/c8a5e6f1-9b2c-4d3e-8f7a-1b2c3d4e5f6a/

# Search tags
curl https://www.fdoi.us/fdoi/api/v1/tags/

# With authentication
curl -H "Authorization: Token your-token" \
     https://www.fdoi.us/fdoi/api/v1/favorites/mine/