API Reference

Complete REST API documentation for the Rouic Platform. All endpoints are under https://system.rouic.com/api/v1.

Authentication

All API requests require a Bearer token in the Authorization header. Tokens are prefixed with rk_.

Authorization header

Authorization: Bearer rk_YOUR_API_TOKEN

Creating a Token

Log in to the dashboard at https://system.rouic.com
Navigate to API Tokens in the sidebar
Click "Create Token"
Give it a name and select scopes:
- deploy — Trigger deployments and manage environment variables
- read — List and view projects, services, and deployments
- admin — Full access including creating/deleting projects
Copy the token immediately — it won't be shown again

Security: Keep your API token secret. Do not commit it to source control. Use environment variables or a secrets manager.

Endpoints

GET/v1/projects

List projects

Returns all projects owned by the authenticated user.

Responses

200 — List of projects

401 — Unauthorized

Example Request

bash

curl https://system.rouic.com/api/v1/projects \
  -H "Authorization: Bearer rk_YOUR_TOKEN"

Example Response

json

[
  {
    "id": "clx1234567890",
    "name": "My App",
    "slug": "my-app",
    "gitUrl": "https://github.com/you/my-app.git",
    "gitBranch": "main",
    "serviceCount": 2,
    "lastDeployAt": "2025-12-01T10:30:00.000Z",
    "latestDeploymentStatus": "running",
    "createdAt": "2025-01-15T08:00:00.000Z",
    "updatedAt": "2025-12-01T10:30:00.000Z"
  }
]

POST/v1/projects

Create project

Create a new project. Requires admin scope.

Parameters

Name	Type	Required	Description
`name`	`string`	Yes	Display name for the project
`slug`	`string`	Yes	URL-safe identifier (lowercase, alphanumeric, hyphens)
`gitUrl`	`string`	No	Git repository URL
`gitBranch`	`string`	No	Default branch (defaults to 'main')
`buildContext`	`string`	No	Docker build context directory (defaults to '.')
`dockerfile`	`string`	No	Path to Dockerfile

Request Body

json

{
  "name": "My App",
  "slug": "my-app",
  "gitUrl": "https://github.com/you/my-app.git",
  "gitBranch": "main"
}

Responses

201 — Project created

400 — Validation error

401 — Unauthorized

409 — Slug already exists

Example Request

bash

curl -X POST https://system.rouic.com/api/v1/projects \
  -H "Authorization: Bearer rk_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My App",
    "slug": "my-app",
    "gitUrl": "https://github.com/you/my-app.git",
    "gitBranch": "main"
  }'

Example Response

json

{
  "id": "clx1234567890",
  "name": "My App",
  "slug": "my-app",
  "gitUrl": "https://github.com/you/my-app.git",
  "gitBranch": "main",
  "serviceCount": 0,
  "lastDeployAt": null,
  "latestDeploymentStatus": null,
  "createdAt": "2025-12-01T10:00:00.000Z",
  "updatedAt": "2025-12-01T10:00:00.000Z"
}

GET/v1/projects/{slug}

Get project by slug

Get detailed project information including services and recent deployments.

Parameters

Name	Type	Required	Description
`slug`	`string`	Yes	Project slug (path parameter)

Responses

200 — Project details

401 — Unauthorized

404 — Project not found

Example Request

bash

curl https://system.rouic.com/api/v1/projects/my-app \
  -H "Authorization: Bearer rk_YOUR_TOKEN"

Example Response

json

{
  "id": "clx1234567890",
  "name": "My App",
  "slug": "my-app",
  "gitUrl": "https://github.com/you/my-app.git",
  "gitBranch": "main",
  "services": [
    {
      "id": "svc_abc123",
      "name": "web",
      "port": 3000,
      "public": true,
      "subdomain": "my-app"
    },
    {
      "id": "svc_def456",
      "name": "api",
      "port": 8080,
      "public": true,
      "subdomain": "api-my-app"
    }
  ],
  "deployments": [
    {
      "id": "dep_xyz789",
      "serviceId": "svc_abc123",
      "status": "running",
      "environment": "production",
      "url": "https://my-app.rouic.com",
      "gitRef": "main",
      "createdAt": "2025-12-01T10:30:00.000Z",
      "finishedAt": "2025-12-01T10:32:00.000Z"
    }
  ],
  "createdAt": "2025-01-15T08:00:00.000Z",
  "updatedAt": "2025-12-01T10:30:00.000Z"
}

POST/v1/deploy

Trigger deployment

Trigger a deployment for a project. Optionally set environment variables and select specific services. The deployment runs asynchronously; poll the deployment status endpoint to monitor progress.

Parameters

Name	Type	Required	Description
`project`	`string`	Yes	Project slug
`ref`	`string`	No	Git ref to deploy (branch, tag, or SHA). Defaults to project's default branch.
`services`	`string[]`	No	List of service names to deploy. Omit to deploy all services.
`env`	`object`	No	Environment variables to set (key-value pairs). Variables are upserted.

Request Body

json

{
  "project": "my-app",
  "ref": "main",
  "services": ["web"],
  "env": {
    "DATABASE_URL": "postgresql://...",
    "NODE_ENV": "production"
  }
}

Responses

202 — Deployment started

400 — Validation error (no git URL, no services)

401 — Unauthorized

404 — Project not found

Example Request

bash

curl -X POST https://system.rouic.com/api/v1/deploy \
  -H "Authorization: Bearer rk_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "my-app",
    "ref": "main",
    "env": {
      "DATABASE_URL": "postgresql://postgres:pass@myapp-postgres:5432/myapp"
    }
  }'

Example Response

json

{
  "message": "Deployment started",
  "deployments": [
    {
      "deploymentId": "dep_abc123",
      "serviceName": "web",
      "url": "https://my-app.rouic.com"
    },
    {
      "deploymentId": "dep_def456",
      "serviceName": "api",
      "url": "https://api-my-app.rouic.com"
    }
  ]
}

GET/v1/deployments/{id}

Get deployment status

Get the current status and details of a deployment, including build logs.

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Deployment ID (path parameter)

Responses

200 — Deployment details

401 — Unauthorized

404 — Deployment not found

Example Request

bash

curl https://system.rouic.com/api/v1/deployments/dep_abc123 \
  -H "Authorization: Bearer rk_YOUR_TOKEN"

Example Response

json

{
  "id": "dep_abc123",
  "projectId": "clx1234567890",
  "projectSlug": "my-app",
  "serviceId": "svc_abc123",
  "serviceName": "web",
  "gitRef": "main",
  "imageTag": "my-app/web:production-1701430200000",
  "environment": "production",
  "status": "running",
  "url": "https://my-app.rouic.com",
  "buildLog": "Step 1/10 : FROM node:20-alpine\n...",
  "startedAt": "2025-12-01T10:30:00.000Z",
  "finishedAt": "2025-12-01T10:32:00.000Z",
  "createdAt": "2025-12-01T10:30:00.000Z"
}

GET/v1/projects/{slug}/env/pull

Pull environment variables

Download all environment variables for a project as key=value pairs. Useful for syncing to a local .env file. The CLI command rouic env pull uses this endpoint.

Parameters

Name	Type	Required	Description
`slug`	`string`	Yes	Project slug (path parameter)

Responses

200 — Environment variables as text/plain

401 — Unauthorized

404 — Project not found

Example Request

bash

curl https://system.rouic.com/api/v1/projects/my-app/env/pull \
  -H "Authorization: Bearer rk_YOUR_TOKEN" \
  -o .env.local

Example Response

json

DATABASE_URL=postgres://user:pass@host:5432/db
NODE_ENV=production
NEXT_PUBLIC_APP_URL=https://my-app.rouic.com

GET/v1/databases

List databases

List all managed databases with their connection details, status, and backup information.

Responses

200 — Array of database objects

401 — Unauthorized

Example Request

bash

curl https://system.rouic.com/api/v1/databases \
  -H "Authorization: Bearer rk_YOUR_TOKEN"

Example Response

json

[
  {
    "id": "db_abc123",
    "name": "myapp-db",
    "engine": "postgresql",
    "host": "paas-postgres",
    "port": 5432,
    "database": "myapp",
    "status": "running",
    "backupSchedule": "daily",
    "lastBackupAt": "2025-12-01T02:00:00.000Z"
  }
]

POST/v1/databases

Create a database

Provision a new managed database. Supported engines: postgresql, mysql, redis.

Request Body

json

{
  "name": "my-new-db",
  "engine": "postgresql",
  "projectId": "clx1234567890"
}

Responses

201 — Database created

400 — Invalid engine or missing fields

401 — Unauthorized

409 — Database name already exists

Example Request

bash

curl -X POST https://system.rouic.com/api/v1/databases \
  -H "Authorization: Bearer rk_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-new-db", "engine": "postgresql"}'

Example Response

json

{
  "id": "db_xyz789",
  "name": "my-new-db",
  "engine": "postgresql",
  "host": "paas-postgres",
  "port": 5432,
  "database": "my_new_db",
  "username": "my_new_db",
  "connectionString": "postgresql://my_new_db:***@paas-postgres:5432/my_new_db"
}

Error Codes

All error responses follow the same format:

{
  "error": "Human-readable error message"
}

Code	Meaning	Common Causes
`400`	Bad Request	Missing required fields, invalid field values, no services configured
`401`	Unauthorized	Missing or invalid token, expired token
`403`	Forbidden	Token doesn't have the required scope
`404`	Not Found	Project or deployment doesn't exist, or belongs to another user
`409`	Conflict	Slug already taken (when creating a project)
`429`	Too Many Requests	Rate limit exceeded (see Rate Limits section)
`500`	Internal Server Error	Unexpected server error. Contact support.

Rate Limits

The API enforces rate limits to ensure fair usage and platform stability.

Endpoint	Limit	Window
GET endpoints	60 requests	Per minute
POST /v1/deploy	10 requests	Per minute
POST /v1/projects	10 requests	Per minute

Rate limit headers are included in all responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 55
X-RateLimit-Reset: 1701430260

If you exceed the limit, you'll receive a 429 response. Wait until the reset timestamp before retrying.

SDKs and Tools

OpenAPI Specification

The full OpenAPI 3.0.3 spec is available at /api/v1/openapi.json. Import it into Swagger UI, Postman, Insomnia, or use it to generate client SDKs.

curl

All examples in this documentation use curl. Copy any example, replace rk_YOUR_TOKEN with your actual token, and run it.

AI Models (Claude, GPT)

See the AI Integration Guide for structured instructions that AI models can follow autonomously.

No SDK Required

The API follows standard REST conventions. Use any HTTP client — fetch, curl, axios, requests(Python), or any language's HTTP library. Import the OpenAPI spec into Postman or Swagger UI for interactive testing, or use it to auto-generate a typed client in any language.

Next up

AI Integration Guide →

Object Storage