Skip to main content

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:

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:

URLFormat
/api/v1/docsSwagger UI -- interactive explorer with "Try it out"
/api/v1/redocReDoc -- 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:

CodeMeaning
200Success
201Resource created
204Deleted (no body)
400Bad request (validation error)
401Not authenticated
403Forbidden (insufficient permissions)
404Resource not found
422Validation 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..."
ParameterDefaultDescription
skip0Number of records to skip
limit50Maximum 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.

See Also​