Documentation | BLAZED.sh

API Documentation

Complete API reference for BLAZED.sh - Deploy containers and scripts on our Web3 PaaS platform.

Authentication

API Key Authentication

All API requests require authentication using your API key.

Base URL

https://backend.blazed.sh

Authentication Header

Authorization: Bearer YOUR_API_KEY

Content Type

Content-Type: application/json

CLI & MCP Server

Everything documented below is also available as a single-file bash CLI, which doubles as an MCP stdio server exposing 15 tools that map 1:1 onto these endpoints. It is open source and depends only on bash ≥ 4, curl and jq.

BLAZED-sh/blazed.sh on GitHub

Install and authenticate

Drop the single file on your PATH, then point it at your API key.

Install

git clone https://github.com/BLAZED-sh/blazed.sh
install -m 755 blazed.sh/blazed.sh ~/.local/bin/blazed.sh

Authenticate

export BLAZED_API_KEY=...   # environment variable, or
blazed.sh config set-key     # stored in ~/.config/blazed/config

Deploy

blazed.sh container create my-app --image nginx:latest -p 8080
blazed.sh container ports <id>
blazed.sh script create watcher --file bot.js
blazed.sh script logs <id> --follow

--json works on any command and prints the raw API response for piping into jq.

MCP mode

Run the same file with the mcp argument to give an AI agent hands on the platform.

Register with Claude Code

claude mcp add --scope user blazed -- ~/.local/bin/blazed.sh mcp

Any MCP client

{
  "mcpServers": {
    "blazed": {
      "command": "/home/you/.local/bin/blazed.sh",
      "args": ["mcp"],
      "env": { "BLAZED_API_KEY": "YOUR_API_KEY" }
    }
  }
}

The 15 tools cover the full surface: create, list, get, stop and delete containers, read their logs and port mappings, plus create, update, list, get, run, stop and delete scripts. See the AI agent infrastructure page for how agents use it end to end.

Containers API

Create Container

POST

/api/containers

Create and deploy a new container. Returns 201 Created with the container record; deployment happens asynchronously (initial status is pending).

Request Body

{
  "name": "my-app",
  "image": "nginx:latest",
  "env": "NODE_ENV=production\nPORT=3000",
  "ports": ["8080", "443"],
  "cmd": "node server.js",
  "tty": true,
  "volumeId": "VOLUME_ID",
  "mountPath": "/data"
}

ports is an array of plain container port numbers as strings (1–65535). Do not use host:container/proto syntax — public host ports are auto-assigned by the platform. Read the resulting mapping back from the ports endpoint.

env is a newline-separated string of KEY=VALUE pairs.

cmd is a single string split on spaces server-side — shell quoting inside it is not honored.

volumeId and mountPath are optional and attach an existing volume. If volumeId is set without mountPath, the volume is mounted at /data.

Response (201 Created)

{
  "id": "RECORD_ID",
  "created": "2025-01-19T10:30:00.000Z",
  "updated": "2025-01-19T10:30:00.000Z",
  "name": "my-app",
  "image": "nginx:latest",
  "cmd": "node server.js",
  "env": "NODE_ENV=production\nPORT=3000",
  "tty": true,
  "status": "pending",
  "ports": "[\"8080\",\"443\"]",
  "ownerId": "USER_ID",
  "volumeId": "VOLUME_ID",
  "mountPath": "/data"
}

List Containers

GET

/api/containers

List all containers owned by the authenticated user.

Response

[
  {
    "id": "RECORD_ID",
    "name": "my-app",
    "image": "nginx:latest",
    "status": "running",
    "ports": "[\"8080\"]",
    "ownerId": "USER_ID",
    "created": "2025-01-19T10:30:00.000Z",
    "updated": "2025-01-19T10:30:00.000Z"
  }
]

Get Container

GET

/api/containers/{id}

Get a single container record by id.

Response

{
  "id": "RECORD_ID",
  "name": "my-app",
  "image": "nginx:latest",
  "cmd": "node server.js",
  "env": "NODE_ENV=production\nPORT=3000",
  "tty": true,
  "status": "running",
  "ports": "[\"8080\"]",
  "ownerId": "USER_ID",
  "created": "2025-01-19T10:30:00.000Z",
  "updated": "2025-01-19T10:30:00.000Z"
}

Stop Container

POST

/api/containers/{id}/stop

Stop a running container. Stopping is asynchronous.

Response

{
  "status": "stopping"
}

Delete Container

DELETE

/api/containers/{id}

Delete a container. Returns 204 No Content on success (empty body).

Container Logs

GET

/api/containers/{id}/logs

Get logs from a container. Accepts an optional since query parameter (RFC3339 or Unix timestamp) to only return logs after that time.

Response

{
  "text": "Container log output here..."
}

Container Ports

GET

/api/containers/{id}/ports

Get port mappings for a container as a map of container port to the auto-assigned public host port.

Response

{
  "8080": 30123,
  "443": 30124
}

Scripts API

Create Script

POST

/api/scripts

Create a new script. Returns 201 Created.

Request Body

{
  "name": "my-script",
  "code": "console.log('Hello from BLAZED.sh!');"
}

Response (201 Created)

{
  "id": "RECORD_ID",
  "created": "2025-01-19T10:30:00.000Z",
  "updated": "2025-01-19T10:30:00.000Z",
  "name": "my-script",
  "code": "console.log('Hello from BLAZED.sh!');",
  "owner": "USER_ID",
  "lastExitCode": 0,
  "lastExitTime": null,
  "lastExecTime": null
}

List Scripts

GET

/api/scripts

List all scripts owned by the authenticated user. Does not include the script code; each entry includes its latest runner container (if any) as currentContainer.

Response

[
  {
    "id": "RECORD_ID",
    "created": "2025-01-19T10:30:00.000Z",
    "updated": "2025-01-19T10:30:00.000Z",
    "name": "my-script",
    "owner": "USER_ID",
    "lastExitCode": 0,
    "lastExitTime": "2025-01-19T11:00:00.000Z",
    "lastExecTime": "2025-01-19T10:59:00.000Z",
    "currentContainer": { "id": "...", "status": "running" }
  }
]

Get Script

GET

/api/scripts/{id}

Get a single script by id, including its code and latest runner container (if any) as currentContainer.

Response

{
  "id": "RECORD_ID",
  "created": "2025-01-19T10:30:00.000Z",
  "updated": "2025-01-19T10:30:00.000Z",
  "name": "my-script",
  "code": "console.log('Hello from BLAZED.sh!');",
  "owner": "USER_ID",
  "lastExitCode": 0,
  "lastExitTime": "2025-01-19T11:00:00.000Z",
  "lastExecTime": "2025-01-19T10:59:00.000Z",
  "currentContainer": { "id": "...", "status": "running" }
}

Update Script

PATCH

/api/scripts/{id}

Update the name and/or code of an existing script. This is a partial update — only the fields you provide are changed.

Request Body

{
  "name": "updated-script-name",
  "code": "console.log('Updated script code!');"
}

Response

{
  "id": "RECORD_ID",
  "created": "2025-01-19T10:30:00.000Z",
  "updated": "2025-01-19T10:35:00.000Z",
  "name": "updated-script-name",
  "code": "console.log('Updated script code!');",
  "owner": "USER_ID",
  "lastExitCode": 0,
  "lastExitTime": null,
  "lastExecTime": null
}

Run Script

POST

/api/scripts/{id}/run

Execute a script in a containerized environment.

Response

{
  "status": "running"
}

Stop Script

POST

/api/scripts/{id}/stop

Stop a running script.

Response

{
  "status": "stopped"
}

Delete Script

DELETE

/api/scripts/{id}

Delete a script. A running script is stopped first. Returns 204 No Content on success (empty body).

Script Logs

GET

/api/scripts/{id}/logs

Get logs from a script execution. Accepts an optional since query parameter (RFC3339 or Unix timestamp) to only return logs after that time.

Response

{
  "text": "Script execution logs here..."
}

Guides & Tutorials

Hands-on walkthroughs for building on co-located Ethereum nodes with BLAZED.sh.

Ethereum webhooks: the complete guide to real-time on-chain events Building an Ethereum webhook API for real-time on-chain events How to access the Ethereum mempool from a co-located node eth_getLogs block range limits and how to chunk them