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

# API Reference

> AcuSight REST API Overview

# API Reference

The AcuSight API provides programmatic access to all platform functionality, from device management to MLOps workflows.

## Base URL

```
https://acusight.io
```

For self-hosted deployments:

```
https://<APP_HOST>/api    # Via Caddy (browser)
http://<LAN_IP>:8080/api  # Direct (devices)
```

## Authentication

AcuSight uses two authentication methods:

### Bearer Token (User API)

For user-facing APIs, use a JWT token obtained via OIDC login:

```bash theme={null}
curl https://acusight.io/api/organization \
  -H "Authorization: Bearer <JWT_TOKEN>"
```

### Device API Key (Device API)

For device-to-platform communication, use the API key received during provisioning:

```bash theme={null}
curl https://acusight.io/api/device/self \
  -H "X-Device-Key: adk_<YOUR_API_KEY>"
```

## API Groups

### Core API

User-authenticated endpoints for managing the platform.

| Endpoint                    | Method | Description                 |
| --------------------------- | ------ | --------------------------- |
| `/provisioning-tokens`      | POST   | Create provisioning token   |
| `/provisioning-tokens`      | GET    | List provisioning tokens    |
| `/provisioning-tokens/{id}` | DELETE | Revoke token                |
| `/devices/provision`        | POST   | Provision a device (public) |
| `/organization`             | GET    | Get organization details    |
| `/organization`             | PATCH  | Update organization         |

### Device API

Device-authenticated endpoints using `X-Device-Key` header.

| Endpoint                | Method | Description     |
| ----------------------- | ------ | --------------- |
| `/device/self`          | GET    | Get device info |
| `/device/checkin`       | POST   | Health check-in |
| `/device/images/upload` | POST   | Upload image    |

### Data API

MLOps data pipeline endpoints.

| Endpoint             | Method    | Description                  |
| -------------------- | --------- | ---------------------------- |
| `/data/projects`     | GET/POST  | List/create projects         |
| `/data/batches`      | GET       | List batches                 |
| `/data/batches/{id}` | PATCH     | Update batch                 |
| `/data/images/{id}`  | GET/PATCH | Get/update image             |
| `/data/annotations`  | POST      | Create annotation            |
| `/data/datasets`     | GET/POST  | List/create dataset versions |

### ML API

Model training and deployment endpoints.

| Endpoint            | Method   | Description                 |
| ------------------- | -------- | --------------------------- |
| `/ml/training-jobs` | GET/POST | List/create training jobs   |
| `/ml/models`        | GET      | List model versions         |
| `/ml/export-jobs`   | POST     | Export model for deployment |

## Response Format

All API responses follow a consistent envelope format:

### Success Response

```json theme={null}
{
  "success": true,
  "data": { ... },
  "meta": {
    "total": 100,
    "page": 1,
    "per_page": 20
  }
}
```

### Error Response

```json theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": "name is required"
  }
}
```

## Common Error Codes

| Code               | HTTP Status | Description                        |
| ------------------ | ----------- | ---------------------------------- |
| `VALIDATION_ERROR` | 400         | Invalid request body or parameters |
| `UNAUTHORIZED`     | 401         | Missing or invalid authentication  |
| `FORBIDDEN`        | 403         | Insufficient permissions           |
| `NOT_FOUND`        | 404         | Resource not found                 |
| `CONFLICT`         | 409         | Resource already exists            |
| `INTERNAL_ERROR`   | 500         | Server error                       |

## Rate Limiting

Rate limiting is not enforced by default. If you enable a limiter (for example at the reverse proxy), document the limits here.

## Pagination

List endpoints support pagination:

```bash theme={null}
GET /api/data/batches?page=2&per_page=50
```

| Parameter  | Default | Max |
| ---------- | ------- | --- |
| `page`     | 1       | -   |
| `per_page` | 20      | 100 |

Response includes pagination metadata:

```json theme={null}
{
  "meta": {
    "total": 250,
    "page": 2,
    "per_page": 50,
    "total_pages": 5
  }
}
```

## Interactive Documentation

Explore the full API using our interactive Swagger UI:

* **Cloud**: [acusight.io/swagger/](https://acusight.io/swagger/)
* **Self-hosted**: `https://<APP_HOST>/swagger/`

<Note>
  The Swagger UI allows you to authenticate and make real API calls directly from your browser.
</Note>

## SDKs and Client Libraries

Currently, AcuSight provides REST APIs only. Client libraries are planned for:

* Python (planned)
* Go (planned)
* TypeScript/JavaScript (planned)

For now, use standard HTTP clients like `curl`, `axios`, or `requests`.

## Next Steps

<CardGroup cols={2}>
  <Card title="Device Provisioning" icon="plus" href="/guides/deploy/device-provisioning">
    Learn the provisioning flow
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/reference/troubleshooting">
    Common API issues
  </Card>
</CardGroup>