API Reference
Complete reference for all Sparkient API endpoints.
The Sparkient API is a RESTful JSON API. All endpoints are prefixed with /api/v1 and require authentication via API key or Firebase JWT.
Base URL: https://api.sparkient.ai/api/v1
Endpoints Overview
| Group | Endpoints | Description |
|---|---|---|
| Decisions | POST /decide, POST /decide/batch | Make single or batch decisions |
| Decision Types | CRUD on /decision-types | Create, list, get, update, delete decision types |
| Examples | /decision-types/{id}/examples | Manage training examples |
| Training | /decision-types/{id}/train | Trigger model training |
| Policies | /decision-types/{id}/policies | List and deploy trained models |
| Logs | /decision-types/{id}/logs | Query decision history |
| Export | /decision-types/{id}/export | Download edge bundles |
| Auth | /auth/me, /auth/org | User and organization management |
| API Keys | /api-keys | Create, list, and revoke API keys |
| Metrics | /metrics | Organization-level aggregate statistics |
| System | /health, /ready | Health and readiness probes |
Interactive endpoint documentation is generated automatically from the OpenAPI specification. If you're viewing a freshly built docs site, the detailed endpoint pages will appear below once the OpenAPI spec has been processed.
Common Patterns
Authentication
All requests require a Bearer token:
-H "Authorization: Bearer YOUR_API_KEY"Error Responses
All errors follow a consistent envelope format with a machine-readable code field:
{
"error": {
"code": "decision_type_not_found",
"message": "Decision type 'nonexistent' not found."
}
}Validation errors (422) include a details array:
{
"error": {
"code": "validation_error",
"message": "Request validation failed.",
"details": [
{
"type": "missing",
"loc": ["body", "decision_type"],
"msg": "Field required"
}
]
}
}| Status | Code | Description |
|---|---|---|
| 400 | bad_request | Malformed request |
| 401 | unauthorized | Missing or invalid credentials |
| 403 | forbidden | Insufficient permissions |
| 404 | not_found | Resource not found |
| 404 | decision_type_not_found | Decision type does not exist |
| 413 | payload_too_large | Request body exceeds size limit |
| 422 | validation_error | Request validation failed |
| 429 | rate_limited | Rate limit exceeded |
| 500 | internal_error | Unexpected server error |
Rate Limiting
API key requests include rate limit headers on every response:
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests per window |
X-RateLimit-Remaining | Requests remaining in current window |
X-RateLimit-Reset | Unix timestamp when the window resets |
Retry-After | Seconds to wait (only on 429 responses) |
Pagination
List endpoints support pagination via query parameters:
| Parameter | Default | Range | Description |
|---|---|---|---|
page | 1 | ≥ 1 | Page number |
page_size | 20 | 1–100 | Items per page |
Paginated responses return:
{
"items": ["..."],
"total": 42,
"page": 1,
"page_size": 20,
"pages": 3
}