API Reference

Endpoint Categories

oCore exposes a RESTful JSON API under the /api prefix. All endpoints require authentication unless noted otherwise. Tenant-scoped endpoints require an X-Org-Slug header to identify the organization.

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:

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "X-Org-Slug: my-org" \
  "https://ocore.example.com/api/instances?limit=20&cursor=eyJpZCI6IjEyMyJ9"

Responses include a next_cursor field when more results are available:

{
  "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"
    }
  }
}

Common status codes:

Asynchronous Operations

Long-running operations like instance provisioning and server removal return 202 Accepted with a status that can be polled:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "provisioning",
  "message": "Instance creation in progress"
}

Use the resource detail endpoint to check progress, or configure a webhook to receive a notification when the operation completes.