API Reference

REST API for programmatic deployments and management. Base URL: https://api.poc.ai

Authentication

All API requests require a Bearer token in the Authorization header. Obtain a token from your POC.ai dashboard under Settings → API Tokens.

Authorization: Bearer poc_your_api_token_here

Error format

All errors return a consistent JSON envelope:

{
  "error": {
    "code": "DEPLOYMENT_NOT_FOUND",
    "message": "No deployment found with ID dep_invalid",
    "status": 404
  }
}

Detect the framework and runtime for a given repository or directory. Returns a deployment recipe.

Auth: Bearer token required

Request body:

{
  "repoUrl": "https://github.com/user/my-app",
  "branch": "main"
}

Response: 200 OK

{
  "framework": "react-vite",
  "runtime": "node-20",
  "buildCommand": "npm run build",
  "startCommand": "npx serve dist",
  "detectedFiles": ["package.json", "vite.config.ts", "tsconfig.json"]
}

Trigger a deployment. Creates a preview service and returns a deployment ID and preview URL.

Auth: Bearer token required

Request body:

{
  "repoUrl": "https://github.com/user/my-app",
  "branch": "main",
  "name": "my-app",
  "env": "preview",
  "envVars": {
    "NODE_ENV": "production",
    "API_KEY": "sk_live_..."
  }
}

Response: 201 Created

{
  "deploymentId": "dep_7xk2m9",
  "status": "building",
  "previewUrl": "https://my-app-abc123.poc.ai",
  "createdAt": "2026-03-17T10:30:00Z"
}

Get the current status and details of a deployment.

Auth: Bearer token required

Response: 200 OK

{
  "deploymentId": "dep_7xk2m9",
  "status": "live",
  "previewUrl": "https://my-app-abc123.poc.ai",
  "productionUrl": null,
  "framework": "react-vite",
  "createdAt": "2026-03-17T10:30:00Z",
  "updatedAt": "2026-03-17T10:32:15Z",
  "version": 3
}

Promote a preview deployment to production.

Auth: Bearer token required

Request body (optional):

{
  "customDomain": "app.example.com"
}

Response: 200 OK

{
  "deploymentId": "dep_7xk2m9",
  "status": "live",
  "productionUrl": "https://my-app.poc.ai",
  "promotedAt": "2026-03-17T11:00:00Z"
}

Roll back a deployment to a previous healthy version.

Auth: Bearer token required

Request body (optional):

{
  "targetVersion": 2
}

Response: 200 OK

{
  "deploymentId": "dep_7xk2m9",
  "status": "live",
  "rolledBackTo": 2,
  "rolledBackAt": "2026-03-17T11:05:00Z"
}

List all tenants (organizations) for admin users. Requires admin-level API token.

Auth: Bearer token required (admin scope)

Response: 200 OK

{
  "tenants": [
    {
      "id": "ten_abc123",
      "name": "PsyTech",
      "plan": "team",
      "memberCount": 8,
      "createdAt": "2026-01-15T08:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1
  }
}

Join the POC.ai early access waitlist. No authentication required.

Auth: None

Request body:

{
  "email": "you@example.com",
  "company": "Acme Corp",
  "role": "Engineering Lead"
}

Response: 201 Created

{
  "message": "You're on the list!",
  "position": 142
}

Rate limits