API Overview

The Odeion server exposes a RESTful HTTP API at /api/. All request and response bodies use JSON.

Interactive API Reference

Browse the complete API with request/response schemas, code examples, and try-it-out functionality in the Interactive API Reference.

Authentication

Most endpoints require a bearer token in the Authorization header:

Authorization: Bearer <token>

There are two kinds of bearer tokens:

• JWTs: short-lived session tokens obtained by calling POST /api/auth/login with a username and password. JWTs grant the full set of permissions the underlying user has, including admin endpoints.
• API keys: long-lived tokens that begin with odn_ and are scoped to a fixed subset of route groups. Users can generate them from Settings → Account once an administrator has enabled API key access for their account. Admin and user-management endpoints are never reachable via an API key, regardless of the user’s role.

For scripting and automation against the Odeion API, prefer API keys. They are revocable, scopeable, and easy to rotate. See the API Keys guide for details.

Error Format

All errors follow a consistent format:

{
  "error": {
    "code": "not_found",
    "message": "movie not found"
  }
}

Error codes map to HTTP statuses: bad_request (400), unauthorized (401), forbidden (403), not_found (404), conflict (409), validation_error (422), service_unavailable (503), internal_error (500).

Pagination

List endpoints return paginated results:

{
  "items": [],
  "page": 1,
  "per_page": 20,
  "total_items": 142,
  "total_pages": 8
}

Use ?page=N&per_page=N query parameters to control pagination.

OpenAPI Specification

The full OpenAPI 3.1 specification is available at /openapi.json on your Odeion server. This specification is auto-generated and always reflects the current API.

Meta Service API

Odeion runs a separate internal metadata enrichment service that fetches and normalizes data from external providers (TMDB, AniList, TVmaze, and others). It exposes its own HTTP API, documented in the Meta Service Reference, with the spec available at /openapi-meta.json. Most users won’t need to call it directly, since the main server API proxies the relevant operations, but it’s documented here for operators and integrators.