API overview

The customer API lets scripts and CI pipelines do what you do in the dashboard: create and deploy projects, change configuration, manage domains, and work with databases and backups. Every endpoint, with its permission, parameters and an example request, is in the API reference.

#Base URL and authentication

All endpoints live under /api/customer/v1 on the dashboard's own address. Send an API key as a bearer token in the Authorization header, never in the URL.

List the projects your key can see:

curl "https://hcode.hostafrica.com/api/customer/v1/projects" \
  --header "Authorization: Bearer $HCODE_API_KEY"

The response includes the project IDs the other endpoints need. Every request is limited by both the key's permissions and your current role in the organisation.

The OpenAPI document is at https://hcode.hostafrica.com/docs/api/openapi.json if you want to import the API into an HTTP client.

#Queued work

Deploys, restarts, backups, restores, imports and other long jobs outlive the request. The API answers HTTP 202 with an operationId. Poll Get operation progress with it until the status is succeeded, failed or cancelled. Failure and cancellation are final results too, so check which one you got.

Saving configuration and deploying are separate calls. Change the project or its variables first, then deploy.

#Idempotency keys

Endpoints that queue work need an Idempotency-Key header. Use a fresh unique value for each new request, and send the same value again when you retry that exact request after a timeout. Reusing a key with a different body returns HTTP 409.

A refusal and a conflict need different handling:

• A refusal, such as workload_busy or project_deleting, or a 403 such as org_suspended, started nothing. It isn't recorded against the key, so retry with the same key once the reason has cleared.
• A conflict, such as conflict, deployment_in_progress or idempotency_in_progress, means the work, or work standing in for it, already exists. A retry with the same key gets the same answer. Follow the existing work instead of sending it again.

#Lists and logs

List endpoints that page their results return nextCursor. Pass it back as cursor to get the next page; null means there are no more.

Runtime log reads return the latest 200 lines by default; set tail for up to 500. Deployment logs can be read in chunks. Both can also be streamed.

#Errors

Errors carry a stable code, a message and a request ID:

{
  "error": {
    "code": "forbidden",
    "message": "Credential does not permit this operation",
    "requestId": "REQUEST_ID",
    "retryable": false
  }
}

Keep the request ID if you contact support.

#Limits

#Usage and plan limits

getCapabilities returns your plan's limits and current usage: build minutes for this month, and memory, storage, bandwidth and build signals, each with its state. enforcing is true while a signal is pausing new work. If usage can't be read, those fields are null and usageStatusUnavailable is true; don't treat that as zero.

#What stays in the dashboard

The API doesn't cover team members and invites, creating or leaving organisations, billing and plans, account settings, managing API keys and integrations, or installing the GitHub App.