Coderunner API Reference

Reference for the Coderunner standalone HTTP API and how Control Plane proxies it. Base URL is set via CODERUNNER_URL on Control Plane.

Dev example: https://dev-coderunner.groundfloor.co

Authentication

Every request requires:

Header	Value
`Authorization`	`Bearer <jwt>` — Control Plane-minted RS256 JWT or forwarded user session
`x-client-key`	Workspace UUID (`external_tenant_id`)
`x-userid`	Portal `users.id` (`external_user_id`)

JWT claims should include external_tenant_id and external_user_id; headers are required by the standalone service.

Lifecycle

Step	Coderunner upstream	Control Plane proxy
Create definition	`POST /api/definitions`	`POST …/definition`
Upload code	`POST /api/file/{id}/upload`	`POST …/upload`
List versions	`GET /api/version/definition?DefinitionId=`	`GET …/versions`
Get version	`GET /api/version/{versionId}`	`GET …/versions/{versionId}`
Delete version	`DELETE /api/version/{versionId}`	`DELETE …/versions/{versionId}`
Deploy	`POST /api/deployment/create`	`POST …/deploy`
Run	`POST {externalEndpoint}` or `POST /api/execution/run/onetime/{id}`	`POST …/run`

Proxy paths are workspace- and app-scoped under /v1/workspaces/{workspace_id}/apps/{app_slug}/coderunner/….

Create definition

{
  "name": "My function",
  "description": "hello",
  "deploymentType": 1,
  "languageType": 2
}

Field	Values
`deploymentType`	`1` Function, `2` BackgroundJob, `3` ScheduleJob, `4` Deployment
`languageType`	`1` NodeJS, `2` Python, `3` DotNetScript

Response envelope:

{
  "success": true,
  "message": "Code definition created",
  "data": { "id": "uuid" }
}

Upload (multipart)

Description (text field)
file (ZIP archive)

Response data.versionId is stored as manifest.coderunner.version_id. Poll version status until Completed (3) before deploy.

Status	Code
Pending	1
Processing	2
Completed	3
Failed	4

Deploy

{
  "DefinitionId": "definition-uuid",
  "VersionId": "version-uuid",
  "Configuration": {
    "Cpu": "250m",
    "Memory": "256Mi",
    "CronExpression": "*/5 * * * *"
  }
}

GET /api/deployment/{deploymentId} returns configuration.externalEndpoint — the invoke URL.

Run

{ "payload": { "hello": "world" } }

Response data.executionId maps to manifest.coderunner.last_job_name.

Manifest state

Control Plane tracks IDs under manifest.coderunner:

definition_id
version_id
deployment_id
last_job_name
last_job_status

Coderunner overview — architecture
Front Door — public HTTPS routing
Apps guide — portal app registration