API
Overview

API Overview

The Onvera API provides programmatic access to deploy, manage, and monitor applications on the Onvera platform.

Base URL

https://api.onvera.io/api/v1

Authentication

The API uses API key authentication. Include your API key in the X-API-Key header:

curl -H "X-API-Key: onv_sk_live_..." \
  https://api.onvera.io/api/v1/deployments

Learn more: API Authentication

API Versioning

The API is versioned under /api/v1/ with stable endpoints and clear deprecation notices for any changes.

Async Operations

Most API operations are asynchronous. When you create a deployment:

  1. API returns 202 Accepted with an operation_id
  2. Poll the operation endpoint to track progress
  3. Operation reaches a terminal state (succeeded or failed)

Learn more: Operations

Response Format

All API responses follow a consistent format:

Success Response:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Production Airflow",
    ...
  }
}

Error Response:

{
  "error": {
    "code": "DEPLOYMENT_NOT_FOUND",
    "message": "Deployment not found",
    "operation_id": "op_xxx"  // For async operations
  }
}

HATEOAS Links

Responses include HATEOAS links to related resources:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "links": {
      "self": "/api/v1/deployments/550e8400-e29b-41d4-a716-446655440000",
      "operation": "/api/v1/operations/op_660e8400-e29b-41d4-a716-446655440001"
    }
  }
}

Endpoints

Deployments

  • POST /v1/deployments - Create a deployment
  • GET /v1/deployments - List deployments
  • GET /v1/deployments/{id} - Get deployment details
  • DELETE /v1/deployments/{id} - Destroy a deployment

Learn more: Deployments

Operations

  • GET /v1/operations - List operations
  • GET /v1/operations/{id} - Get operation details

Learn more: Operations

Environments

  • GET /v1/environments - List environments

Rate Limits

The API has rate limits to ensure fair usage. See Rate Limits for details.

Error Handling

The API returns standard HTTP status codes and error messages. See Errors for error codes and handling.

OpenAPI Specification

The complete API specification is available:

  • OpenAPI JSON: /api/v1/openapi.json
  • Interactive Documentation: Swagger UI

Next Steps

configAuthentication