API Reference

Base URL

https://api.raidframe.com/v1

Authentication

All API requests require a Bearer token:

curl https://api.raidframe.com/v1/projects \
  -H "Authorization: Bearer rf_tok_your_token_here"

Create tokens with the CLI:

rf auth token create --name "API Access" --scope full

Rate Limits

Rate limit headers are included in every response:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 298
X-RateLimit-Reset: 1710600000

Pagination

List endpoints return paginated results:

GET /v1/projects?page=1&per_page=20

Response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 42,
    "total_pages": 3
  }
}

Errors

Errors follow a consistent format:

{
  "error": {
    "code": "not_found",
    "message": "Service 'web' not found in project 'my-app'",
    "request_id": "req_abc123"
  }
}

Endpoints

Projects

GET    /v1/projects                    List projects
POST   /v1/projects                    Create project
GET    /v1/projects/:id                Get project
PATCH  /v1/projects/:id                Update project
DELETE /v1/projects/:id                Delete project

Services

GET    /v1/projects/:id/services              List services
POST   /v1/projects/:id/services              Create service
GET    /v1/projects/:id/services/:name        Get service
PATCH  /v1/projects/:id/services/:name        Update service
DELETE /v1/projects/:id/services/:name        Delete service
POST   /v1/projects/:id/services/:name/restart    Restart
POST   /v1/projects/:id/services/:name/scale      Scale

Deployments

GET    /v1/projects/:id/deployments           List deployments
POST   /v1/projects/:id/deployments           Trigger deploy
GET    /v1/projects/:id/deployments/:dep_id   Get deployment
POST   /v1/projects/:id/deployments/rollback  Rollback
POST   /v1/projects/:id/deployments/:dep_id/promote  Promote
POST   /v1/projects/:id/deployments/:dep_id/cancel   Cancel

Databases

GET    /v1/projects/:id/databases             List databases
POST   /v1/projects/:id/databases             Create database
GET    /v1/projects/:id/databases/:name       Get database
PATCH  /v1/projects/:id/databases/:name       Update database
DELETE /v1/projects/:id/databases/:name       Delete database
POST   /v1/projects/:id/databases/:name/backup    Create backup
GET    /v1/projects/:id/databases/:name/backups   List backups
POST   /v1/projects/:id/databases/:name/restore   Restore backup
POST   /v1/projects/:id/databases/:name/branch    Create branch
GET    /v1/projects/:id/databases/:name/branches  List branches
GET    /v1/projects/:id/databases/:name/insights  Query insights

Environment Variables

GET    /v1/projects/:id/env                   List variables
PUT    /v1/projects/:id/env                   Set variables (bulk)
GET    /v1/projects/:id/env/:key              Get variable
DELETE /v1/projects/:id/env/:key              Delete variable

Domains

GET    /v1/projects/:id/domains               List domains
POST   /v1/projects/:id/domains               Add domain
DELETE /v1/projects/:id/domains/:domain       Remove domain
GET    /v1/projects/:id/domains/:domain/verify  Verify DNS/SSL

Logs

GET    /v1/projects/:id/logs                  Query logs
GET    /v1/projects/:id/logs/stream           Stream logs (SSE)

Metrics

GET    /v1/projects/:id/metrics               Get metrics
GET    /v1/projects/:id/metrics/:metric       Get specific metric

Cron Jobs

GET    /v1/projects/:id/cron                  List cron jobs
POST   /v1/projects/:id/cron                  Create cron job
DELETE /v1/projects/:id/cron/:name            Delete cron job
POST   /v1/projects/:id/cron/:name/run        Trigger run
GET    /v1/projects/:id/cron/:name/runs       List runs

Alerts

GET    /v1/projects/:id/alerts                List alerts
POST   /v1/projects/:id/alerts                Create alert
PATCH  /v1/projects/:id/alerts/:alert_id      Update alert
DELETE /v1/projects/:id/alerts/:alert_id      Delete alert
GET    /v1/projects/:id/alerts/:alert_id/history  Alert history

Webhooks

Receive notifications for events in your project:

POST /v1/projects/:id/webhooks               Create webhook
GET  /v1/projects/:id/webhooks               List webhooks
DELETE /v1/projects/:id/webhooks/:webhook_id  Delete webhook

Supported Events

deployment.started
deployment.succeeded
deployment.failed
deployment.rolled_back
service.scaled
service.crashed
alert.firing
alert.resolved
database.backup.completed
cron.run.completed
cron.run.failed

Webhook Verification

Every webhook request includes a signature header:

X-RaidFrame-Signature: sha256=abc123...

Verify with your webhook secret:

import crypto from "crypto";

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return `sha256=${expected}` === signature;
}

SDKs

Official client libraries wrap this API:

• Node.js — npm install @raidframe/sdk
• Python — pip install raidframe
• Go — go get github.com/raidframe/sdk-go

See Node.js SDK, Python SDK, Go SDK for usage.