Skip to content
Developer docs

REST API

Base address, the OpenAPI spec, and the main endpoints for projects, deployments, jobs, AI keys and secrets, with request and response examples.

Base address: https://remcloudhub.com/api/ · Spec: https://remcloudhub.com/api/openapi.json (OpenAPI 3.1) · Explorer: https://remcloudhub.com/api/docs

All bodies are JSON. Authenticate with Authorization: Bearer <qchp_ or qchsa_ token> and pick the organisation with X-RCH-Org (see Authentication). Operation ids in the spec are <tag>_<handler>. Values in the examples below (ids, names, dates) are illustrative; field names are exact.

Who am I

GET /api/me/roles

Answers your role, level, the organisations you are in, those you administer (company_admin_of, team_admin_of) and the console pages you may open. GET /api/whoami answers id, username and your regions.

Projects (apps)

Method and path

Does

GET /api/apps

Projects you can see (?id= or ?name= for one)

POST /api/apps

Create a project and start its first deploy

PUT /api/apps

Update a project (send the full object)

PATCH /api/apps/{app_id}

Change some fields

DELETE /api/apps

Delete (detaches and keeps its resources)

POST /api/apps/{app_id}/update-now

Build the branch head and deploy it (answers 202)

POST /api/apps/{app_id}/restart

Restart the running container

GET /api/apps/{app_id}/deploys

Current deployment and history

GET /api/apps/{id}/versions

Builds you can roll back to

POST /api/apps/{app_id}/rollback

Run an earlier version

GET /api/deployments/{id}/logs

A deployment's build log

Create a project

POST /api/apps
Content-Type: application/json

{
  "name": "pricing-api",
  "url_endpoint": "pricingapi",
  "git_url": "https://github.com/acme/pricing-api.git",
  "git_branch": "main",
  "appType": "fast_api",
  "size_class": "S",
  "provision_postgres": true
}
{
  "success": true, "app_id": 118, "deployment_id": 902, "name": "pricing-api",
  "url_endpoint": "pricingapi", "public_url": "https://remcloudhub.com/pricingapi",
  "domain": null, "domain_id": null, "domain_note": ""
}

name and url_endpoint are required. appType keys: shiny_web_app, plumber_api, fast_api, flask_api, react_app, quasar_app, next_app, full_stack, mcp_server, custom_app_dockerfile. size_class: XS, S, M (default), L, XL, unless your organisation fixes it. provision_postgres: true gives it a database; or pass database_id of an existing one.

Follow a deploy

GET /api/apps/118/deploys
{
  "auto_rollback": true,
  "current": {"status": "running", "version": 3, "deployed_by": "asha", "error": "",
              "steps": [{"key": "build", "label": "Build the image", "state": "done", "duration_s": 74,
                         "started_at": "2026-11-18T10:40:15Z", "detail": ""}],
              "log_tail": "...", "log_truncated": true, "can_cancel": false},
  "history": [
    {"id": 902, "revision": 3, "status": "running", "is_current": true, "built": true,
     "commit_sha": "4e1d0c2", "commit_message": "Add /quote endpoint", "image_tag": "pricingapi:3",
     "deployed_by": "asha", "created_at": "2026-11-18T10:40:12Z", "can_rollback": false, "error": ""}
  ]
}

Poll it every few seconds until current.status is running or failed. On failed, current.error says why in plain words and the previous version keeps serving.

Roll back

POST /api/apps/118/rollback
Content-Type: application/json

{"version_id": 2}

Answers 202 with {"message": "...", "version": 2}.

Jobs

Method and path

Does

GET /api/jobs

Jobs you can see, with schedule, last runs and failure rate

POST /api/jobs

Create a job

POST /api/jobs/{job_id}/run

Run now

POST /api/jobs/{job_id}/stop

Stop the running run

POST /api/jobs/{job_id}/enable, /disable

Switch scheduled runs on or off

GET /api/jobs/{job_id}/runs

Runs with status and duration

GET /api/jobs/{job_id}/logs

Output of the latest run

GET/PUT /api/jobs/{job_id}/run-policy

Overlap, timeout, retries, holidays, pause

POST /api/jobs/57/run
{"success": true, "message": "Job 'nightly-report' started."}

A job that is already running, or disabled, answers 400 with the reason ("Job is already running."); a run held by your release rules answers 409.

AI keys

Method and path

Does

GET /api/ai/hub/info

The gateway endpoint, the default variable name

GET/POST /api/ai/hub/keys

List or create keys

GET/PATCH/DELETE /api/ai/hub/keys/{id}

One key

POST /api/ai/hub/keys/{id}/rotate

New value; attached places refresh

POST /api/ai/hub/keys/{id}/bindings

Attach to a project, job, team or agent

POST /api/ai/hub/keys
Content-Type: application/json

{"name": "pricing-prod", "description": "Quote explanations", "models": ["rch-fast"],
 "max_budget_usd": 50, "budget_duration": "30d", "rpm": 60, "tags": {"product": "pricing"}}

Answers 201 with key (its settings, spend_usd, bindings) and value, the key itself, shown once. Tags: at most 8, names lower-case. Attach it:

POST /api/ai/hub/keys/23/bindings
Content-Type: application/json

{"target_type": "app", "target_id": 118, "env_name": "QFS_AI_KEY"}

Secrets

GET /api/shared-secrets lists secrets (metadata only), POST creates one with a write-only value; bindings attach a secret to a project or job. Values are never returned by any endpoint.

Paging and lists

Large lists have paged twins under /api/paged/... (for example /api/paged/apps, /api/paged/jobs) that take page, page_size, q (search) and sort, and return the total. Prefer them for anything you loop over.

Limits

Sign-in and some sensitive routes are rate limited and answer 429. Creating a project, job or database past your plan answers 403 with code plan_limit_reached, the feature, its limit and how many are used.

Download: PDF · Word · Markdown