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

# API Introduction

> Station REST API reference

## Overview

Station provides a REST API for programmatic access to all features.

**Base URL**: `http://localhost:8585/api/v1`

## Authentication

### Local Mode

No authentication required when `local_mode: true`.

### CloudShip Mode

Use bearer token authentication:

```bash theme={null}
curl -H "Authorization: Bearer your-token" \
  http://localhost:8585/api/v1/agents
```

## Endpoints

### Health

```http theme={null}
GET /api/v1/health
```

Returns server health status.

### Agents

| Method | Endpoint                 | Description       |
| ------ | ------------------------ | ----------------- |
| GET    | `/api/v1/agents`         | List all agents   |
| GET    | `/api/v1/agents/:id`     | Get agent details |
| POST   | `/api/v1/agents`         | Create agent      |
| PUT    | `/api/v1/agents/:id`     | Update agent      |
| DELETE | `/api/v1/agents/:id`     | Delete agent      |
| POST   | `/api/v1/agents/:id/run` | Execute agent     |

### Environments

| Method | Endpoint                          | Description       |
| ------ | --------------------------------- | ----------------- |
| GET    | `/api/v1/environments`            | List environments |
| GET    | `/api/v1/environments/:name`      | Get environment   |
| POST   | `/api/v1/environments/:name/sync` | Sync environment  |

### MCP Servers

| Method | Endpoint              | Description          |
| ------ | --------------------- | -------------------- |
| GET    | `/api/v1/mcp-servers` | List MCP servers     |
| GET    | `/api/v1/tools`       | List available tools |

### Runs

| Method | Endpoint           | Description     |
| ------ | ------------------ | --------------- |
| GET    | `/api/v1/runs`     | List agent runs |
| GET    | `/api/v1/runs/:id` | Get run details |

## Response Format

All responses follow this format:

```json theme={null}
{
  "success": true,
  "data": { ... },
  "error": null
}
```

Error response:

```json theme={null}
{
  "success": false,
  "data": null,
  "error": {
    "code": "AGENT_NOT_FOUND",
    "message": "Agent with ID 123 not found"
  }
}
```

## Pagination

List endpoints support pagination:

```http theme={null}
GET /api/v1/agents?page=1&limit=20
```

Response includes pagination metadata:

```json theme={null}
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "pages": 3
  }
}
```

## Rate Limiting

| Mode      | Limit       |
| --------- | ----------- |
| Local     | None        |
| CloudShip | 100 req/min |

## SDKs

Official SDKs coming soon:

* Python
* TypeScript
* Go

## OpenAPI Spec

Download the OpenAPI specification:

```bash theme={null}
curl http://localhost:8585/api/v1/openapi.json -o openapi.json
```