API Reference

Overview

oCore exposes a RESTful JSON API under the /api prefix. Each endpoint group below is auto-generated from the OpenAPI specification and includes full request/response schemas with an interactive playground for testing.

Select an endpoint group from the sidebar to view its operations, parameters, request bodies, and response schemas. Use the built-in playground to send test requests directly from the documentation.

Authentication

oCore supports two authentication methods:

JWT Bearer Tokens

All browser and CLI sessions use short-lived JWT access tokens obtained through the /api/auth/login endpoint. Include the token in the Authorization header:

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "X-Org-Slug: my-org" \
  https://ocore.example.com/api/servers

Access tokens expire after 1 hour (configurable via JWT_ACCESS_EXPIRY). Use the /api/auth/refresh endpoint with your refresh token to obtain a new access token without re-authenticating.

API Keys

For server-to-server integrations and CI/CD pipelines, create a long-lived API key from the dashboard or via the API. API keys are scoped to an organization and respect the same role-based permissions as regular users.

curl -H "Authorization: Bearer ocore_k_abc123..." \
  -H "X-Org-Slug: my-org" \
  https://ocore.example.com/api/servers

API keys use the same Authorization: Bearer header as JWT tokens. The backend detects the ocore_ prefix to distinguish API keys from JWT tokens automatically.

See the API Keys guide for setup instructions and best practices.

Request and Response Conventions

Content Type

All request and response bodies use application/json. Set the Content-Type header accordingly for POST, PUT, and PATCH requests.

Pagination

List endpoints support cursor-based pagination:

{
  "data": ["..."],
  "next_cursor": "eyJpZCI6IjQ1NiJ9",
  "has_more": true
}

Error Responses

Errors follow a consistent structure with an HTTP status code and a machine-readable error code:

{
  "error": {
    "code": "validation_error",
    "message": "Instance name must be between 3 and 64 characters",
    "details": {
      "field": "name",
      "constraint": "min_length"
    }
  }
}

Status	Meaning
`400`	Validation error in request body or parameters
`401`	Missing or invalid authentication credentials
`403`	Authenticated but lacking required permissions
`404`	Resource not found
`409`	Conflict, such as duplicate slug or name
`422`	Request understood but cannot be processed
`429`	Rate limit exceeded
`500`	Internal server error

Asynchronous Operations

Long-running operations like instance provisioning and server removal return 202 Accepted with a status that can be polled. Use the resource detail endpoint to check progress, or configure a webhook to receive a notification when the operation completes.

API Reference

On this page