Reference for the Synthcore API — VM management gateway and VM reporter endpoints for authentication, lifecycle, telemetry, and commands.

API Reference

Synthcore exposes two API gateways as Supabase Edge Functions:

VM API (vm-api) — Dashboard-to-VM operations: create, start, stop, delete, and check status. Authenticated with Supabase JWT.
VM Reporter (vm-reporter) — VM-to-platform telemetry: health snapshots, metrics, commands, messages, and approvals. Authenticated with per-project reporter tokens.

VM API

All VM lifecycle operations — creating, starting, stopping, and deleting instances — go through a single endpoint.

Base URL:

POST https://<your-supabase-url>/functions/v1/vm-api

Authentication

All requests require a valid Supabase JWT in the Authorization header:

Authorization: Bearer <your-jwt-token>

The gateway verifies your token against Supabase Auth and checks that your user account has access to the requested resource:

Create requires membership in the target organization
Start / Stop / Delete / Status require membership in the target project

Requests with missing or invalid tokens receive a 401 Unauthorized response. Requests where the user lacks access receive 403 Forbidden.

Rate Limits

The gateway enforces 20 requests per minute per authenticated user. If you exceed this limit, the response includes a Retry-After header indicating when you can retry:

{ "error": "Rate limit exceeded. Please try again later." }

Status code: 429 Too Many Requests

Request Format

All requests are POST with a JSON body containing an action field and action-specific parameters:

{
  "action": "start",
  "project_id": "uuid-here"
}

Endpoints

Create a Project

Provisions a new VM instance and adds you as the project owner.

{
  "action": "create",
  "organization_id": "uuid",
  "name": "my-project",
  "region": "australiaeast",
  "vm_size": "Standard_D2s_v3"
}

Parameter	Required	Default	Description
`organization_id`	Yes	—	Organization to create the project under
`name`	Yes	—	Display name for the project
`region`	No	`australiaeast`	Cloud region for the VM
`vm_size`	No	`Standard_D2s_v3`	VM instance size

Response:

{
  "success": true,
  "data": {
    "project_id": "generated-uuid",
    "status": "provisioning"
  }
}

Provisioning typically takes 3–5 minutes. The project status transitions from provisioning to active once the VM is ready.

Start a VM

Starts a stopped VM. The project must be in stopped status.

{
  "action": "start",
  "project_id": "uuid"
}

Response:

{
  "success": true,
  "data": {
    "project_id": "uuid",
    "status": "starting"
  }
}

Stop a VM

Stops a running VM. The project must be in active or running status.

{
  "action": "stop",
  "project_id": "uuid"
}

Response:

{
  "success": true,
  "data": {
    "project_id": "uuid",
    "status": "stopping"
  }
}

Delete a VM

Terminates and deletes a VM. The project must be stopped unless you pass force: true.

{
  "action": "delete",
  "project_id": "uuid",
  "force": false
}

Parameter	Required	Default	Description
`project_id`	Yes	—	Project to delete
`force`	No	`false`	Skip the stopped-state check

Response:

{
  "success": true,
  "data": {
    "project_id": "uuid",
    "status": "deleting"
  }
}

Get VM Status

Returns the project details and last 5 activity log entries.

{
  "action": "status",
  "project_id": "uuid"
}

Response:

{
  "success": true,
  "data": {
    "project": {
      "id": "uuid",
      "name": "my-project",
      "status": "active",
      "health_status": "healthy",
      "region": "australiaeast",
      "vm_size": "Standard_D2s_v3",
      "created_at": "2026-01-15T10:00:00Z",
      "updated_at": "2026-04-01T14:30:00Z"
    },
    "recent_activity": [
      {
        "action": "vm_start_requested",
        "details": {},
        "created_at": "2026-04-01T14:30:00Z"
      }
    ]
  }
}

VM Status Lifecycle

provisioning → active ⇄ stopping → stopped → starting → active
                  ↓                     ↓
               deleting              deleting

Status	Description
`provisioning`	VM is being created and configured
`active` / `running`	VM is running and agents are working
`stopping`	Shutdown in progress
`stopped`	VM is off — no compute charges
`starting`	Boot in progress
`deleting`	Termination in progress

Error Responses

All errors return a JSON object with an error field:

{ "error": "Description of what went wrong" }

Status Code	Meaning
`400`	Bad request — missing fields, invalid action, or invalid state transition
`401`	Unauthorized — missing or invalid JWT
`403`	Forbidden — user lacks access to the resource
`405`	Method not allowed — only POST is accepted
`429`	Rate limit exceeded
`500`	Server error

CORS

The gateway accepts requests from:

http://localhost:3000 and http://localhost:3001 (development)
https://app.synthcore.dev and https://uat.synthcore.dev (production and UAT)

Preflight OPTIONS requests are handled automatically.

VM Reporter

The VM Reporter gateway handles all telemetry and command traffic from VMs back to the platform. Each VM calls these endpoints on every agent cycle to report health, push metrics, poll for commands, and manage approvals.

Base URL:

POST https://<your-supabase-url>/functions/v1/vm-reporter/<route>

Authentication

VMs authenticate with a project-scoped reporter token, not a user JWT:

Authorization: Bearer <reporter-token>
X-Project-ID: <project-uuid>

The gateway validates the token against the database on every request. Invalid tokens receive 401 Unauthorized.

Rate Limits

100 requests per minute per project (configurable via VM_REPORTER_RATE_LIMIT environment variable). Returns 429 with Retry-After header when exceeded.

Endpoints

Health

POST /vm-reporter/health

Push a health snapshot (CPU, memory, disk, agent status).

Messages

POST /vm-reporter/messages

Log agent messages for display in the dashboard Chat tab.

Audit

POST /vm-reporter/audit

Push audit events (action logs for the activity trail).

Conflicts

POST /vm-reporter/conflicts

Report git conflict and sync statistics.

Task Metrics

POST /vm-reporter/metrics/tasks

Push task completion metrics (assigned, completed, failed, drifted counts).

Productivity Metrics

POST /vm-reporter/metrics/productivity

Push agent productivity metrics.

CLI Session Metrics

POST /vm-reporter/metrics/cli-sessions

Push CLI session tracking data.

Poll Commands

POST /vm-reporter/commands/poll

VM polls for queued commands to execute (start, stop, restart agents, etc.).

Update Command Status

POST /vm-reporter/commands/status

Report the result of a command execution back to the platform.

Create Approval Request

POST /vm-reporter/approvals

Request human approval before proceeding with an action. Creates an entry visible on the dashboard Approvals tab.

Acknowledge Approval Decision

POST /vm-reporter/approvals/ack

Report the outcome of an approval decision.

Error Responses

Status Code	Meaning
`400`	Bad request — missing project ID, invalid JSON, or RPC error
`401`	Unauthorized — missing or invalid reporter token
`404`	Unknown route
`405`	Method not allowed — only POST is accepted
`429`	Rate limit exceeded
`500`	Server error

Request Logging

All requests are logged to vm_reporter_request_log with project ID, route, status code, latency, and any error message. This powers the Logs tab in the dashboard.

API Reference

API Reference

VM API

Authentication

Rate Limits

Request Format

Endpoints

Create a Project

Start a VM

Stop a VM

Delete a VM

Get VM Status

VM Status Lifecycle

Error Responses

CORS

VM Reporter

Authentication

Rate Limits

Endpoints

Health

Messages

Audit

Conflicts

Task Metrics

Productivity Metrics

CLI Session Metrics

Poll Commands

Update Command Status

Create Approval Request

Acknowledge Approval Decision

Error Responses

Request Logging

On this page