# Orizon Public API — full reference for agents

Orizon is a deployment platform. This file is the complete public-API surface in
one place, optimized for LLM agents. For prose docs see https://orzn.io/docs/api
and for the machine-readable spec see https://api.orizon.ng/api/v1/openapi.json.

Base URL: https://api.orizon.ng/api/v1
Auth:     every request needs a platform API key sent as a Bearer token:
            Authorization: Bearer orz_pk_…
          Keys are org-scoped and either "full" (read + write) or "read" (GET
          only). Create one at https://dashboard.orizon.ng/api-keys — the secret
          is shown once.

Responses
  Success: { "data": <result>, "meta"?: { total, offset, limit } }
  Error:   { "error": { "code": "<machine_code>", "message": "<human text>" } }
           codes: invalid_request, unauthorized, forbidden, not_found,
           rate_limited, plan_limit, deploy_failed, internal_error.

Conventions
  - {id}-style path segments are required path parameters.
  - List endpoints accept ?limit (1–200) and ?offset for pagination; meta.total
    is always returned.
  - Rate limit: 20 requests/second per key; 429 + Retry-After when exceeded.
  - A trailing "[write]" means the endpoint needs a full (read+write) key.
  - In the param lists below, a trailing "*" marks a required parameter.

Total operations: 92

Endpoints by resource

## projects (6)
  GET /projects — List the caller's Orizon projects (hosted apps/sites) [read]
  POST /projects — Create a project (the container for a deployed app or site) [write] · body: name*, repositoryUrl, productionBranch, rootDirectory, buildCommand, githubInstallationId
  GET /projects/{id} — Get one project's full configuration and live URL [read]
  PATCH /projects/{id} — Update mutable project settings [write] · body: name, productionBranch, rootDirectory, buildCommand, framework, githubInstallationId
  GET /projects/{id}/static-routing — Get static-site URL routing mode [read]
  PUT /projects/{id}/static-routing — Set static-site URL routing mode [write] · body: mode*

## github (1)
  GET /github/installations — List this org's connected GitHub App installations [read]

## deployments (4)
  GET /projects/{id}/deployments — List a project's deployments / deploy history (newest first) [read] · query: limit, offset
  POST /projects/{id}/deployments — Deploy a project — build and ship it live [write] · body: branch, commitSha, sourceTarballUrl
  GET /deployments/{id} — Get one deployment's status (is it live yet?) [read]
  GET /deployments/{id}/logs — Get a deployment's build and runtime logs [read] · query: source

## uploads (1)
  POST /uploads — Upload source (a zip) for an upload-only deploy [write]

## env (2)
  GET /projects/{id}/env — List a project's environment variables (names, not secrets) [read]
  PUT /projects/{id}/env — Set environment variables / secrets for a project [write] · body: variables*

## databases (11)
  GET /databases — List managed databases [read]
  POST /databases — Provision a managed database [write] · body: name*, engine*, version, databaseName, username
  GET /databases/{id} — Get a managed database [read]
  DELETE /databases/{id} — Delete a managed database [write]
  POST /databases/{id}/stop — Stop a managed database [write]
  POST /databases/{id}/start — Start a managed database [write]
  POST /databases/{id}/restart — Restart a managed database [write]
  GET /databases/{id}/stats — Get live stats for a managed database [read]
  GET /databases/{id}/logs — Get recent container logs for a managed database [read] · query: tail
  POST /databases/{id}/users — Add a connection user to a managed database [write] · body: username*, password
  DELETE /databases/{id}/users/{username} — Remove a connection user from a managed database [write]

## domains (5)
  GET /projects/{id}/domains — List a project's domains [read]
  POST /projects/{id}/domains — Attach a custom domain to a project [write] · body: domain*
  POST /projects/{id}/domains/{domain}/primary — Set a project's primary (production) domain [write]
  DELETE /projects/{id}/domains/{domain} — Detach a domain from a project [write]
  GET /projects/{id}/domains/{domain}/proxy-status — Get a domain's Cloudflare proxy status [read]

## emails (2)
  GET /emails — List recent transactional emails [read] · query: limit
  POST /emails — Send a transactional email [write] · body: from*, to*, cc, bcc, reply_to, subject*, html, text, headers, tags

## dns_zones (4)
  GET /dns/zones — List managed DNS zones [read]
  POST /dns/zones — Create a managed DNS zone [write] · body: domain*
  GET /dns/zones/{id} — Get a managed DNS zone [read]
  DELETE /dns/zones/{id} — Delete a managed DNS zone [write]

## dns_records (4)
  GET /dns/zones/{id}/records — List DNS records in a zone [read]
  POST /dns/zones/{id}/records — Create a DNS record [write] · body: type*, name*, content*, ttl, priority, proxied, comment
  PUT /dns/zones/{id}/records/{recordId} — Update a DNS record [write] · body: type*, name*, content*, ttl, priority, proxied, comment
  DELETE /dns/zones/{id}/records/{recordId} — Delete a DNS record [write]

## cdn_buckets (5)
  GET /cdn/buckets — List CDN storage buckets [read]
  POST /cdn/buckets — Create a CDN storage bucket [write] · body: name*, visibility, optimizeImages, optimizeVideo
  GET /cdn/buckets/{id} — Get a CDN bucket [read]
  PATCH /cdn/buckets/{id} — Update a CDN bucket [write] · body: visibility, optimizeImages, optimizeVideo
  DELETE /cdn/buckets/{id} — Delete a CDN bucket [write]

## cdn_assets (6)
  GET /cdn/buckets/{id}/assets — List assets in a CDN bucket [read] · query: limit
  POST /cdn/buckets/{id}/uploads/presign — Presign a direct-to-R2 CDN upload [write] · body: filename*, contentType, sizeBytes, path
  POST /cdn/buckets/{id}/uploads/finalize — Finalize a direct-to-R2 CDN upload [write] · body: assetId*
  GET /cdn/assets/{id} — Get a CDN asset [read]
  DELETE /cdn/assets/{id} — Delete a CDN asset [write]
  GET /cdn/assets/{id}/signed-url — Get a signed URL for a private CDN asset [read] · query: ttl

## cdn (1)
  GET /cdn/usage — Get CDN usage totals + a daily window [read] · query: days

## cdn_keys (3)
  GET /cdn/keys — List CDN upload API keys [read]
  POST /cdn/keys — Create a CDN upload API key [write] · body: name*
  DELETE /cdn/keys/{id} — Revoke a CDN upload API key [write]

## cron (8)
  GET /cron — List cron jobs [read]
  POST /cron — Create a cron job [write] · body: name*, schedule*, timezone, targetType, url, method, headers, body, command, projectId, timeoutSec, maxRetries, secret, enabled
  POST /cron/preview — Validate a cron expression and preview its next runs [read] · body: schedule*, timezone, count
  GET /cron/{id} — Get a cron job [read]
  PATCH /cron/{id} — Update a cron job [write] · body: name, schedule, timezone, targetType, url, method, headers, body, command, projectId, timeoutSec, maxRetries, secret, enabled
  DELETE /cron/{id} — Delete a cron job [write]
  POST /cron/{id}/run — Run a cron job now [write]
  GET /cron/{id}/runs — List a cron job's run history [read] · query: limit

## env-groups (11)
  GET /env-groups — List environment-variable groups [read]
  POST /env-groups — Create an environment-variable group [write] · body: name*, description
  GET /env-groups/{id} — Get an environment-variable group [read]
  PATCH /env-groups/{id} — Update an environment-variable group [write] · body: name, description
  DELETE /env-groups/{id} — Delete an environment-variable group [write] · query: cascade
  POST /env-groups/{id}/vars — Set a variable on an environment-variable group [write] · body: name*, value*
  PUT /env-groups/{id}/vars/{name} — Update a variable on an environment-variable group [write] · body: value*
  DELETE /env-groups/{id}/vars/{name} — Delete a variable from an environment-variable group [write]
  GET /projects/{id}/env-groups — List a project's environment-variable groups [read]
  POST /projects/{id}/env-groups — Attach an environment-variable group to a project [write] · body: groupId*, environment
  DELETE /projects/{id}/env-groups/{groupId} — Detach an environment-variable group from a project [write]

## files (8)
  GET /projects/{id}/files — List a directory in a project's source tree [read] · query: path
  GET /projects/{id}/files/content — Read a file's contents [read] · query: path*
  PUT /projects/{id}/files/content — Write (create or overwrite) a file [write] · body: path*, content*
  DELETE /projects/{id}/files/content — Delete a file or directory [write] · query: path*
  POST /projects/{id}/files/directories — Create a directory [write] · body: path*
  POST /projects/{id}/files/move — Move or rename a file/directory [write] · body: path*, dest*
  GET /projects/{id}/files/search — Search file contents [read] · query: q*
  POST /projects/{id}/files/deploy — Deploy the edited source tree [write]

## services (3)
  GET /projects/{id}/services — List a project's running containers [read]
  POST /projects/{id}/services/{service}/{action} — Start, stop or restart one container [write]
  POST /projects/{id}/services/{service}/exec — Run a command inside one service's live container [write] · body: command*, timeoutSec

## runs (4)
  GET /projects/{id}/runs — List previous runs for a project [read]
  POST /projects/{id}/runs — Run a one-off command against a project in an isolated sandbox [write] · body: command*
  GET /projects/{id}/runs/{runId} — Get one run, including its full output [read]
  GET /runs/allowed-commands — List the commands create_project_run accepts [read]

## service_env (3)
  GET /projects/{id}/services/{service}/env — List a compose service's own environment variables [read]
  PUT /projects/{id}/services/{service}/env/{name} — Set one environment variable for a single compose service [write] · body: value*
  DELETE /projects/{id}/services/{service}/env/{name} — Remove a service-scoped environment variable [write]