API Reference

The Ghayma API is a RESTful API at https://api.ghayma.tech/api/v1/.

Base URL

https://api.ghayma.tech/api/v1

Authentication

Most endpoints require a Bearer credential in the Authorization header:

curl https://api.ghayma.tech/api/v1/projects \
  -H "Authorization: Bearer YOUR_TOKEN"

Two long-lived credentials open the API — plus the JWT that /api/v1/auth/login returns, which is what the dashboard itself uses.

Account token (gh_…) — created in Settings → API Tokens in the dashboard. It acts as you: every project you can reach and your account routes, within the scopes you gave the token — or only the projects you restrict it to. This is the credential the ghayma CLI stores on your machine, and the one an orchestrator or a pipeline holds. Tokens take an expiry, rotate in place and revoke without losing their history — see Account Tokens.

Project API key (gsk_…) — created in Project → Settings → API keys. It belongs to one project, not to a person, and reaches a deny-by-default allowlist of that project’s application routes: auth-app user administration, storage objects, database connection details, and, for a CI key, the deploy routes. See Project API Keys.

With a project API key, a request for a resource in another project answers 404, and a route outside the allowlist answers 403.

End-user authentication

Your auth apps’ end users sign in against the auth service at https://auth.ghayma.tech, a separate API with its own OpenAPI document. See Auth Service API.

Response Format

All responses return JSON. Successful responses include the data directly. Errors return:

{
  "error": "Description of the error"
}

HTTP Status Codes

Rate Limits

Rate limits are per route and per client IP, not per plan. A short list of sensitive routes is limited (sign-in and registration, password and email changes, database and storage maintenance operations such as resize, refresh, query and bulk delete); a limited call answers 429 with a Retry-After header and the X-RateLimit-Limit / X-RateLimit-Remaining headers. Ordinary project, deployment, domain and billing calls are not rate limited.

Endpoints