Skip to main content
This reference documents a self-hosted instance. Openinary Cloud has its own base URL, authentication and endpoint set, see the Cloud API Reference.

​
Base URL

All endpoints are relative to your Openinary server URL.

​
Authentication

Protected endpoints require an API key passed as a Bearer token.
Generate API keys from the dashboard (/api-keys) or via the API Keys API. In API-only mode, the first key is printed to the server logs on startup.
Every API-key endpoint also accepts a dashboard session cookie, not just the API key management ones. That is how the dashboard calls storage, queue and upload without minting a key for itself.

​
Rate limiting

Public endpoints are rate-limited by IP address. Rate limit headers are included in every response: Most API-key endpoints sit outside the public rate limiter, but not all: POST /upload and GET /health/database are behind it as well, so a burst of uploads can be throttled even with a valid key.

​
Endpoints overview

​
Error responses

JSON errors carry a short error label and a message explaining it:
The media delivery routes (/t/* and /authenticated/*) return plain text, not JSON. Parsing every error body as JSON will throw on exactly the routes your users hit most. Check the response Content-Type first.
A few endpoints add fields on top of that pair. Delete returns a details object listing what was cleaned up, and Invalidate Cache returns an errors array. Neither is a general envelope.