API Reference

Overview

The Ollum API is REST-based and returns JSON. It is versioned under /api/v1 and scoped to a single project via its public slug. Slugs appear in your changelog URL: https://ollum.dev/c/your-slug.

base url

https://ollum.dev/api/v1/{slug}

Authentication

Every request must include your API key as a Bearer token in the Authorization header. Keys are generated in Settings → Integrations. They are shown only once — store them somewhere safe.

Header

http

Authorization: Bearer gl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Example request

bash

curl https://ollum.dev/api/v1/my-project/entries \
  -H "Authorization: Bearer gl_xxxx..."

Rate Limiting

Limits are enforced per API key using a sliding window algorithm (Upstash Redis).

GET endpoints60 req / min

POST /report10 req / min

When exceeded, the API returns 429 Too Many Requests with:

X-RateLimit-LimitMax requests in the current window

X-RateLimit-RemainingRequests remaining

X-RateLimit-ResetISO 8601 timestamp of window reset

Retry-AfterSeconds until you can retry

Errors

All errors return a JSON body with a single error field.

json

{ "error": "Invalid API key" }

401Missing or invalid API key

403Valid key but feature requires a higher plan

404Resource not found

400Malformed request body or missing required field

429Rate limit exceeded

500 / 503Server or upstream error — safe to retry

GET/api/v1/{slug}

Returns basic metadata for the project. Useful for verifying a key works and getting the current published entry count.

Request

bash

curl https://ollum.dev/api/v1/my-project \
  -H "Authorization: Bearer gl_xxxx..."

Response · 200 OK

json

{
  "data": {
    "name": "My Project",
    "slug": "my-project",
    "entry_count": 42,
    "created_at": "2025-01-12T09:00:00.000Z"
  }
}

GET/api/v1/{slug}/entries

Returns a paginated list of published changelog entries, newest first by default.

Query parameters

limitinteger

Entries to return. Min 1, max 100. Default: 20.

offsetinteger

Entries to skip for pagination. Default: 0.

tagstring

Filter by tag. Only entries whose tags array contains this value are returned.

orderstring

"asc" returns oldest first. Default: "desc" (newest first).

Request

bash

# Newest 20
curl "https://ollum.dev/api/v1/my-project/entries" \
  -H "Authorization: Bearer gl_xxxx..."

# Filter by tag, oldest first
curl "https://ollum.dev/api/v1/my-project/entries?tag=feature&order=asc" \
  -H "Authorization: Bearer gl_xxxx..."

# Page 2
curl "https://ollum.dev/api/v1/my-project/entries?limit=50&offset=50" \
  -H "Authorization: Bearer gl_xxxx..."

Response · 200 OK

json

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": "v2.1.0 — Dark mode & faster load times",
      "content": "## What's new\n\nWe shipped dark mode...",
      "tags": ["feature", "performance"],
      "version_label": "v2.1.0",
      "published_at": "2025-05-20T14:30:00.000Z",
      "source": "github",
      "created_at": "2025-05-20T14:28:11.000Z"
    }
  ],
  "meta": {
    "total": 42,
    "limit": 20,
    "offset": 0
  }
}

GET/api/v1/{slug}/entries/{id}

Returns a single published entry by its UUID. Returns 404 if the entry doesn't exist, is unpublished, or belongs to a different project.

Path parameters

slugstringrequired

Your project's public slug (visible in the changelog URL).

iduuidrequired

UUID of the changelog entry.

Request

bash

curl https://ollum.dev/api/v1/my-project/entries/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer gl_xxxx..."

Response · 200 OK

json

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": "v2.1.0 — Dark mode & faster load times",
    "content": "## What's new\n\nWe shipped dark mode...",
    "tags": ["feature", "performance"],
    "version_label": "v2.1.0",
    "published_at": "2025-05-20T14:30:00.000Z",
    "source": "github",
    "created_at": "2025-05-20T14:28:11.000Z"
  }
}

POST/api/v1/{slug}/report

Requires Pro plan

Reports a service degradation or outage from your infrastructure. Ollum creates a draft incident on your status page which you can review and publish from the dashboard. Rate-limited to 10 requests/minute — intended for monitor webhooks, not polling.

Request body · application/json

componentNamestringrequired

Name of the affected component as configured on your status page. Max 256 chars.

errorstringrequired

Human-readable description of the error. Ollum uses this to draft the incident message. Max 8 192 chars.

severityenum

Impact level. One of: "degraded" (default), "partial_outage", "major_outage".

Request

bash

curl -X POST https://ollum.dev/api/v1/my-project/report \
  -H "Authorization: Bearer gl_xxxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "componentName": "API",
    "error": "p99 latency exceeded 5 s for 3 consecutive minutes",
    "severity": "degraded"
  }'

Response · 200 OK

json

{
  "ok": true,
  "status": "draft"
}

status: "draft" means the incident was queued successfully. It is processed asynchronously and creates a draft on your status page. The incident is not published automatically.

Missing something? Send us a note and we'll prioritise the endpoints that matter most to your use case.