API Reference

All endpoints are under https://api.avycenna.com/api/v1. All requests require authentication via Authorization: Bearer {token} or X-API-Key: avk_.... All responses are JSON.

Check-ins (Patient Data)

Get Patient Check-ins

Fetch a patient's daily check-ins. Requires an active grant with check_ins permission.

GET /api/v1/grants/patient/{patient_id}/check-ins?days=30

Parameters:

Parameter	Type	Default	Description
`patient_id`	path	required	The patient's user ID
`days`	query	`30`	Lookback window in days (max 365)

Example:

curl "https://api.avycenna.com/api/v1/grants/patient/usr_7jRtHvBk/check-ins?days=30" \
  -H "Authorization: Bearer eyJhbGci..."

Response:

{
  "patient_id": "usr_7jRtHvBk",
  "patient_name": "Alex Morgan",
  "check_ins": [
    {
      "id": "ci_4nWxYzAb",
      "user_id": "usr_7jRtHvBk",
      "mood": 4,
      "energy": 3,
      "focus": 4,
      "sleep_hours": 7.5,
      "steps": 9241,
      "note": "Good day overall, slight afternoon slump.",
      "checked_in_at": "2026-06-30T08:15:00Z",
      "source": "mobile"
    }
  ],
  "summary": {
    "avg_mood": 3.8,
    "avg_energy": 3.2,
    "avg_focus": 3.6,
    "avg_sleep_hours": 7.1,
    "avg_steps": 7834,
    "total_check_ins": 27,
    "days_requested": 30
  }
}

Response fields:

Field	Type	Description
`id`	string	Check-in ID
`user_id`	string	Patient's user ID
`mood`	integer	Mood score, 1–5
`energy`	integer	Energy score, 1–5
`focus`	integer	Focus score, 1–5
`sleep_hours`	number	Hours slept
`steps`	integer	Step count
`note`	string \| null	Journal note
`checked_in_at`	string (ISO 8601)	When the check-in was submitted
`source`	string	`mobile`, `web`, or `api`

Symptoms (Patient Data)

Get Patient Symptoms

Fetch a patient's symptom logs. Requires symptoms grant permission.

GET /api/v1/grants/patient/{patient_id}/symptoms?days=90

Example:

curl "https://api.avycenna.com/api/v1/grants/patient/usr_7jRtHvBk/symptoms?days=90" \
  -H "Authorization: Bearer eyJhbGci..."

Response:

{
  "patient_id": "usr_7jRtHvBk",
  "symptoms": [
    {
      "id": "sym_9pQrStUv",
      "name": "Migraine",
      "severity": "severe",
      "onset_at": "2026-06-25T14:00:00Z",
      "resolved_at": "2026-06-26T09:00:00Z",
      "status": "resolved",
      "notes": "Right-side, light sensitivity, lasted ~19 hours."
    },
    {
      "id": "sym_2cDeFgHi",
      "name": "Lower back pain",
      "severity": "moderate",
      "onset_at": "2026-06-28T00:00:00Z",
      "resolved_at": null,
      "status": "active",
      "notes": "Worse when sitting for long periods."
    }
  ]
}

Response fields:

Field	Type	Description
`id`	string	Symptom ID
`name`	string	Symptom name as logged by patient
`severity`	string	`mild`, `moderate`, `severe`, or `critical`
`onset_at`	string (ISO 8601)	When the symptom started
`resolved_at`	string \| null	When it resolved, or null if still active
`status`	string	`active` or `resolved`
`notes`	string \| null	Patient's notes

Grants Management

List Your Patients

Returns all patients with an active grant to you.

GET /api/v1/grants/outgoing

curl https://api.avycenna.com/api/v1/grants/outgoing \
  -H "Authorization: Bearer eyJhbGci..."

Response:

{
  "grants": [
    {
      "id": "grant_2xK9mNpQ",
      "patient_id": "usr_7jRtHvBk",
      "patient_name": "Alex Morgan",
      "patient_email": "alex@example.com",
      "permissions": ["check_ins", "symptoms"],
      "status": "active",
      "granted_at": "2026-03-15T10:22:00Z",
      "expires_at": null,
      "last_check_in_at": "2026-06-30T08:15:00Z"
    }
  ]
}

Send a Grant Invitation

Invite a patient to share their data with you.

POST /api/v1/grants/invite

curl -X POST https://api.avycenna.com/api/v1/grants/invite \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{
    "patient_email": "patient@example.com",
    "permissions": ["check_ins", "symptoms", "medications"],
    "message": "I would like to monitor your health data between our appointments.",
    "expires_at": "2027-06-30T00:00:00Z"
  }'

Request body:

Field	Required	Description
`patient_email`	Yes	Patient's registered email
`permissions`	Yes	Array: any of `check_ins`, `symptoms`, `medications`
`message`	No	Personal note shown to the patient
`expires_at`	No	ISO 8601 datetime for auto-expiry

Response (201):

{
  "grant_id": "grant_2xK9mNpQ",
  "status": "pending",
  "invited_at": "2026-06-30T14:00:00Z"
}

Revoke a Grant

Close an active grant. Access terminates immediately.

POST /api/v1/grants/revoke

curl -X POST https://api.avycenna.com/api/v1/grants/revoke \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{
    "grant_id": "grant_2xK9mNpQ",
    "reason": "Patient transferred to another provider"
  }'

Your Own Account

Get Current User

GET /api/v1/auth/me

curl https://api.avycenna.com/api/v1/auth/me \
  -H "Authorization: Bearer eyJhbGci..."

Returns the authenticated user's account and profile. See Authentication for the full response shape.

Get User Profile

GET /api/v1/users/me

Returns extended profile fields (specialty, institution, etc.).

Update User Profile

PATCH /api/v1/users/me/profile

curl -X PATCH https://api.avycenna.com/api/v1/users/me/profile \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{
    "specialty": "Cardiology",
    "institution": "City Medical Center"
  }'

API Keys

List API Keys

GET /api/v1/api-keys

curl https://api.avycenna.com/api/v1/api-keys \
  -H "Authorization: Bearer eyJhbGci..."

Response:

{
  "api_keys": [
    {
      "id": "key_3mPqRsTu",
      "name": "EHR Integration - Production",
      "scopes": ["read:health", "read:users"],
      "created_at": "2026-06-01T09:00:00Z",
      "last_used_at": "2026-06-30T13:47:00Z",
      "key_prefix": "avk_a7f3..."
    }
  ]
}

The key_prefix is a safe preview — the full key is never returned after creation.

Create an API Key

POST /api/v1/api-keys

curl -X POST https://api.avycenna.com/api/v1/api-keys \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "EHR Integration - Production",
    "scopes": ["read:health", "read:users"]
  }'

The full key value (avk_...) is returned once and only once in this response. Store it immediately.

Delete an API Key

DELETE /api/v1/api-keys/{key_id}

curl -X DELETE https://api.avycenna.com/api/v1/api-keys/key_3mPqRsTu \
  -H "Authorization: Bearer eyJhbGci..."

Returns 204 No Content on success. Deletion is immediate and irreversible.

Error Reference

HTTP Status	When It Occurs
`400 Bad Request`	Malformed request body or invalid parameters
`401 Unauthorized`	Missing or invalid authentication token
`403 Forbidden`	Valid auth but insufficient permissions (e.g., no grant for patient)
`404 Not Found`	Resource doesn't exist
`422 Unprocessable Entity`	Request body failed validation (see `detail` array)
`429 Too Many Requests`	Rate limit exceeded
`500 Internal Server Error`	Unexpected server error

API Reference

On this page