> ## Documentation Index
> Fetch the complete documentation index at: https://docs.splox.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API Introduction

> Run workflows, manage chats, and monitor execution via the Splox API

## Base URL

All API requests should be made to:

```
https://app.splox.io/api/v1
```

## Official SDKs

Use our official SDKs instead of raw HTTP requests:

<CodeGroup>
  ```bash Python theme={null}
  pip install splox
  ```

  ```bash Node.js theme={null}
  npm install splox
  ```

  ```bash Go theme={null}
  go get github.com/splox-ai/go-sdk
  ```
</CodeGroup>

See the full [SDK documentation](/sdks) for quickstart examples, authentication, error handling, and more.

## Authentication

Protected endpoints require a Bearer token in the Authorization header:

```bash theme={null}
Authorization: Bearer YOUR_API_TOKEN
```

Generate API tokens from your [account settings](https://app.splox.io/account?tab=settings).

<Info>
  API tokens require a minimum \$2.00 account balance to create. Tokens can be configured with custom expiry (default: 1 hour, max: 1 year).
</Info>

## Endpoints

The Splox API provides these endpoints:

### Workflows

| Method | Endpoint                          | Description                         |
| ------ | --------------------------------- | ----------------------------------- |
| GET    | `/workflows`                      | List all workflows                  |
| GET    | `/workflows/{id}`                 | Get a workflow with nodes and edges |
| GET    | `/workflows/{id}/versions/latest` | Get the latest workflow version     |
| GET    | `/workflows/{id}/versions`        | List all workflow versions          |
| GET    | `/workflows/{id}/entry-nodes`     | Get entry nodes for a version       |

### Workflow Execution

| Method | Endpoint                                 | Description                      |
| ------ | ---------------------------------------- | -------------------------------- |
| POST   | `/workflow-requests/run`                 | Run a workflow                   |
| GET    | `/workflow-requests/{id}/listen`         | Stream execution updates (SSE)   |
| GET    | `/workflow-requests/{id}/execution-tree` | Get complete execution hierarchy |
| GET    | `/workflow-requests/{id}/history`        | Get past executions              |
| POST   | `/workflow-requests/{id}/stop`           | Stop a running workflow          |

### Chats

| Method | Endpoint                                  | Description                   |
| ------ | ----------------------------------------- | ----------------------------- |
| POST   | `/chats`                                  | Create a new chat session     |
| GET    | `/chats/{resourceType}/{resourceId}`      | List chats for a resource     |
| GET    | `/chats/{id}`                             | Get a chat session            |
| DELETE | `/chats/{id}`                             | Delete a chat session         |
| GET    | `/chat-history/{chatId}/paginated`        | Get paginated message history |
| DELETE | `/chat-history/{chatId}`                  | Delete all message history    |
| GET    | `/chat-internal-messages/{chatId}/listen` | Stream chat events (SSE)      |

### Events

| Method | Endpoint               | Description                        |
| ------ | ---------------------- | ---------------------------------- |
| POST   | `/events/{webhook_id}` | Receive external event via webhook |

### Billing

| Method | Endpoint                | Description                       |
| ------ | ----------------------- | --------------------------------- |
| GET    | `/billing/balance`      | Get current account balance       |
| GET    | `/billing/transactions` | Get paginated transaction history |
| GET    | `/activity/stats`       | Get aggregate activity statistics |
| GET    | `/activity/daily`       | Get daily spending and usage data |

## Typical API Flow

<Steps>
  <Step title="Discover Your Workflow">
    `GET /workflows` — List your workflows (or search by name). Then get the latest version with `GET /workflows/{id}/versions/latest` and its entry nodes with `GET /workflows/{versionId}/entry-nodes`.
  </Step>

  <Step title="Create a Chat">
    `POST /chats` — Create a chat session for the workflow. The chat ID is used for context memory and SSE streaming.
  </Step>

  <Step title="Run the Workflow">
    `POST /workflow-requests/run` — Trigger the workflow with your query, chat ID, workflow version ID, and entry node IDs. Returns a `workflow_request_id`.
  </Step>

  <Step title="Listen for Results">
    `GET /workflow-requests/{id}/listen` — Connect to the SSE stream to receive real-time execution updates as nodes complete.
  </Step>
</Steps>

## Response Format

All responses return JSON. Example run workflow response:

```json theme={null}
{
  "workflow_request_id": "0199f123-d60e-7ffd-9131-4cc5ab040ee8"
}
```

Use this ID to listen for results, get the execution tree, or check history.

## SSE Streaming

SSE endpoints (`/listen`) use standard Server-Sent Events format:

```
data: {"workflow_request": {...}, "node_execution": {...}}

data: keepalive
```

* Keepalive messages sent every **3 seconds**
* Connection timeout: **30 minutes** (reconnect if needed)

## Rate Limits

| Endpoint                      | Limit                  |
| ----------------------------- | ---------------------- |
| `POST /workflow-requests/run` | 20 per minute per user |

## Support

* **Community**: [community.splox.io](https://community.splox.io/)
* **Email**: [support@splox.io](mailto:support@splox.io)