Build with the HCode API

Create a key

Open API keys in your organisation settings. Give the key a name, choose a project or the organisation, and select its permissions. Save the secret when it appears; it is shown once.

A project key works only within that project. Use an organisation key to create projects or automate across several projects. Every request is limited by both the key's scopes and your current role.

Keys expire after 90 days by default and can last at most 365 days. Create a replacement, update your integration, then revoke the old key. Secret reads, SQL, imports, restores and deletion need explicit permissions.

Make your first request

Use your dashboard's origin as HCODE_BASE_URL. Send the key in the authorization header, not in the URL.

export HCODE_BASE_URL="https://hcode.hostafrica.com"
export HCODE_API_KEY="YOUR_API_KEY"

curl "$HCODE_BASE_URL/api/customer/v1/projects" \
  --header "Authorization: Bearer $HCODE_API_KEY"

List projects returns the IDs you need for project requests. All endpoint paths start with /api/customer/v1.

Wait for queued work

Deployment, provisioning and backup work can outlive the request. HTTP 202 means the request was accepted. Use the returned operationId with Get operation progress until it reaches a terminal state.

Where required, supply an Idempotency-Key. Reuse it for the same request after a timeout. A reused key with different input returns a conflict. If the outcome is uncertain, inspect the project operations before submitting new work.

Read lists and logs

List endpoints with cursor support return nextCursor. Pass it back as cursor; a null cursor means you have reached the end. Check each endpoint for its supported filters and limits.

Runtime logs are bounded snapshots of the latest entries. Deployment logs support chunked reads. The REST API and SDKs also expose log streams; MCP uses bounded reads.

Errors and retries

Error responses include a stable code, a message and a request ID. Keep the request ID when asking for help. Avoid logging response bodies that contain secrets.

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

Limits are shared across requests: 120 per minute for a credential and 600 per organisation. JSON bodies are limited to 1 MiB; proxied file uploads are limited to 100 MiB and a 30-second body deadline. Prefer direct uploads for large files.

SDKs and MCP

The SDK packages are @hcode/sdk for TypeScript and hcode-sdk for Python. Package publication is a separate release step; use the source packages while this preview is under development.

import { HCodeClient } from '@hcode/sdk';

const client = new HCodeClient({
  baseUrl: process.env.HCODE_BASE_URL!,
  apiKey: process.env.HCODE_API_KEY!
});
const { projects } = await client.listProjects();

import os
from hcode_sdk import HCodeClient

client = HCodeClient(
    os.environ['HCODE_BASE_URL'],
    os.environ['HCODE_API_KEY'],
)
projects = client.list_projects()

Local MCP runs hcode-mcp with HCODE_BASE_URL and HCODE_API_KEY in its environment. Include credential:read so the client can discover its permissions.

Hosted MCP uses /mcp. Configure a bearer key or use the client's browser sign-in flow to choose an organisation, project and permissions. Revoke OAuth access from Integrations.

Download the OpenAPI specification to import the API into your own tools.