Code Server API Reference

Programmatic control of your Code Server instances.

Base URL: https://api.universalapi.co

All endpoints require authentication: Authorization: Bearer YOUR_TOKEN

INFO

Code Server requires an active subscription (Starter or Professional plan).

Get Status

Get the current state of your code server instance.

GET /code-server/status

Response

json

{
  "data": {
    "status": "running",
    "instanceId": "i-0abc123def456",
    "alias": "myalias",
    "instanceType": "t3.small",
    "creditsPerMinute": 1,
    "totalMinutesUsed": 120,
    "currentMonthMinutes": 45,
    "launchedAt": "2026-03-10T15:00:00Z",
    "stoppedAt": null,
    "costPerMinute": 1,
    "url": "https://code.universalapi.co/myalias/",
    "password": "abc123...",
    "setupScript": "#!/bin/bash\n...",
    "setupStatus": "completed",
    "setupError": "",
    "credentials": {
      "hasGithubPat": true,
      "githubPatPrefix": "ghp_abc",
      "hasAwsKeys": true,
      "awsAccessKeyPrefix": "AKIA"
    }
  }
}

TIP

The url and password fields are only included when the instance is running. The credentials field shows which API keys are available for setup script injection (no secrets exposed).

Status Values

Status	Description
`none`	No instance exists — use Launch to create one
`launching`	Instance is booting and configuring (~3-5 min for new, ~30s for restart)
`running`	Instance is active and accessible
`stopped`	Instance is stopped — use Start to resume
`terminated`	Instance has been destroyed — use Launch to create a new one

List Instance Types

Get available instance types and their pricing.

GET /code-server/instance-types

Response

json

{
  "data": {
    "instanceTypes": [
      {
        "instanceType": "t3.small",
        "creditsPerMinute": 1,
        "ram": "2 GB",
        "vcpus": 2,
        "description": "Basic — light editing, small installs"
      },
      {
        "instanceType": "t3.medium",
        "creditsPerMinute": 2,
        "ram": "4 GB",
        "vcpus": 2,
        "description": "Standard — development, SAM CLI, builds"
      },
      {
        "instanceType": "t3.large",
        "creditsPerMinute": 3,
        "ram": "8 GB",
        "vcpus": 2,
        "description": "Performance — Docker, large builds"
      },
      {
        "instanceType": "t3.xlarge",
        "creditsPerMinute": 5,
        "ram": "16 GB",
        "vcpus": 4,
        "description": "Power — ML, heavy workloads"
      }
    ],
    "default": "t3.small"
  }
}

Launch Instance

Create and start a new code server instance.

POST /code-server/launch

Request Body

json

{
  "instanceType": "t3.small",
  "setupScript": "#!/bin/bash\nnpm install"
}

Field	Type	Required	Description
`instanceType`	string	No	Instance type (default: `t3.small`). See Instance Types for options.
`setupScript`	string	No	Bash setup script to save (up to 8,000 chars). Not executed on launch — use `/code-server/setup` after the instance is running.

Response

json

{
  "data": {
    "status": "launching",
    "instanceId": "i-0abc123def456",
    "instanceType": "t3.small",
    "creditsPerMinute": 1,
    "alias": "myalias",
    "message": "Your code server (t3.small) is launching. This takes 3-5 minutes."
  }
}

WARNING

You can only have one instance at a time. If you already have a running or stopped instance, this will return an error.

Start Instance

Start a previously stopped instance. The launchedAt timestamp updates to reflect the most recent start.

POST /code-server/start

Response

json

{
  "data": {
    "status": "launching",
    "instanceId": "i-0abc123def456",
    "message": "Your code server is starting. This takes about 30 seconds."
  }
}

Minimum Credits

You need at least 10 minutes' worth of credits to start. For example, a t3.medium instance requires at least 20 credits.

Stop Instance

Stop a running instance. The instance can be restarted later. No credits are charged while stopped.

POST /code-server/stop

Response

json

{
  "data": {
    "status": "stopped",
    "instanceId": "i-0abc123def456",
    "message": "Your code server is stopping."
  }
}

Terminate Instance

Permanently destroy the instance and its EBS volume. You can launch a new one afterward.

POST /code-server/terminate

Response

json

{
  "data": {
    "status": "terminated",
    "message": "Your code server has been terminated. All local data has been deleted. Knowledge files in S3 are preserved."
  }
}

WARNING

Termination is irreversible. Any files stored on the instance's local disk (outside ~/knowledge/) will be lost. Knowledge files in S3 are preserved.

Run Setup Script

Execute a bash setup script on your running instance via SSM. Your credentials (GitHub PAT, AWS keys) from the API Keys page are automatically injected as environment variables.

POST /code-server/setup

Request Body

json

{
  "setupScript": "#!/bin/bash\ngit config --global user.name \"$USER_ALIAS\"\ncd /home/ec2-user && git clone https://github.com/your-org/your-repo.git"
}

Field	Type	Required	Description
`setupScript`	string	No	Bash script content (max 8,000 characters). If omitted, runs the previously saved script.

Response

json

{
  "data": {
    "setupStatus": "completed",
    "message": "Setup script completed successfully.",
    "commandId": "abc123-def456"
  }
}

Setup Status Values

Status	Description
`completed`	Script ran successfully
`running`	Script is currently executing (check status for updates)
`failed`	Script failed — check `error` field for details

Injected Environment Variables

Variable	Description
`GITHUB_PAT`	GitHub Personal Access Token
`AWS_ACCESS_KEY_ID`	AWS Access Key ID
`AWS_SECRET_ACCESS_KEY`	AWS Secret Access Key
`AWS_REGION`	AWS Region (defaults to `us-east-1`)
`USER_ALIAS`	Your Universal API username
`USER_EMAIL`	Your alias-based email

INFO

The instance must be in running state to execute a setup script.

Save Setup Script

Save a setup script without executing it. Useful for preparing a script before the instance is running.

POST /code-server/save-setup-script

Request Body

json

{
  "setupScript": "#!/bin/bash\nnpm install && npm run build"
}

Field	Type	Required	Description
`setupScript`	string	Yes	Bash script content (max 8,000 characters)

Response

json

{
  "data": {
    "message": "Setup script saved.",
    "setupScript": "#!/bin/bash\nnpm install && npm run build"
  }
}

Billing & Request Logs

Code Server operations and billing entries appear in your Request Logs:

Log Type	`request_type`	Description
API calls	`CODE_SERVER`	Management operations (launch, start, stop, status, etc.)
Billing	`CODE_SERVER_BILLING`	Credit deductions every 5 minutes while running
Auto-stop	`CODE_SERVER_BILLING`	Instance auto-stopped due to insufficient credits

Billing log entries include details like credits charged, minutes billed, instance type, and remaining balance.

Error Responses

Status Code	Code	Description
`400`	`INVALID_INSTANCE_TYPE`	Invalid instance type specified
`401`	—	Authentication required
`402`	`INSUFFICIENT_CREDITS`	Not enough credits to launch/start
`404`	—	No instance found
`409`	—	Already have a running instance (launch)
`409`	`INSTANCE_STOPPED`	Instance is stopped — use `/code-server/start`

Example: Full Lifecycle

bash

# 1. Check available instance types
curl -s https://api.universalapi.co/code-server/instance-types \
  -H "Authorization: Bearer YOUR_TOKEN" | jq

# 2. Launch a new instance (t3.medium for more RAM)
curl -s -X POST https://api.universalapi.co/code-server/launch \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"instanceType": "t3.medium"}' | jq

# 3. Check status (poll until "running")
curl -s https://api.universalapi.co/code-server/status \
  -H "Authorization: Bearer YOUR_TOKEN" | jq

# 4. Open in browser: https://code.universalapi.co/your-alias/

# 5. Run setup script
curl -s -X POST https://api.universalapi.co/code-server/setup \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"setupScript": "#!/bin/bash\ncd /home/ec2-user && git clone https://github.com/your-org/repo.git"}' | jq

# 6. Stop when done (no charges while stopped)
curl -s -X POST https://api.universalapi.co/code-server/stop \
  -H "Authorization: Bearer YOUR_TOKEN" | jq

# 7. Start again later (~30 seconds)
curl -s -X POST https://api.universalapi.co/code-server/start \
  -H "Authorization: Bearer YOUR_TOKEN" | jq

# 8. Terminate when no longer needed
curl -s -X POST https://api.universalapi.co/code-server/terminate \
  -H "Authorization: Bearer YOUR_TOKEN" | jq

Code Server API Reference ​

Get Status ​

Response ​

Status Values ​

List Instance Types ​

Response ​

Launch Instance ​

Request Body ​

Response ​

Start Instance ​

Response ​

Stop Instance ​

Response ​

Terminate Instance ​

Response ​

Run Setup Script ​

Request Body ​

Response ​

Setup Status Values ​

Injected Environment Variables ​

Save Setup Script ​

Request Body ​

Response ​

Billing & Request Logs ​

Error Responses ​

Example: Full Lifecycle ​

Code Server API Reference

Get Status

Response

Status Values

List Instance Types

Response

Launch Instance

Request Body

Response

Start Instance

Response

Stop Instance

Response

Terminate Instance

Response

Run Setup Script

Request Body

Response

Setup Status Values

Injected Environment Variables

Save Setup Script

Request Body

Response

Billing & Request Logs

Error Responses

Example: Full Lifecycle