Documentation / REST API

Darwa REST API

The same project, source, service, and deployment resources used by the dashboard and CLI, exposed as versioned JSON endpoints.

API v1JSON over HTTPSBearer authenticationBase api.darwa.com/api/v1

Authentication

Send an active Darwa access token in the Authorization header. Tokens are workspace-scoped and must never be included in browser bundles or committed source.

terminal

curl https://api.darwa.com/api/v1/project-folders \
  -H "Authorization: Bearer $DARWA_TOKEN" \
  -H "Accept: application/json"

Resource model

Projects are organizational containers. Services are runnable resources. A source connection makes repositories available, while deployments capture immutable builds of a service.

Resource	API collection	Relationship
Project	/project-folders	Contains zero or more services
Service	/projects	May belong to a project through project_group
Source	/source-connections	Provides repositories and branches
Deployment	/runtime	Builds and releases one service revision

Projects

GET/project-foldersList workspace projects

POST/project-foldersCreate a project container

GET/project-folders/{slug}Get a project with its services

DELETE/project-folders/{slug}Delete a project and contained services

request.json

{
  "name": "Storefront",
  "environment": "production",
  "access_mode": "all_members"
}

Services

GET/projects?limit=20&offset=0List deployable services

POST/projectsCreate a source-less service

GET/projects/{slug}Get service configuration and status

PATCH/projects/{slug}Update service identity or runtime state

DELETE/projects/{slug}Delete one service

GET/projects/{slug}/environment-variablesList environment variable keys

Secret values are write-only. Read responses return variable names and whether a value exists, never the stored value.

GitHub sources

GET/source-connectionsList source provider connection status

POST/source-connections/github/authorizeBegin browser authorization

GET/source-connections/github/repositoriesList available repositories

GET/source-connections/github/repositories/{id}/branchesList repository branches

GET/source-connections/github/repositories/{id}/frameworkDetect framework and version

POST/source-connections/github/importCreate a service from a repository

DELETE/source-connections/githubDisconnect GitHub

import.json

{
  "repository_id": "987654321",
  "name": "Frontend",
  "branch": "main",
  "project_group": "Storefront",
  "kind": "web_service",
  "runtime": "node",
  "region": "us-east",
  "instance_type": "starter"
}

Deployments

GET/runtime/deploymentsList workspace deployments

GET/runtime/projects/{slug}/deployments/latestRead the latest service deployment

POST/runtime/projects/{slug}/cli-deploymentsUpload a CLI source archive

GET/runtime/projects/{slug}/deployments/{id}/logsRead build and runtime logs

Upload format

CLI deployment bodies use application/zip. Archives are limited to 50 MB compressed, 250 MB expanded, and 20,000 files.

Errors and pagination

Errors use an HTTP status plus a JSON detail field. Collection endpoints use limit and offset where shown.

error.json

{
  "detail": "Project not found"
}

Status	Meaning	Client action
401	Missing or expired session	Authenticate again
403	Workspace permission denied	Request workspace access
404	Resource not found in this workspace	Check the slug or ID
409	Name, state, or billing conflict	Resolve the reported conflict
422	Request validation failed	Correct the indicated fields
503	Runtime temporarily unavailable	Retry with backoff