CP API Reference

Base URL: https://api.computeportal.io

The ComputePortal REST API gives you programmatic control over every aspect of your GPU compute environment — services, domains, environment variables, logs, scaling, and more. All requests are authenticated with a Bearer token.

Authentication

Every API request must include your CP API token in the Authorization header.

http

Authorization: Bearer cp_live_<hex-string>

Token format: cp_live_ followed by a lowercase hex string (e.g. cp_live_4a7f3b9c2e1d8a06...).

You can find your token in the CP Dashboard under Settings → API Tokens.

Example

bash

curl https://api.computeportal.io/v1/services \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Error Responses

Status	Meaning
`401 Unauthorized`	Missing or malformed token
`403 Forbidden`	Token is valid but lacks permission for the requested resource

Rate Limits

The API is rate-limited per token. If you exceed the limit, you will receive a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait.

Errors

All error responses follow a consistent JSON shape:

json

{
  "error": "human-readable description",
  "code": "MACHINE_READABLE_CODE"
}

Common Error Codes

HTTP Status	Code	Description
`400`	`CNAME_NOT_CONFIGURED`	The hostname's DNS CNAME record does not point to `cpctl.app`
`400`	`DEFAULT_DOMAIN`	Attempt to remove a service's default `<service>.cpctl.app` domain
`401`	`UNAUTHORIZED`	Missing, expired, or invalid API token
`403`	`FORBIDDEN`	Token lacks permission for this resource
`404`	`NOT_FOUND`	Service or hostname does not exist
`409`	`CONFLICT`	Hostname is already attached to this or another service
`422`	`VALIDATION_ERROR`	Request body failed schema validation
`500`	`INTERNAL_ERROR`	Unexpected server error — contact support

Domains

Custom domains let you serve your CP service under your own hostname (e.g. dashboard.example.com) with automatic HTTPS. The default domain <service>.cpctl.app is always available and cannot be removed.

How Custom Domains Work

your domain (e.g. dashboard.example.com)
    │  CNAME → cpctl.app (DNS only)
    ▼
cpctl.app
    │
    ▼
public IP (nginx + Let's Encrypt cert, per hostname, auto-provisioned)
  - Proxy pass via internal network
    │
    ▼
compute cluster
  Traefik (routes by Host header via Docker Swarm service labels)
    │
    ▼
Docker Swarm service

Before attaching a domain, you must create a DNS record at your registrar:

Field	Value
Name	Your subdomain (e.g. `dashboard`)
Type	`CNAME`
Target	`cpctl.app`
Proxy	DNS only — do NOT enable Cloudflare proxying

POST /v1/services/:service/domains

Attach a custom hostname to a service. CP verifies the CNAME record, provisions an nginx virtual host and a Let's Encrypt TLS certificate on the VPS, and updates the Traefik routing label on the Docker Swarm service.

Path Parameters

Parameter	Type	Description
`service`	string	The service name (e.g. `cp-dashboard`)

Request Body

Field	Type	Required	Default	Description
`hostname`	string	Yes	—	The fully-qualified hostname to attach (e.g. `dashboard.example.com`)
`skip_dns`	boolean	No	`false`	Skip the DNS CNAME validation check. Use only for testing

Example Request

bash

curl -X POST https://api.computeportal.io/v1/services/cp-dashboard/domains \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06" \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "dashboard.example.com"
  }'

Example Response — 200 OK

json

{
  "hostname": "dashboard.example.com",
  "status": "active",
  "service": "cp-dashboard",
  "created_at": "2026-07-04T10:52:36.153Z"
}

What happens on the server:

Resolves the DNS CNAME for hostname and verifies it points to cpctl.app (skipped if skip_dns: true)
Writes a new nginx site configuration for the hostname on the edge proxy
Runs certbot --nginx to issue a Let's Encrypt certificate (HTTP-01 challenge)
Reloads nginx to activate the new virtual host
Updates the Traefik Host router label on the Swarm service to include the new hostname

Error Responses

Status	Condition
`400 Bad Request`	CNAME record not found or not pointing to `cpctl.app`
`404 Not Found`	The specified service does not exist
`409 Conflict`	The hostname is already registered
`422 Unprocessable Entity`	Request body is malformed or `hostname` is missing
`500 Internal Server Error`	nginx or certbot provisioning failed

Testing Without DNS

If your DNS record is not yet propagated, pass skip_dns: true to bypass the CNAME check. The domain will be registered but traffic will not route correctly until the DNS record is active.

bash

curl -X POST https://api.computeportal.io/v1/services/cp-dashboard/domains \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06" \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "dashboard.example.com",
    "skip_dns": true
  }'

GET /v1/services/:service/domains

List all hostnames attached to a service — including the default <service>.cpctl.app domain.

Path Parameters

Parameter	Type	Description
`service`	string	The service name (e.g. `cp-dashboard`)

Example Request

bash

curl https://api.computeportal.io/v1/services/cp-dashboard/domains \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Example Response — 200 OK

json

{
  "domains": [
    {
      "hostname": "cp-dashboard.computeportal.io",
      "status": "active",
      "created_at": null
    },
    {
      "hostname": "dashboard.example.com",
      "status": "active",
      "created_at": "2026-07-04T10:52:36.153Z"
    }
  ]
}

Response Schema

Field	Type	Description
`domains`	array	List of domain objects
`domains[].hostname`	string	Fully-qualified hostname
`domains[].status`	string	Always `"active"` for attached domains
`domains[].created_at`	string \| null	ISO 8601 timestamp. `null` for the default service domain

Error Responses

Status	Condition
`404 Not Found`	The specified service does not exist

DELETE /v1/services/:service/domains/:hostname

Remove a custom hostname from a service. This removes the nginx virtual host configuration and TLS certificate from the VPS, and removes the hostname from the Traefik routing label.

The default <service>.cpctl.app domain cannot be removed.

Path Parameters

Parameter	Type	Description
`service`	string	The service name (e.g. `cp-dashboard`)
`hostname`	string	The hostname to remove (e.g. `dashboard.example.com`)

Example Request

bash

curl -X DELETE \
  https://api.computeportal.io/v1/services/cp-dashboard/domains/dashboard.example.com \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Response — 204 No Content

No response body is returned on success.

What happens on the server:

Removes the nginx site configuration file for the hostname from the VPS
Deletes the Let's Encrypt certificate via certbot delete
Reloads nginx
Removes the hostname from the Traefik Host router label on the Swarm service

Error Responses

Status	Condition
`400 Bad Request`	Attempt to remove the default `<service>.cpctl.app` domain
`404 Not Found`	The service or hostname does not exist

Services

Services are Docker Swarm services running on CP compute infrastructure. Each service maps to a deployed AI/ML workload.

GET /v1/services

List all services in your CP account.

Example Request

bash

curl https://api.computeportal.io/v1/services \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Example Response — 200 OK

json

{
  "services": [
    {
      "name": "ml-inference",
      "image": "registry.example.com/model:v2",
      "status": "running",
      "replicas": { "running": 2, "desired": 2 },
      "created_at": "2026-07-01T08:00:00.000Z"
    }
  ]
}

POST /v1/services

Deploy a new service from a Docker image.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Service name (e.g. `ml-inference`)
`image`	string	Yes	Container image reference
`replicas`	integer	No	Initial replica count. Default: `1`
`port`	integer	No	Port the container listens on. Default: `8080`
`env`	object	No	Key-value environment variables to set at creation

Example Request

bash

curl -X POST https://api.computeportal.io/v1/services \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ml-inference",
    "image": "registry.example.com/model:v2",
    "replicas": 2,
    "port": 8080
  }'

Example Response — 200 OK

json

{
  "name": "ml-inference",
  "image": "registry.example.com/model:v2",
  "status": "deploying",
  "replicas": { "running": 0, "desired": 2 },
  "url": "https://ml-inference.cpctl.app",
  "created_at": "2026-07-08T09:00:00.000Z"
}

GET /v1/services/:name

Get details for a specific service.

Path Parameters

Parameter	Type	Description
`name`	string	The service name (e.g. `ml-inference`)

Example Request

bash

curl https://api.computeportal.io/v1/services/ml-inference \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Example Response — 200 OK

json

{
  "name": "ml-inference",
  "image": "registry.example.com/model:v2",
  "status": "running",
  "replicas": { "running": 2, "desired": 2 },
  "url": "https://ml-inference.cpctl.app",
  "port": 8080,
  "created_at": "2026-07-01T08:00:00.000Z"
}

DELETE /v1/services/:name

Delete a service and all associated resources.

Path Parameters

Parameter	Type	Description
`name`	string	The service name to delete

Example Request

bash

curl -X DELETE https://api.computeportal.io/v1/services/ml-inference \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Response — 204 No Content

POST /v1/services/:name/start

Start a stopped service.

Path Parameters

Parameter	Type	Description
`name`	string	The service name

Example Request

bash

curl -X POST https://api.computeportal.io/v1/services/ml-inference/start \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Example Response — 200 OK

json

{ "name": "ml-inference", "status": "starting" }

POST /v1/services/:name/stop

Stop a running service. The service is kept but all replicas are brought down.

Path Parameters

Parameter	Type	Description
`name`	string	The service name

Example Request

bash

curl -X POST https://api.computeportal.io/v1/services/ml-inference/stop \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Example Response — 200 OK

json

{ "name": "ml-inference", "status": "stopped" }

POST /v1/services/:name/restart

Trigger a rolling restart of all service replicas.

Path Parameters

Parameter	Type	Description
`name`	string	The service name

Example Request

bash

curl -X POST https://api.computeportal.io/v1/services/ml-inference/restart \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Example Response — 200 OK

json

{ "name": "ml-inference", "status": "restarting" }

POST /v1/services/:name/redeploy

Re-trigger the current deployment without changing the image or configuration.

Path Parameters

Parameter	Type	Description
`name`	string	The service name

Example Request

bash

curl -X POST https://api.computeportal.io/v1/services/ml-inference/redeploy \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Example Response — 200 OK

json

{ "name": "ml-inference", "status": "deploying" }

POST /v1/services/:name/scale

Scale a service to a target replica count.

Path Parameters

Parameter	Type	Description
`name`	string	The service name

Request Body

Field	Type	Required	Description
`replicas`	integer	Yes	Target replica count

Example Request

bash

curl -X POST https://api.computeportal.io/v1/services/ml-inference/scale \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06" \
  -H "Content-Type: application/json" \
  -d '{ "replicas": 3 }'

Example Response — 200 OK

json

{ "name": "ml-inference", "replicas": { "running": 2, "desired": 3 } }

POST /v1/services/:name/rollback

Roll back a service to its previous deployment.

Path Parameters

Parameter	Type	Description
`name`	string	The service name

Request Body

Field	Type	Required	Description
`deployment_id`	string	No	Specific deployment ID to roll back to. Omit for the last stable deployment

Example Request

bash

curl -X POST https://api.computeportal.io/v1/services/ml-inference/rollback \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Example Response — 200 OK

json

{ "name": "ml-inference", "status": "deploying", "rolled_back_to": "deploy_8f3a1b" }

GET /v1/services/:name/logs

Fetch recent log output from a service.

Path Parameters

Parameter	Type	Description
`name`	string	The service name

Query Parameters

Parameter	Type	Description
`tail`	integer	Number of most recent log lines to return. Default: `100`

Example Request

bash

curl "https://api.computeportal.io/v1/services/ml-inference/logs?tail=50" \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Example Response — 200 OK

json

{
  "lines": [
    { "ts": "2026-07-08T09:11:58Z", "msg": "Model loaded in 2.3s" },
    { "ts": "2026-07-08T09:12:00Z", "msg": "Listening on :8080" }
  ]
}

GET /v1/services/:name/metrics

Get CPU, memory, and network metrics for a service.

Path Parameters

Parameter	Type	Description
`name`	string	The service name

Example Request

bash

curl https://api.computeportal.io/v1/services/ml-inference/metrics \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Example Response — 200 OK

json

{
  "service": "ml-inference",
  "cpu_percent": 34.2,
  "memory_mb": 2048,
  "network_in_kbps": 120,
  "network_out_kbps": 95
}

GET /v1/services/:name/gpu

Get GPU utilization metrics for a service.

Path Parameters

Parameter	Type	Description
`name`	string	The service name

Example Request

bash

curl https://api.computeportal.io/v1/services/ml-inference/gpu \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Example Response — 200 OK

json

{
  "service": "ml-inference",
  "gpu_utilization_percent": 72,
  "gpu_memory_used_mb": 14336,
  "gpu_memory_total_mb": 20480
}

GET /v1/services/:name/deployments

List the deployment history for a service.

Path Parameters

Parameter	Type	Description
`name`	string	The service name

Example Request

bash

curl https://api.computeportal.io/v1/services/ml-inference/deployments \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Example Response — 200 OK

json

{
  "deployments": [
    { "id": "deploy_8f3a1b", "image": "registry.example.com/model:v2", "status": "succeeded", "created_at": "2026-07-08T08:00:00Z" },
    { "id": "deploy_7c2e09", "image": "registry.example.com/model:v1", "status": "succeeded", "created_at": "2026-07-01T08:00:00Z" }
  ]
}

GET /v1/services/:name/deployments/:id

Get details for a specific deployment.

Path Parameters

Parameter	Type	Description
`name`	string	The service name
`id`	string	The deployment ID (e.g. `deploy_8f3a1b`)

Example Request

bash

curl https://api.computeportal.io/v1/services/ml-inference/deployments/deploy_8f3a1b \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Example Response — 200 OK

json

{
  "id": "deploy_8f3a1b",
  "service": "ml-inference",
  "image": "registry.example.com/model:v2",
  "status": "succeeded",
  "replicas": 2,
  "created_at": "2026-07-08T08:00:00Z",
  "finished_at": "2026-07-08T08:01:15Z"
}

GET /v1/services/:name/env

List all environment variables set on a service.

Path Parameters

Parameter	Type	Description
`name`	string	The service name

Example Request

bash

curl https://api.computeportal.io/v1/services/ml-inference/env \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Example Response — 200 OK

json

{
  "env": {
    "MODEL_PATH": "/models/v2",
    "BATCH_SIZE": "32"
  }
}

POST /v1/services/:name/env

Set one or more environment variables on a service. Triggers a rolling restart.

Path Parameters

Parameter	Type	Description
`name`	string	The service name

Request Body

Field	Type	Required	Description
`env`	object	Yes	Key-value map of variables to set

Example Request

bash

curl -X POST https://api.computeportal.io/v1/services/ml-inference/env \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06" \
  -H "Content-Type: application/json" \
  -d '{ "env": { "MODEL_PATH": "/models/v2", "BATCH_SIZE": "32" } }'

Example Response — 200 OK

json

{ "updated": ["MODEL_PATH", "BATCH_SIZE"] }

POST /v1/services/:name/env/unset

Remove one or more environment variables from a service. Triggers a rolling restart.

Path Parameters

Parameter	Type	Description
`name`	string	The service name

Request Body

Field	Type	Required	Description
`keys`	array	Yes	List of variable names to remove

Example Request

bash

curl -X POST https://api.computeportal.io/v1/services/ml-inference/env/unset \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06" \
  -H "Content-Type: application/json" \
  -d '{ "keys": ["DEBUG"] }'

Example Response — 200 OK

json

{ "removed": ["DEBUG"] }

GET /v1/services/:name/volumes

List persistent volumes attached to a service.

Path Parameters

Parameter	Type	Description
`name`	string	The service name

Example Request

bash

curl https://api.computeportal.io/v1/services/ml-inference/volumes \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Example Response — 200 OK

json

{
  "volumes": [
    { "name": "ml-data", "path": "/data", "size": "10Gi", "created_at": "2026-07-01T08:00:00Z" }
  ]
}

GET /v1/status

Platform health check. Returns the operational status of the CP API.

Example Request

bash

curl https://api.computeportal.io/v1/status

Example Response — 200 OK

json

{ "status": "ok", "version": "v1" }

GPU & Nodes

GET /v1/gpu/nodes

List GPU nodes and their current availability.

Example Request

bash

curl https://api.computeportal.io/v1/gpu/nodes \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Example Response — 200 OK

json

{
  "nodes": [
    { "id": "dgx-node-01", "gpu_model": "H100", "gpu_count": 8, "available": 3, "region": "us-east-1" }
  ]
}

POST /v1/gpu/reserve

Reserve GPU capacity on a node.

Request Body

Field	Type	Required	Description
`node_id`	string	Yes	The GPU node ID to reserve on
`gpu_count`	integer	Yes	Number of GPUs to reserve
`duration_hours`	integer	No	Reservation duration in hours. Default: `1`

Example Request

bash

curl -X POST https://api.computeportal.io/v1/gpu/reserve \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06" \
  -H "Content-Type: application/json" \
  -d '{ "node_id": "dgx-node-01", "gpu_count": 2, "duration_hours": 4 }'

Example Response — 200 OK

json

{
  "reservation_id": "res_7f2a3c",
  "node_id": "dgx-node-01",
  "gpu_count": 2,
  "expires_at": "2026-07-08T13:00:00Z"
}

POST /v1/gpu/jobs

Run a one-shot GPU job (non-persistent service).

Request Body

Field	Type	Required	Description
`image`	string	Yes	Container image to run
`command`	string	No	Command to execute inside the container
`gpu_count`	integer	No	Number of GPUs to allocate. Default: `1`

Example Request

bash

curl -X POST https://api.computeportal.io/v1/gpu/jobs \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06" \
  -H "Content-Type: application/json" \
  -d '{ "image": "registry.example.com/train:latest", "gpu_count": 4 }'

Example Response — 200 OK

json

{ "job_id": "job_4b9d12", "status": "queued", "created_at": "2026-07-08T09:00:00Z" }

GET /v1/gpu/jobs/:id/logs

Get log output for a GPU job.

Path Parameters

Parameter	Type	Description
`id`	string	The GPU job ID (e.g. `job_4b9d12`)

Example Request

bash

curl https://api.computeportal.io/v1/gpu/jobs/job_4b9d12/logs \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Example Response — 200 OK

json

{
  "lines": [
    { "ts": "2026-07-08T09:01:00Z", "msg": "Epoch 1/10 — loss: 0.8421" },
    { "ts": "2026-07-08T09:02:30Z", "msg": "Epoch 2/10 — loss: 0.6103" }
  ]
}

GET /v1/nodes

List all compute nodes in the CP cluster.

Example Request

bash

curl https://api.computeportal.io/v1/nodes \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Example Response — 200 OK

json

{
  "nodes": [
    { "id": "node-01", "region": "us-east-1", "status": "active", "role": "worker" }
  ]
}

GET /v1/nodes/:id

Get details and health information for a specific compute node.

Path Parameters

Parameter	Type	Description
`id`	string	The node ID (e.g. `node-01`)

Example Request

bash

curl https://api.computeportal.io/v1/nodes/node-01 \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Example Response — 200 OK

json

{
  "id": "node-01",
  "region": "us-east-1",
  "status": "active",
  "cpu_cores": 64,
  "memory_gb": 256,
  "gpu_count": 8,
  "uptime_hours": 720
}

GET /v1/nodes/self-hosted

List self-hosted nodes registered to your CP account.

Example Request

bash

curl https://api.computeportal.io/v1/nodes/self-hosted \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Example Response — 200 OK

json

{
  "nodes": [
    { "id": "sh-node-01", "hostname": "my-server.example.com", "status": "connected", "registered_at": "2026-06-01T10:00:00Z" }
  ]
}

GET /v1/regions

List all available CP regions.

Example Request

bash

curl https://api.computeportal.io/v1/regions \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Example Response — 200 OK

json

{
  "regions": [
    { "id": "us-east-1", "name": "US East (Virginia)", "available": true },
    { "id": "eu-west-1", "name": "EU West (Ireland)", "available": true }
  ]
}

Databases

GET /v1/databases

List all managed databases in your CP account.

Example Request

bash

curl https://api.computeportal.io/v1/databases \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Example Response — 200 OK

json

{
  "databases": [
    { "name": "app-db", "type": "postgres", "status": "running", "created_at": "2026-06-15T10:00:00Z" }
  ]
}

POST /v1/databases

Create a new managed database.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Database name (e.g. `app-db`)
`type`	string	Yes	Database engine: `postgres`, `mysql`, or `redis`
`version`	string	No	Engine version. Default: latest stable

Example Request

bash

curl -X POST https://api.computeportal.io/v1/databases \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06" \
  -H "Content-Type: application/json" \
  -d '{ "name": "app-db", "type": "postgres" }'

Example Response — 200 OK

json

{
  "name": "app-db",
  "type": "postgres",
  "status": "provisioning",
  "connection_url": "postgres://cp:secret@app-db.internal:5432/app-db",
  "created_at": "2026-07-08T09:00:00Z"
}

GET /v1/databases/:name

Get details and connection information for a specific database.

Path Parameters

Parameter	Type	Description
`name`	string	The database name

Example Request

bash

curl https://api.computeportal.io/v1/databases/app-db \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Example Response — 200 OK

json

{
  "name": "app-db",
  "type": "postgres",
  "status": "running",
  "connection_url": "postgres://cp:secret@app-db.internal:5432/app-db",
  "created_at": "2026-06-15T10:00:00Z"
}

DELETE /v1/databases/:name

Destroy a managed database and all its data. This action is irreversible.

Path Parameters

Parameter	Type	Description
`name`	string	The database name to destroy

Example Request

bash

curl -X DELETE https://api.computeportal.io/v1/databases/app-db \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Response — 204 No Content

Environments

GET /v1/environments

List all environments in your CP account (e.g. production, staging).

Example Request

bash

curl https://api.computeportal.io/v1/environments \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Example Response — 200 OK

json

{
  "environments": [
    { "name": "production", "created_at": "2026-06-01T00:00:00Z" },
    { "name": "staging", "created_at": "2026-06-15T00:00:00Z" }
  ]
}

POST /v1/environments

Create a new environment.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Environment name (e.g. `staging`)

Example Request

bash

curl -X POST https://api.computeportal.io/v1/environments \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06" \
  -H "Content-Type: application/json" \
  -d '{ "name": "staging" }'

Example Response — 200 OK

json

{ "name": "staging", "created_at": "2026-07-08T09:00:00Z" }

DELETE /v1/environments/:name

Delete an environment. Services in the environment must be removed first.

Path Parameters

Parameter	Type	Description
`name`	string	The environment name to delete

Example Request

bash

curl -X DELETE https://api.computeportal.io/v1/environments/staging \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Response — 204 No Content

Sandboxes

GET /v1/sandboxes

List all sandboxes in your CP account.

Example Request

bash

curl https://api.computeportal.io/v1/sandboxes \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Example Response — 200 OK

json

{
  "sandboxes": [
    { "id": "sbx_3d9f1a", "status": "running", "created_at": "2026-07-08T08:00:00Z", "expires_at": "2026-07-08T16:00:00Z" }
  ]
}

POST /v1/sandboxes

Create a new sandbox — an ephemeral compute environment for short-lived workloads.

Request Body

Field	Type	Required	Description
`image`	string	No	Container image to use. Default: CP base image
`ttl_hours`	integer	No	Time-to-live in hours before the sandbox auto-destroys. Default: `8`

Example Request

bash

curl -X POST https://api.computeportal.io/v1/sandboxes \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06" \
  -H "Content-Type: application/json" \
  -d '{ "ttl_hours": 4 }'

Example Response — 200 OK

json

{
  "id": "sbx_3d9f1a",
  "status": "starting",
  "url": "https://sbx_3d9f1a.cpctl.app",
  "created_at": "2026-07-08T09:00:00Z",
  "expires_at": "2026-07-08T13:00:00Z"
}

DELETE /v1/sandboxes/:id

Destroy a sandbox immediately, before its TTL expires.

Path Parameters

Parameter	Type	Description
`id`	string	The sandbox ID (e.g. `sbx_3d9f1a`)

Example Request

bash

curl -X DELETE https://api.computeportal.io/v1/sandboxes/sbx_3d9f1a \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Response — 204 No Content

Machine Payments

GET /v1/pay/status

Get the currently linked payment method for your CP account.

Example Request

bash

curl https://api.computeportal.io/v1/pay/status \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Example Response — 200 OK

json

{
  "method": "card",
  "last4": "4242",
  "brand": "visa",
  "linked_at": "2026-06-01T10:00:00Z"
}

POST /v1/pay/setup

Start a card or USDC wallet setup flow. Returns a Stripe-hosted URL to complete the process.

Request Body

Field	Type	Required	Description
`method`	string	Yes	Payment method type: `card` or `usdc`
`return_url`	string	No	URL to redirect to after setup completes

Example Request

bash

curl -X POST https://api.computeportal.io/v1/pay/setup \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06" \
  -H "Content-Type: application/json" \
  -d '{ "method": "card" }'

Example Response — 200 OK

json

{
  "setup_url": "https://checkout.stripe.com/pay/cs_live_...",
  "expires_at": "2026-07-08T09:30:00Z"
}

GET /v1/pay/setup/poll

Poll for completion of a payment method setup flow started via POST /v1/pay/setup.

Example Request

bash

curl https://api.computeportal.io/v1/pay/setup/poll \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Example Response — 200 OK

json

{ "status": "complete", "method": "card", "last4": "4242" }

POST /v1/pay/authorize

Pre-authorize a per-call charge for a service. Used for metered billing on GPU inference endpoints.

Request Body

Field	Type	Required	Description
`service`	string	Yes	The service name to authorize charges for
`amount_usd`	number	Yes	Maximum charge amount in USD to authorize

Example Request

bash

curl -X POST https://api.computeportal.io/v1/pay/authorize \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06" \
  -H "Content-Type: application/json" \
  -d '{ "service": "ml-inference", "amount_usd": 5.00 }'

Example Response — 200 OK

json

{
  "authorization_id": "auth_9c1f2a",
  "service": "ml-inference",
  "amount_usd": 5.00,
  "expires_at": "2026-07-08T17:00:00Z"
}

GET /v1/pay/history

List all per-call payment charges on your account.

Example Request

bash

curl https://api.computeportal.io/v1/pay/history \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Example Response — 200 OK

json

{
  "charges": [
    { "id": "chg_1a2b3c", "service": "ml-inference", "amount_usd": 1.25, "created_at": "2026-07-07T14:00:00Z" }
  ]
}

Billing

GET /v1/billing/usage

Get usage totals for the current billing cycle.

Example Request

bash

curl https://api.computeportal.io/v1/billing/usage \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Example Response — 200 OK

json

{
  "cycle_start": "2026-07-01T00:00:00Z",
  "cycle_end": "2026-07-31T23:59:59Z",
  "total_usd": 128.40,
  "breakdown": {
    "compute": 100.00,
    "gpu": 24.00,
    "storage": 4.40
  }
}

GET /v1/billing/history

List past invoices.

Example Request

bash

curl https://api.computeportal.io/v1/billing/history \
  -H "Authorization: Bearer cp_live_4a7f3b9c2e1d8a06"

Example Response — 200 OK

json

{
  "invoices": [
    { "id": "inv_2026_06", "period": "June 2026", "total_usd": 112.80, "status": "paid", "url": "https://dashboard.computeportal.io/inv_2026_06.pdf" }
  ]
}

Versioning

The current API version is v1. The version is part of every URL path: /v1/....

Breaking changes will be introduced under a new version prefix (e.g. /v2/...). Non-breaking additions (new fields, new endpoints) may be added to the current version at any time.

Infrastructure Reference

Component	Value
API base URL	`https://api.computeportal.io`
CNAME target	`cpctl.app`
Edge proxy	Public IP running nginx + certbot
Edge → cluster	Internal private network
Default service domain	`<service-name>.cpctl.app`
TLS	Let's Encrypt (HTTP-01 via certbot)
Ingress	Traefik on Docker Swarm

SDK and Tools

In addition to direct HTTP calls, you can interact with the CP API through:

CP CLI — command-line interface for managing services and domains
CP MCP Server — AI assistant integration at https://mcp.computeportal.io/mcp (see MCP Server Reference)

Support

Dashboard: https://dashboard.computeportal.io
Docs: https://docs.computeportal.io

CP API Reference ​

Authentication ​

Example ​

Error Responses ​

Rate Limits ​

Errors ​

Common Error Codes ​

Domains ​

How Custom Domains Work ​

POST /v1/services/:service/domains ​

GET /v1/services/:service/domains ​

DELETE /v1/services/:service/domains/:hostname ​

Services ​

GET /v1/services ​

POST /v1/services ​

GET /v1/services/:name ​

DELETE /v1/services/:name ​

POST /v1/services/:name/start ​

POST /v1/services/:name/stop ​

POST /v1/services/:name/restart ​

POST /v1/services/:name/redeploy ​

POST /v1/services/:name/scale ​

POST /v1/services/:name/rollback ​

GET /v1/services/:name/logs ​

GET /v1/services/:name/metrics ​

GET /v1/services/:name/gpu ​

GET /v1/services/:name/deployments ​

GET /v1/services/:name/deployments/:id ​

GET /v1/services/:name/env ​

POST /v1/services/:name/env ​

POST /v1/services/:name/env/unset ​

GET /v1/services/:name/volumes ​

GET /v1/status ​

GPU & Nodes ​

GET /v1/gpu/nodes ​

POST /v1/gpu/reserve ​

POST /v1/gpu/jobs ​

GET /v1/gpu/jobs/:id/logs ​

GET /v1/nodes ​

GET /v1/nodes/:id ​

GET /v1/nodes/self-hosted ​

GET /v1/regions ​

Databases ​

GET /v1/databases ​

POST /v1/databases ​

GET /v1/databases/:name ​

DELETE /v1/databases/:name ​

Environments ​

GET /v1/environments ​

POST /v1/environments ​

DELETE /v1/environments/:name ​

Sandboxes ​

GET /v1/sandboxes ​

POST /v1/sandboxes ​

DELETE /v1/sandboxes/:id ​

Machine Payments ​

GET /v1/pay/status ​

POST /v1/pay/setup ​

GET /v1/pay/setup/poll ​

POST /v1/pay/authorize ​

GET /v1/pay/history ​

Billing ​

GET /v1/billing/usage ​

GET /v1/billing/history ​

Versioning ​

Infrastructure Reference ​

SDK and Tools ​

Support ​

CP API Reference

Authentication

Example

Error Responses

Rate Limits

Errors

Common Error Codes

Domains

How Custom Domains Work

POST /v1/services/:service/domains

GET /v1/services/:service/domains

DELETE /v1/services/:service/domains/:hostname

Services

GET /v1/services

POST /v1/services

GET /v1/services/:name

DELETE /v1/services/:name

POST /v1/services/:name/start

POST /v1/services/:name/stop

POST /v1/services/:name/restart

POST /v1/services/:name/redeploy

POST /v1/services/:name/scale

POST /v1/services/:name/rollback

GET /v1/services/:name/logs

GET /v1/services/:name/metrics

GET /v1/services/:name/gpu

GET /v1/services/:name/deployments

GET /v1/services/:name/deployments/:id

GET /v1/services/:name/env

POST /v1/services/:name/env

POST /v1/services/:name/env/unset

GET /v1/services/:name/volumes

GET /v1/status

GPU & Nodes

GET /v1/gpu/nodes

POST /v1/gpu/reserve

POST /v1/gpu/jobs

GET /v1/gpu/jobs/:id/logs

GET /v1/nodes

GET /v1/nodes/:id

GET /v1/nodes/self-hosted

GET /v1/regions

Databases

GET /v1/databases

POST /v1/databases

GET /v1/databases/:name

DELETE /v1/databases/:name

Environments

GET /v1/environments

POST /v1/environments

DELETE /v1/environments/:name

Sandboxes

GET /v1/sandboxes

POST /v1/sandboxes

DELETE /v1/sandboxes/:id

Machine Payments

GET /v1/pay/status

POST /v1/pay/setup

GET /v1/pay/setup/poll

POST /v1/pay/authorize

GET /v1/pay/history

Billing

GET /v1/billing/usage

GET /v1/billing/history

Versioning

Infrastructure Reference

SDK and Tools

Support