Complete reference for the Briefly. API v1.
All API requests require authentication via an API key passed in the Authorization header using the Bearer scheme.
curl -X GET "https://app.briefly.health/api/v1/letters" \
-H "Authorization: Bearer briefly_sk_your_key_here"Keep your API key secure
Never expose your API key in client-side code. Store it securely in environment variables on your server.
API keys can be configured with specific scopes to limit access:
| Scope | Description |
|---|---|
| letters:read | Read letters |
| letters:write | Create letters |
| patients:read | Read patients |
| patients:write | Create patients |
| recordings:read | Read recording status |
| recordings:write | Submit recordings |
API requests are rate limited to ensure fair usage and system stability.
| Plan | Limit | Window |
|---|---|---|
| Standard | 100 requests | 1 minute |
| Enterprise | 1000 requests | 1 minute |
When rate limited, the API returns HTTP 429 with a Retry-After header indicating seconds to wait.
/api/v1/lettersList letters for the practice with optional filtering./api/v1/letters/{id}Get full details of a single letter including content./api/v1/lettersCreate a new letter from a transcript./api/v1/patientsSearch for patients by name or email./api/v1/patientsCreate a new patient record./api/v1/recordingsSubmit an audio recording for transcription and letter generation./api/v1/recordings/{id}/statusCheck the transcription and letter generation status.The API uses standard HTTP status codes to indicate success or failure.
| Status | Code | Description |
|---|---|---|
| 400 | BAD_REQUEST | Invalid request body or parameters |
| 401 | UNAUTHORIZED | Invalid or missing API key |
| 403 | FORBIDDEN | Missing required scopes |
| 404 | NOT_FOUND | Resource not found |
| 429 | RATE_LIMITED | Too many requests |
| 500 | SERVER_ERROR | Internal server error |
{
"error": {
"code": "BAD_REQUEST",
"message": "Invalid request body",
"details": [
{ "path": ["patientId"], "message": "Required" }
]
}
}