API Overview

The AVYCENNA REST API gives you programmatic access to everything in the platform — patient data (with grants), your own account, wearable ingestion, and more. It's a standard JSON API over HTTPS.

Base URL

https://api.avycenna.com/api/v1

For self-hosted deployments, replace api.avycenna.com with your instance's API hostname.

Interactive Docs

Two interactive API documentation interfaces are available on your running instance:

Interface	URL	Best For
Swagger UI	`/docs`	Trying out endpoints interactively
ReDoc	`/redoc`	Reading reference documentation

Both are auto-generated from the OpenAPI schema and always reflect the exact current API.

Request Format

All requests use JSON. Include the Content-Type: application/json header on any request with a body.

curl -X POST https://api.avycenna.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@clinic.com", "password": "..."}'

Fields use snake_case. Timestamps are ISO 8601 strings in UTC.

Authentication

Two authentication methods are supported:

Obtain a JWT access token via login or OTP verification, then pass it in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Access tokens expire after 15 minutes. Use the refresh token to obtain a new one without re-authenticating.

Generate an API key from the dashboard or via POST /api/v1/api-keys. Pass it in the X-API-Key header:

X-API-Key: avk_a7f3c91e8b2d4...

API keys do not expire unless deleted. They're ideal for server-to-server integrations and automation.

See Authentication for the complete auth reference.

Response Format

All responses are JSON with snake_case field names.

Success:

{
  "id": "usr_7jRtHvBk",
  "email": "doctor@clinic.com",
  "name": "Dr. Sarah Chen",
  "created_at": "2026-01-15T09:00:00Z"
}

Validation error (422):

{
  "detail": [
    {
      "loc": ["body", "email"],
      "msg": "value is not a valid email address",
      "type": "value_error.email"
    }
  ]
}

Application error (400, 401, 403, 404, etc.):

{
  "detail": "Grant not found or access denied."
}

Rate Limiting

Auth Method	Rate Limit
JWT Bearer token	100 requests per minute
API Key	1,000 requests per minute

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1751285520

When you exceed the limit, you receive a 429 Too Many Requests response. Back off and retry after the Retry-After header value (in seconds).

Health Check

The health endpoint requires no authentication and is useful for uptime monitoring:

curl https://api.avycenna.com/health

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2026-06-30T14:22:00Z"
}

Quick Start

Here's everything you need to make your first authenticated API call:

# 1. Request an OTP to your email
curl -X POST https://api.avycenna.com/api/v1/auth/otp/send \
  -H "Content-Type: application/json" \
  -d '{"email": "you@clinic.com"}'

# 2. Verify the OTP (from your email) and get tokens
curl -X POST https://api.avycenna.com/api/v1/auth/otp/verify \
  -H "Content-Type: application/json" \
  -d '{"email": "you@clinic.com", "otp": "847291"}'

# Response includes access_token and refresh_token
# Store the access_token as $TOKEN

# 3. Check your profile
curl https://api.avycenna.com/api/v1/auth/me \
  -H "Authorization: Bearer $TOKEN"

# 4. List your patients (requires active grants)
curl https://api.avycenna.com/api/v1/grants/outgoing \
  -H "Authorization: Bearer $TOKEN"

API Overview

On this page