API Overview

O.D.I.N. exposes a RESTful JSON API for managing printers, jobs, models, spools, and all other platform resources. Everything the web UI does is available through the API.

Base URL

http://your-server:8000/api/v1/

Routes are also available under /api/ (unversioned) for backwards compatibility, but /api/v1/ is recommended.

Authentication

All API requests require authentication. There are two methods:

Session Cookie (Browser)

The web UI authenticates via an httpOnly session cookie set during login. This is what the browser uses automatically -- you don't need to manage it manually.

# Login to obtain a session cookie
curl -X POST http://your-server:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "your-password"}' \
  -c cookies.txt

# Use the cookie on subsequent requests
curl http://your-server:8000/api/v1/printers -b cookies.txt

API Token (Automation)

For scripts, integrations, and automation, generate an API token in Settings > API Tokens. Pass it as a Bearer token:

curl http://your-server:8000/api/v1/printers \
  -H "Authorization: Bearer odin_abc123..."

tip

API tokens are scoped to the permissions of the user who created them. An operator's token cannot perform admin-only actions.

Interactive Documentation

Every running O.D.I.N. instance serves interactive API docs:

URL	Format
/api/v1/docs	Swagger UI -- interactive explorer with "Try it out"
/api/v1/redoc	ReDoc -- clean read-only reference

These are auto-generated from the FastAPI route definitions and are always in sync with your installed version.

info

The Swagger UI at /api/v1/docs is the canonical, always-up-to-date API reference. This documentation covers the major endpoint groups and patterns, but Swagger has the full details for every parameter, response schema, and status code.

Response Format

All responses return JSON. Successful responses return the resource directly (object or array). Errors return:

{
  "detail": "Printer not found"
}

Common HTTP status codes:

Code	Meaning
200	Success
201	Resource created
204	Deleted (no body)
400	Bad request (validation error)
401	Not authenticated
403	Forbidden (insufficient permissions)
404	Resource not found
422	Validation error (Pydantic)

Pagination

List endpoints accept skip and limit query parameters:

# Get jobs 51-100
curl "http://your-server:8000/api/v1/jobs?skip=50&limit=50" \
  -H "Authorization: Bearer odin_abc123..."

Parameter	Default	Description
skip	0	Number of records to skip
limit	50	Maximum records to return

Rate Limiting

O.D.I.N. is self-hosted and does not impose rate limits. You are limited only by your server's resources.

WebSocket

Real-time updates are available via WebSocket at:

ws://your-server:8000/ws

The WebSocket broadcasts printer status changes, job updates, and alert events as they happen. The web UI uses this for live dashboard updates.