AiSpinner

Appearance

REST API ​

AiSpinner provides a REST API at https://api.aispinner.io.

All endpoints require authentication via Bearer token (JWT), obtained through the login endpoint.

Authentication ​

Login ​

http
POST /login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your_password"
}

Response:

json
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer"
}

Get Current User ​

http
GET /me
Authorization: Bearer <token>

Response:

json
{
  "id": 1,
  "email": "user@example.com",
  "nickname": "username",
  "plan": "free"
}

Register ​

http
POST /register/start
Content-Type: application/json

{"email": "user@example.com", "password": "...", "nickname": "username"}

Sends a confirmation code to the email. Confirm with:

http
POST /register/confirm
Content-Type: application/json

{"email": "user@example.com", "code": "123456"}

Workspaces ​

List Workspaces ​

http
GET /workspaces
Authorization: Bearer <token>

Get Workspace with Graph ​

http
GET /workspaces/me
Authorization: Bearer <token>

Returns the current workspace including the full graph (blocks and edges).

Get Graph ​

http
GET /workspaces/{id}/graph
Authorization: Bearer <token>

Response:

json
{
  "version": 42,
  "graph_json": {
    "nodes": [
      {
        "id": "node_abc123",
        "type": "code.worker",
        "data": {
          "label": "My Worker",
          "x": 100,
          "y": 200,
          "cfg": {"tick_interval": 10}
        }
      }
    ],
    "edges": [
      {
        "id": "edge_1",
        "source": "node_abc123",
        "target": "node_def456"
      }
    ]
  }
}

Save Graph ​

http
PUT /workspaces/{id}/graph
Authorization: Bearer <token>
Content-Type: application/json

{
  "version": 42,
  "graph_json": { ... }
}

Uses optimistic locking -- the version must match the server's current version.

Workers ​

Deploy Worker Code ​

http
POST /workers/deploy
Authorization: Bearer <token>
Content-Type: application/json

{
  "workspace_id": 1,
  "node_id": "worker_abc123",
  "code": "def setup(ctx): pass\ndef tick(ctx): pass",
  "tick_interval": 10,
  "max_errors": 5,
  "auto_heal": true,
  "connected_blocks": {
    "trading_node_id": "bybit_1",
    "monitor_node_ids": ["monitor_1"]
  }
}

Start Worker ​

http
POST /workers/{workspace_id}/{node_id}/start
Authorization: Bearer <token>

Stop Worker ​

http
POST /workers/{workspace_id}/{node_id}/stop
Authorization: Bearer <token>

Get Worker Status ​

http
GET /workers/{workspace_id}/{node_id}/status
Authorization: Bearer <token>

Response:

json
{
  "status": "running",
  "tick_count": 1234,
  "error_count": 0,
  "tick_interval": 10,
  "auto_heal": true,
  "max_errors": 5,
  "last_tick_at": "2026-03-10T12:34:56Z"
}

Get Worker Logs ​

http
GET /workers/{workspace_id}/{node_id}/logs?limit=100&level=info
Authorization: Bearer <token>

Update Worker Settings ​

http
PATCH /workers/{workspace_id}/{node_id}/settings
Authorization: Bearer <token>
Content-Type: application/json

{
  "tick_interval": 30,
  "max_errors": 10,
  "auto_heal": false
}

No redeployment needed -- settings update immediately.

Node Configs ​

Get Node Config ​

http
GET /workspaces/{workspace_id}/nodes/{node_id}/config
Authorization: Bearer <token>

Update Node Config ​

http
PUT /workspaces/{workspace_id}/nodes/{node_id}/config
Authorization: Bearer <token>
Content-Type: application/json

{
  "config_json": {
    "api_key_id": 1,
    "tick_interval": 10
  }
}

MCP (Model Context Protocol) ​

AiSpinner exposes an MCP endpoint for AI assistant integration:

Endpoint: https://api.aispinner.io/mcp-api/mcp
Auth: Bearer token (same JWT as REST API)

Available MCP tools: get_workspace_graph, get_node_config, list_block_types, get_worker_logs, get_call_history, add_node, remove_node, connect_nodes, disconnect_nodes, update_node_config, rename_node, restart_worker, start_dialer.

Error Responses ​

All errors follow this format:

json
{
  "detail": "Error description here"
}

Common HTTP status codes:

  • 401 -- Not authenticated (missing or invalid token)
  • 403 -- Forbidden (insufficient plan or permissions)
  • 404 -- Resource not found
  • 409 -- Version conflict (optimistic locking on graph save)
  • 422 -- Validation error
  • 500 -- Server error

AiSpinner Documentation

Copyright 2024-2026 AiSpinner