API Reference
API Reference
REST API for integrating with the Headways platform.
The Headways API allows you to programmatically interact with the platform. All endpoints require authentication via API key.
Base URL
https://api.headways.ai/v1Authentication
Include your API key in the Authorization header:
curl -H "Authorization: Bearer hw_your_api_key" \
https://api.headways.ai/v1/orgAPI keys are managed under Settings > API Keys in the dashboard. Each key is scoped to a specific organization.
Rate Limits
| Plan | Requests/minute | Requests/day |
|---|---|---|
| Starter | 60 | 10,000 |
| Pro | 300 | 100,000 |
| Enterprise | Custom | Custom |
Rate limit headers are included in every response:
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1717200000Endpoints
Organization
| Method | Path | Description |
|---|---|---|
GET | /org | Get organization details |
GET | /org/members | List organization members |
POST | /org/members/invite | Invite a new member |
Maturity
| Method | Path | Description |
|---|---|---|
GET | /maturity | Get current maturity score |
GET | /maturity/history | Get score history |
GET | /maturity/teams | Get per-team scores |
Fluency
| Method | Path | Description |
|---|---|---|
GET | /fluency/scores | List fluency scores |
GET | /fluency/scores/:userId | Get individual score |
GET | /fluency/distribution | Get score distribution |
Workflows
| Method | Path | Description |
|---|---|---|
GET | /workflows | List workflows |
GET | /workflows/:id | Get workflow details |
POST | /workflows/:id/assign | Assign workflow to users |
GET | /workflows/:id/progress | Get completion progress |
Diagnostic
| Method | Path | Description |
|---|---|---|
POST | /diagnostic/sessions | Create a diagnostic session |
GET | /diagnostic/sessions/:id | Get session results |
GET | /diagnostic/reports/:id | Get the scored report |
Error Responses
All errors follow a consistent format:
{
"error": {
"code": "invalid_request",
"message": "The request body is missing the required 'email' field.",
"status": 400
}
}| Status | Code | Description |
|---|---|---|
| 400 | invalid_request | Malformed request |
| 401 | unauthorized | Missing or invalid API key |
| 403 | forbidden | Insufficient permissions |
| 404 | not_found | Resource does not exist |
| 429 | rate_limited | Too many requests |
| 500 | internal_error | Server error |
Pagination
List endpoints support cursor-based pagination:
GET /org/members?limit=25&cursor=eyJpZCI6MTAwfQResponse includes pagination metadata:
{
"data": [...],
"pagination": {
"has_more": true,
"next_cursor": "eyJpZCI6MTI1fQ"
}
}