API Reference
The Acusight API provides programmatic access to all platform functionality, from device management to MLOps workflows.
Base URL
For self-hosted deployments:
https://<SERVER_EXTERNAL_IP>/api # Via Caddy (browser)
http://<SERVER_EXTERNAL_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:
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:
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 |
Success Response
{
"success": true,
"data": { ... },
"meta": {
"total": 100,
"page": 1,
"per_page": 20
}
}
Error Response
{
"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.
List endpoints support pagination:
GET /api/data/batches?page=2&per_page=50
| Parameter | Default | Max |
|---|
page | 1 | - |
per_page | 20 | 100 |
{
"meta": {
"total": 250,
"page": 2,
"per_page": 50,
"total_pages": 5
}
}
Interactive Documentation
Explore the full API using our interactive Swagger UI:
The Swagger UI allows you to authenticate and make real API calls directly from your browser.
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
