API Documentation

Complete reference for the Briefly. API v1.

Authentication

All API requests require authentication via an API key passed in the Authorization header using the Bearer scheme.

bash

curl -X GET "https://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 Key Scopes

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

Rate Limits

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.

Letters

GET

/api/v1/lettersList letters for the practice with optional filtering.

GET

/api/v1/letters/{id}Get full details of a single letter including content.

POST

/api/v1/lettersCreate a new letter from a transcript.

Patients

GET

/api/v1/patientsSearch for patients by name or email.

POST

/api/v1/patientsCreate a new patient record.

Recordings

POST

/api/v1/recordingsSubmit an audio recording for transcription and letter generation.

GET

/api/v1/recordings/{id}/statusCheck the transcription and letter generation status.

Error Handling

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

json

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request body",
    "details": [
      { "path": ["patientId"], "message": "Required" }
    ]
  }
}