REST API Reference

The Okustera Cloud Platform provides a comprehensive, RESTful OpenAPI 3.1 interface for programmatic management of all cloud infrastructure, developer platform, and security resources.

Base Production Endpoint:

https://portal.okustera.com/api/v1

---

Authentication

All API requests require authentication via an HTTP Authorization header containing an Okustera API Bearer token:

curl -H "Authorization: Bearer <YOUR_API_TOKEN>" \
     -H "Content-Type: application/json" \
     https://portal.okustera.com/api/v1/auth/me

Tokens can be generated from the Okustera Cloud Portal under User Settings $\to$ API Tokens or provisioned via Keystone.

---

API Endpoints Overview

1. Authentication & Security (2FA)

HTTP Method & Path	Description
POST /api/v1/auth/login	Authenticate user credentials and optional TOTP code; receive JWT access token.
GET /api/v1/auth/me	Retrieve profile and project membership of current caller.
POST /api/v1/auth/2fa/setup	Generate a new TOTP secret key and QR code provisioning URI.
POST /api/v1/auth/2fa/activate	Submit initial 6-digit verification code to activate 2FA on user account.
POST /api/v1/auth/2fa/verify	Validate a 6-digit code during authentication challenge.
POST /api/v1/auth/2fa/disable	Deactivate 2FA by providing a valid verification code.

2. Compute Instances (Nova)

HTTP Method & Path	Description
GET /api/v1/compute/instances	List all instances in current tenant project.
POST /api/v1/compute/instances	Launch a new VM instance with flavor, image, and network.
GET /api/v1/compute/instances/{id}	Inspect instance state, IP addresses, and hardware flavor.
DELETE /api/v1/compute/instances/{id}	Terminate and delete an instance.
POST /api/v1/compute/instances/{id}/action	Execute lifecycle action (reboot, start, stop, pause, unpause, rebuild).
GET /api/v1/compute/instances/{id}/console	Retrieve interactive VNC/SPICE console URL for out-of-band access.
GET /api/v1/compute/instances/{id}/console-log	Retrieve live serial kernel boot logs.
GET /api/v1/compute/flavors	List available compute resource flavors.

3. VPC Networking & Security Groups (Neutron & OVN)

HTTP Method & Path	Description
GET /api/v1/network/networks	List tenant private VPC networks and subnets.
POST /api/v1/network/networks	Create a new private network with custom CIDR and DHCP.
DELETE /api/v1/network/networks/{id}	Delete a private network.
GET /api/v1/network/routers	List active virtual routers and gateway interfaces.
GET /api/v1/network/security-groups	List stateful firewall security groups and rules.
POST /api/v1/network/security-groups	Create a new security group.
POST /api/v1/network/security-groups/{id}/rules	Add ingress/egress firewall rule (protocol, port range, CIDR).
DELETE /api/v1/network/security-groups/rules/{rule_id}	Remove a firewall rule.
GET /api/v1/network/floating-ips	List allocated floating public IP addresses.
POST /api/v1/network/floating-ips	Allocate a new public floating IP from external pool.
POST /api/v1/network/floating-ips/{id}/associate	Bind floating IP to compute instance or load balancer port.
POST /api/v1/network/floating-ips/{id}/disassociate	Unbind floating IP from port.
DELETE /api/v1/network/floating-ips/{id}	Release floating IP back to external pool.
GET /api/v1/network/ports	List virtual network interfaces, MAC addresses, and IP bindings.

4. Load Balancers (Octavia LBaaS)

HTTP Method & Path	Description
GET /api/v1/octavia/loadbalancers	List active load balancers and provisioning status.
POST /api/v1/octavia/loadbalancers	Provision a new high-availability load balancer with dedicated VIP.
GET /api/v1/octavia/loadbalancers/{id}	Inspect load balancer status and VIP details.
DELETE /api/v1/octavia/loadbalancers/{id}	Decommission and delete a load balancer.
GET /api/v1/octavia/listeners	List listeners associated with tenant load balancers.
GET /api/v1/octavia/pools	List backend pools and member health states.

5. Persistent Block Storage (Cinder & Ceph)

HTTP Method & Path	Description
GET /api/v1/storage/volumes	List block storage volumes in current tenant project.
POST /api/v1/storage/volumes	Provision a new persistent volume (from scratch, image, or snapshot).
GET /api/v1/storage/volumes/{id}	Retrieve volume status, size, and instance attachments.
DELETE /api/v1/storage/volumes/{id}	Delete an unattached volume.
POST /api/v1/storage/volumes/{id}/attach	Attach volume to a running compute instance.
POST /api/v1/storage/volumes/{id}/detach	Detach volume from an instance.
GET /api/v1/storage/snapshots	List point-in-time volume snapshots.
POST /api/v1/storage/snapshots	Create an instantaneous copy-on-write volume snapshot.

6. S3-Compatible Object Storage (Ceph RGW)

HTTP Method & Path	Description
GET /api/v1/storage/credentials	List active S3 access keys for the tenant project.
POST /api/v1/storage/credentials	Generate a new S3 Access Key / Secret Key pair.
GET /api/v1/storage/buckets	List S3-compatible object storage buckets.
POST /api/v1/storage/buckets	Create new S3 bucket with quota and ACL (private, public-read).
DELETE /api/v1/storage/buckets/{name}	Delete an empty S3 bucket.
GET /api/v1/storage/buckets/{name}/objects	List objects in bucket with optional prefix filtering.
POST /api/v1/storage/buckets/{name}/objects/presign	Generate temporary presigned download or upload URL.
DELETE /api/v1/storage/buckets/{name}/objects/{key}	Delete an object from a bucket.

7. Operating System Images (Glance)

HTTP Method & Path	Description
GET /api/v1/glance/images	List certified public and custom tenant images.
POST /api/v1/glance/images	Register and upload a custom image (QCOW2, RAW, ISO).
GET /api/v1/glance/images/{id}	Retrieve image metadata, checksum, and status.
DELETE /api/v1/glance/images/{id}	Remove a custom image from the catalog.

8. Secrets Vault & KMS (Barbican)

HTTP Method & Path	Description
GET /api/v1/barbican/secrets	List secrets in current tenant project.
POST /api/v1/barbican/secrets	Store a new secret (passphrase, symmetric key, certificate, opaque).
GET /api/v1/barbican/secrets/{id}/payload	Retrieve decrypted secret payload.
DELETE /api/v1/barbican/secrets/{id}	Permanently delete a secret from the vault.

9. Managed Kubernetes Service (Magnum & CAPI)

HTTP Method & Path	Description
GET /api/v1/kubernetes/clusters	List all managed Kubernetes clusters for tenant.
POST /api/v1/kubernetes/clusters	Provision a new upstream Kubernetes cluster.
GET /api/v1/kubernetes/clusters/{id}	Inspect cluster health, API endpoint, and node count.
POST /api/v1/kubernetes/clusters/{id}/scale	Scale worker node pool count dynamically.
GET /api/v1/kubernetes/clusters/{id}/kubeconfig	Download cluster admin kubeconfig.
DELETE /api/v1/kubernetes/clusters/{id}	Terminate a cluster and delete associated VMs.
GET /api/v1/kubernetes/cluster-templates	List certified upstream Kubernetes templates.

10. Managed Databases (DBaaS)

HTTP Method & Path	Description
GET /api/v1/dbaas/clusters	List managed clusters across all engines (PostgreSQL, MySQL, MongoDB, Valkey, Qdrant).
POST /api/v1/dbaas/postgres	Provision high-availability PostgreSQL cluster (CloudNativePG).
GET /api/v1/dbaas/postgres/{ns}/{name}	Retrieve details for a PostgreSQL cluster.
GET /api/v1/dbaas/valkey	List active Valkey Sentinel clusters.
POST /api/v1/dbaas/valkey	Provision high-availability Valkey cluster (Spotahome Sentinel).
GET /api/v1/dbaas/qdrant	List tenant-isolated Qdrant Vector DB clusters.
POST /api/v1/dbaas/qdrant	Provision tenant-isolated Qdrant Vector DB cluster with Barbican API key auth.
POST /api/v1/dbaas/mysql	Provision multi-master MySQL cluster (Percona XtraDB).
POST /api/v1/dbaas/mongodb	Provision MongoDB replica set (Percona PSMDB).
GET /api/v1/dbaas/catalog/versions	List certified database engine versions available for deployment and upgrades.
GET /api/v1/dbaas/clusters/{engine}/{ns}/{name}/upgrade-candidates	Discover certified upgrade targets and tier classification for a running cluster.
GET /api/v1/dbaas/clusters/{engine}/{ns}/{name}/preflight	Evaluate the automated 5-point safety gate checklist prior to upgrading.
POST /api/v1/dbaas/clusters/{engine}/{ns}/{name}/upgrade	Dispatch an automated zero-downtime rolling upgrade job with auto-rollback.
GET /api/v1/dbaas/jobs/{job_id}	Query real-time lifecycle stage transitions and diagnostic logs for an upgrade job.
POST /api/v1/dbaas/jobs/{job_id}/rollback	Request manual rollback to restore the previous certified database engine version.

11. AI Inference PaaS & Model Foundry

HTTP Method & Path	Description
GET /api/v1/ai/status	Retrieve operational AI inference and Qdrant cluster health status.
GET /api/v1/ai/models	List active foundation models available for inference.
POST /api/v1/ai/chat/completions	OpenAI-compatible chat completions with unbuffered SSE streaming.
GET /api/v1/ai/rag/collections	List and inspect RAG vector knowledge base collections.
POST /api/v1/ai/rag/collections	Create and index a new RAG document collection in Qdrant.

12. API Gateway & Ingress (APISIX)

HTTP Method & Path	Description
GET /api/v1/gateway/routes	List all APISIX ingress routing rules.
POST /api/v1/gateway/routes	Create or update traffic-split canary route.
GET /api/v1/gateway/routes/{id}/manifest	Generate Kubernetes ApisixRoute YAML manifest.
GET /api/v1/gateway/certificates	List SSL/TLS certificates registered on the gateway.
POST /api/v1/gateway/certificates	Register new SSL/TLS certificate or request automated Let's Encrypt cert.

13. Serverless Functions & Layers (FaaS)

HTTP Method & Path	Description
GET /api/v1/functions/templates	List certified language runtime templates and lifecycle statuses (active, deprecated).
GET /api/v1/functions	List active serverless functions.
POST /api/v1/functions	Deploy serverless function with gVisor sandbox.
POST /api/v1/functions/{id}/invoke	Invoke serverless function synchronously or asynchronously.
GET /api/v1/functions/{id}/logs	Stream live function execution logs.
GET /api/v1/layers	List available shared CephFS dependency layers.
POST /api/v1/layers	Create a new shared dependency layer definition.
POST /api/v1/layers/{id}/versions	Publish an immutable layer version with zip or package requirements.
POST /api/v1/layers/{id}/permissions	Grant cross-tenant layer sharing permissions.

14. Workflows & Orchestration (Airflow)

HTTP Method & Path	Description
GET /api/v1/workflows/status	Retrieve operational health of Airflow Scheduler, PostgreSQL, and Ceph S3.
GET /api/v1/workflows/dags	List workflow DAGs accessible to current tenant.
PATCH /api/v1/workflows/dags/{dag_id}	Pause or unpause a workflow DAG.
POST /api/v1/workflows/dags/{dag_id}/trigger	Trigger immediate DAG execution with optional JSON parameters.
GET /api/v1/workflows/dags/{dag_id}/runs	List historical and active DAG runs with state and duration.
GET /api/v1/workflows/dags/{dag_id}/runs/{run_id}/tasks/{task_id}/logs	Retrieve streaming task execution logs.
POST /api/v1/workflows/dags/upload	Upload Python DAG file to S3 with automatic scheduler synchronization.
DELETE /api/v1/workflows/dags/{dag_id}	Delete DAG file from storage and purge scheduler metadata.

15. Observability & Telemetry

HTTP Method & Path	Description
GET /api/v1/observability/dashboard	Retrieve tenant-scoped telemetry summary.
GET /api/v1/observability/logs	Query Grafana Loki log streams with LogQL expressions and time ranges.
GET /api/v1/observability/timeseries/{metric_type}	Retrieve historical time-series data for CPU, RAM, Network, or Disk.
GET /api/v1/grafana/info	Retrieve tenant Grafana workspace URL and SSO endpoint.

16. FinOps, Billing & Payments

HTTP Method & Path	Description
GET /api/v1/billing/overview	Retrieve real-time metering, budget limit, and forecasted spend.
GET /api/v1/billing/breakdown	Itemized cost breakdown across compute, storage, and databases.
GET /api/v1/billing/invoices	Historical billing statements and line items.
GET /api/v1/billing/payment-methods	List configured customer payment cards.
POST /api/v1/billing/payment-methods	Add and tokenize a new payment method via Stripe.
POST /api/v1/billing/payment-methods/{id}/default	Set card as default payment method.
POST /api/v1/billing/checkout-session	Generate a secure Stripe payment checkout session.
GET /api/v1/billing/budget	Retrieve current budget limits and alert thresholds.
PUT /api/v1/billing/budget	Update monthly budget limit and notification thresholds.
GET /api/v1/billing/pricing	Retrieve active rate card and unit prices.

17. Identity & Policy Simulation

HTTP Method & Path	Description
GET /api/v1/identity/users	List users in current project.
POST /api/v1/identity/users	Create user account with initial credentials.
GET /api/v1/identity/roles	List available IAM roles (admin, member, reader).
POST /api/v1/identity/role-assignments	Assign a role to a user within a project.
DELETE /api/v1/identity/role-assignments	Revoke a user's role assignment.
POST /api/v1/iam/simulate	Evaluate whether an identity has permission to invoke an endpoint.
POST /api/v1/iam/sts/assume-role	Exchange workload identity token for short-lived credentials.

18. Service Catalog & Inventory

HTTP Method & Path	Description
GET /api/v1/services/services	List available cloud catalog services and subscription statuses.
GET /api/v1/inventory/inventory	Retrieve unified inventory of all compute, K8s, DB, and network resources.

19. Tenant Quotas & Governance

HTTP Method & Path	Description
GET /api/v1/tenant/quota	Query live resource allocations, usage, and available balances across 9 quota dimensions.

---

Standard Error Response Format

All failed API responses adhere to the standard JSON error schema:

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Cluster with ID 'k8s-prod-01' was not found in tenant 'tenant-production'.",
    "status": 404,
    "timestamp": "2026-09-28T12:00:00Z"
  }
}