Aurabox REST API

What This Skill Does

Generates correct, working client code for the Aurabox Cloud REST API. Knows the full API surface -- patients, cases, studies -- including authentication, pagination, and error handling. Produces idiomatic code in Python, TypeScript/JavaScript, PHP, and curl.

Prerequisites

An Aurabox account with API access enabled
An API key (generated from the Aurabox dashboard under your team settings)
Familiarity with REST APIs

Quick Reference

Base URL

https://au.aurabox.cloud

Authentication

All requests require a Bearer token in the Authorization header:

Authorization: Bearer {YOUR_AUTH_KEY}
Content-Type: application/json
Accept: application/json

API keys are generated in the Aurabox web interface. They are scoped to a team realm.

Security: API keys are sensitive. Never commit them to source control. Use environment variables or a secrets manager.

OpenAPI / Postman

Machine-readable specs are available:

OpenAPI: https://au.aurabox.app/docs/openapi.yaml
Postman collection: https://au.aurabox.app/docs/collection.json

API Surface

Patients

Full CRUD for patient records within the authenticated team realm.

Data Model

{
  "id": "003fb6c7-a399-46de-8199-ac51e031bd10",
  "given_names": "Jessica",
  "family_name": "Jones",
  "date_of_birth": "1985-06-15",
  "sex": "female",
  "address": {
    "street": "123 Main Street",
    "city": "Sydney",
    "region": "NSW",
    "postcode": "2000",
    "country": "au"
  },
  "status": "active",
  "archived": false,
  "created_at": "2025-01-15T10:30:00.000000Z",
  "updated_at": "2025-01-15T10:30:00.000000Z"
}

Endpoints

Method	Path	Description
`GET`	`/api/v1/patients`	List patients (paginated, searchable, sortable)
`POST`	`/api/v1/patients`	Create a patient
`GET`	`/api/v1/patients/{id}`	Retrieve a patient
`PUT`	`/api/v1/patients/{id}`	Update a patient
`DELETE`	`/api/v1/patients/{id}`	Delete a patient

List Parameters

Parameter	Type	Values
`per_page`	integer	1-100
`search`	string	Max 255 chars
`sort`	string	`name`, `created_at`, `updated_at`, `date_of_birth`
`direction`	string	`asc`, `desc`
`archived`	boolean	`true`, `false`

Create/Update Fields

Field	Type	Required (create)	Notes
`given_names`	string	Yes	Max 255 chars
`family_name`	string	Yes	Max 255 chars
`date_of_birth`	string	Yes	Date format, must be before today
`sex`	string	Yes	`male`, `female`, `other`, `unknown`
`address`	object	No	Contains `street`, `city`, `region`, `postcode` (max 20), `country` (max 2, ISO)

Cases (De-identified Patients)

Cases are patients whose identity has been removed. Only a label and non-identifying metadata are stored.

Data Model

{
  "id": "003fb6c7-a399-46de-8199-ac51e031bd10",
  "label": "CASE-00142",
  "status": "deidentified",
  "archived": false,
  "created_at": "2025-01-15T10:30:00.000000Z",
  "updated_at": "2025-01-15T10:30:00.000000Z"
}

Endpoints

Method	Path	Description
`GET`	`/api/v1/cases`	List cases (paginated, searchable, sortable)
`POST`	`/api/v1/cases`	Create a case
`GET`	`/api/v1/cases/{patient_id}`	Show a case
`PUT`	`/api/v1/cases/{patient_id}`	Update a case
`DELETE`	`/api/v1/cases/{patient_id}`	Delete a case

List Parameters

Parameter	Type	Values
`per_page`	integer	1-100
`search`	string	Max 255 chars (searches label)
`sort`	string	`label`, `created_at`, `updated_at`, `date_of_birth`
`direction`	string	`asc`, `desc`
`archived`	boolean	`true`, `false`

Create/Update Fields

Field	Type	Required (create)	Notes
`label`	string	Yes	Max 255 chars
`sex`	string	No	`male`, `female`, `other`, `unknown`
`date_of_birth`	string	No	Date format, must be before today

Studies

Studies are nested under patients. Each study represents a medical imaging study (e.g., a CT scan, MRI, X-ray).

Endpoints

Method	Path	Description
`GET`	`/api/v1/patients/{patient_id}/studies`	List studies for a patient
`POST`	`/api/v1/patients/{patient_id}/studies`	Create a study
`GET`	`/api/v1/patients/{patient_id}/studies/{id}`	Retrieve a study
`PUT`	`/api/v1/patients/{patient_id}/studies/{id}`	Update a study
`DELETE`	`/api/v1/patients/{patient_id}/studies/{id}`	Delete a study

Pagination

All list endpoints return paginated responses using Laravel-style pagination:

{
  "data": [ ... ],
  "links": {
    "first": "https://au.aurabox.cloud/api/v1/patients?page=1",
    "last": "https://au.aurabox.cloud/api/v1/patients?page=5",
    "prev": null,
    "next": "https://au.aurabox.cloud/api/v1/patients?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "per_page": 25,
    "to": 25,
    "total": 112
  }
}

To paginate, follow the links.next URL or increment the page query parameter.

Code Examples

Python Client

import requests
import os

BASE_URL = "https://au.aurabox.cloud"


class AuraboxClient:
    """Client for the Aurabox REST API."""

    def __init__(self, api_key: str):
        self.base_url = BASE_URL
        self.session = requests.Session()
        self.session.headers.update({
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
            "Accept": "application/json",
        })

    def _request(self, method: str, path: str, **kwargs) -> dict:
        url = f"{self.base_url}{path}"
        response = self.session.request(method, url, **kwargs)
        response.raise_for_status()
        if response.status_code == 204:
            return {}
        return response.json()

    # --- Patients ---

    def list_patients(self, search: str = None, per_page: int = 25,
                      sort: str = "created_at", direction: str = "desc",
                      archived: bool = False) -> dict:
        params = {"per_page": per_page, "sort": sort,
                  "direction": direction, "archived": archived}
        if search:
            params["search"] = search
        return self._request("GET", "/api/v1/patients", params=params)

    def get_patient(self, patient_id: str) -> dict:
        return self._request("GET", f"/api/v1/patients/{patient_id}")

    def create_patient(self, given_names: str, family_name: str,
                       date_of_birth: str, sex: str,
                       address: dict = None) -> dict:
        body = {
            "given_names": given_names,
            "family_name": family_name,
            "date_of_birth": date_of_birth,
            "sex": sex,
        }
        if address:
            body["address"] = address
        return self._request("POST", "/api/v1/patients", json=body)

    def update_patient(self, patient_id: str, **fields) -> dict:
        return self._request("PUT", f"/api/v1/patients/{patient_id}", json=fields)

    def delete_patient(self, patient_id: str) -> dict:
        return self._request("DELETE", f"/api/v1/patients/{patient_id}")

    # --- Cases (de-identified patients) ---

    def list_cases(self, search: str = None, per_page: int = 25,
                   sort: str = "created_at", direction: str = "desc",
                   archived: bool = False) -> dict:
        params = {"per_page": per_page, "sort": sort,
                  "direction": direction, "archived": archived}
        if search:
            params["search"] = search
        return self._request("GET", "/api/v1/cases", params=params)

    def get_case(self, case_id: str) -> dict:
        return self._request("GET", f"/api/v1/cases/{case_id}")

    def create_case(self, label: str, sex: str = None,
                    date_of_birth: str = None) -> dict:
        body = {"label": label}
        if sex:
            body["sex"] = sex
        if date_of_birth:
            body["date_of_birth"] = date_of_birth
        return self._request("POST", "/api/v1/cases", json=body)

    def update_case(self, case_id: str, **fields) -> dict:
        return self._request("PUT", f"/api/v1/cases/{case_id}", json=fields)

    def delete_case(self, case_id: str) -> dict:
        return self._request("DELETE", f"/api/v1/cases/{case_id}")

    # --- Studies (nested under patients) ---

    def list_studies(self, patient_id: str) -> dict:
        return self._request("GET", f"/api/v1/patients/{patient_id}/studies")

    def get_study(self, patient_id: str, study_id: str) -> dict:
        return self._request("GET",
            f"/api/v1/patients/{patient_id}/studies/{study_id}")

    def create_study(self, patient_id: str, **fields) -> dict:
        return self._request("POST",
            f"/api/v1/patients/{patient_id}/studies", json=fields)

    def update_study(self, patient_id: str, study_id: str, **fields) -> dict:
        return self._request("PUT",
            f"/api/v1/patients/{patient_id}/studies/{study_id}", json=fields)

    def delete_study(self, patient_id: str, study_id: str) -> dict:
        return self._request("DELETE",
            f"/api/v1/patients/{patient_id}/studies/{study_id}")

    # --- Pagination helper ---

    def paginate(self, method, *args, **kwargs):
        """Iterate through all pages of a paginated endpoint."""
        response = method(*args, **kwargs)
        while True:
            yield from response.get("data", [])
            next_url = response.get("links", {}).get("next")
            if not next_url:
                break
            response = self.session.get(next_url).json()


# Usage
client = AuraboxClient(api_key=os.environ["AURABOX_API_KEY"])
patients = client.list_patients(search="Jones")

TypeScript Client

const AURABOX_BASE_URL = "https://au.aurabox.cloud";

class AuraboxClient {
  private baseUrl: string;
  private headers: Record<string, string>;

  constructor(apiKey: string) {
    this.baseUrl = AURABOX_BASE_URL;
    this.headers = {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
      Accept: "application/json",
    };
  }

  private async request<T>(
    method: string,
    path: string,
    options?: { body?: unknown; params?: Record<string, unknown> },
  ): Promise<T> {
    let url = `${this.baseUrl}${path}`;
    if (options?.params) {
      const searchParams = new URLSearchParams();
      for (const [key, value] of Object.entries(options.params)) {
        if (value !== undefined && value !== null) {
          searchParams.set(key, String(value));
        }
      }
      const qs = searchParams.toString();
      if (qs) url += `?${qs}`;
    }
    const response = await fetch(url, {
      method,
      headers: this.headers,
      body: options?.body ? JSON.stringify(options.body) : undefined,
    });
    if (!response.ok) {
      throw new Error(`Aurabox API error: ${response.status} ${response.statusText}`);
    }
    if (response.status === 204) return {} as T;
    return response.json();
  }

  // Patients
  listPatients(params?: ListParams) {
    return this.request<PaginatedResponse<Patient>>("GET", "/api/v1/patients", { params });
  }
  getPatient(id: string) {
    return this.request<{ data: Patient }>("GET", `/api/v1/patients/${id}`);
  }
  createPatient(patient: CreatePatient) {
    return this.request<{ data: Patient }>("POST", "/api/v1/patients", { body: patient });
  }
  updatePatient(id: string, fields: Partial<CreatePatient>) {
    return this.request<{ data: Patient }>("PUT", `/api/v1/patients/${id}`, { body: fields });
  }
  deletePatient(id: string) {
    return this.request<void>("DELETE", `/api/v1/patients/${id}`);
  }

  // Cases
  listCases(params?: ListParams) {
    return this.request<PaginatedResponse<Case>>("GET", "/api/v1/cases", { params });
  }
  getCase(id: string) {
    return this.request<{ data: Case }>("GET", `/api/v1/cases/${id}`);
  }
  createCase(caseData: CreateCase) {
    return this.request<{ data: Case }>("POST", "/api/v1/cases", { body: caseData });
  }

  // Studies
  listStudies(patientId: string) {
    return this.request<PaginatedResponse<Study>>("GET",
      `/api/v1/patients/${patientId}/studies`);
  }
  getStudy(patientId: string, studyId: string) {
    return this.request<{ data: Study }>("GET",
      `/api/v1/patients/${patientId}/studies/${studyId}`);
  }
}

// Types
interface Patient {
  id: string;
  given_names: string;
  family_name: string;
  date_of_birth: string;
  sex: "male" | "female" | "other" | "unknown";
  address?: Address;
  status: string;
  archived: boolean;
  created_at: string;
  updated_at: string;
}

interface Case {
  id: string;
  label: string;
  status: "deidentified";
  archived: boolean;
  created_at: string;
  updated_at: string;
}

interface Study {
  id: string;
  [key: string]: unknown; // Study fields vary
}

interface Address {
  street?: string;
  city?: string;
  region?: string;
  postcode?: string;
  country?: string;
}

interface CreatePatient {
  given_names: string;
  family_name: string;
  date_of_birth: string;
  sex: "male" | "female" | "other" | "unknown";
  address?: Address;
}

interface CreateCase {
  label: string;
  sex?: "male" | "female" | "other" | "unknown";
  date_of_birth?: string;
}

interface ListParams {
  per_page?: number;
  search?: string;
  sort?: string;
  direction?: "asc" | "desc";
  archived?: boolean;
}

interface PaginatedResponse<T> {
  data: T[];
  links: { first: string; last: string; prev: string | null; next: string | null };
  meta: { current_page: number; from: number; last_page: number; per_page: number; to: number; total: number };
}

curl

# List patients
curl -s "https://au.aurabox.cloud/api/v1/patients" \
  -H "Authorization: Bearer $AURABOX_API_KEY" \
  -H "Accept: application/json" | jq

# Create a case
curl -s -X POST "https://au.aurabox.cloud/api/v1/cases" \
  -H "Authorization: Bearer $AURABOX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"label": "STUDY-2025-001"}' | jq

# Get studies for a patient
curl -s "https://au.aurabox.cloud/api/v1/patients/{patient_id}/studies" \
  -H "Authorization: Bearer $AURABOX_API_KEY" \
  -H "Accept: application/json" | jq

Error Handling

The API returns standard HTTP status codes:

Code	Meaning
`200`	Success
`201`	Created
`204`	Deleted (no content)
`401`	Unauthorized (bad or missing API key)
`404`	Not found
`422`	Validation error (check response body for details)
`429`	Rate limited
`500`	Server error

Error responses include a message field:

{
  "message": "Not found"
}

Validation errors include field-level detail:

{
  "message": "The given data was invalid.",
  "errors": {
    "given_names": ["The given names field is required."],
    "family_name": ["The family name field is required."]
  }
}

Common Patterns

Iterate All Patients

# Python: paginate through all patients
all_patients = list(client.paginate(client.list_patients))

Search and Filter

# Find active patients named "Smith"
results = client.list_patients(search="Smith", archived=False)

Bulk Case Creation (Research)

# Create cases for a research cohort
import csv

with open("cohort.csv") as f:
    for row in csv.DictReader(f):
        client.create_case(
            label=row["study_id"],
            sex=row.get("sex"),
            date_of_birth=row.get("dob"),
        )

Gotchas

IDs are UUIDs -- not sequential integers. Always use the id field from API responses.
Patient vs Case -- Patients have PII (names, addresses). Cases are de-identified (label only). Use cases for research data.
Studies are nested -- Study endpoints require a patient_id in the URL path. You cannot query studies globally.
Dates must be before today -- The API rejects future dates for date_of_birth.
Country is 2-char ISO -- The address.country field accepts ISO 3166-1 alpha-2 codes only (e.g., au).

Aurabox REST API

Aurabox REST API

What This Skill Does

Prerequisites

Quick Reference

Base URL

Authentication

OpenAPI / Postman

API Surface

Patients

Data Model

Endpoints

List Parameters

Create/Update Fields

Cases (De-identified Patients)

Data Model

Endpoints

List Parameters

Create/Update Fields

Studies

Endpoints

Pagination

Code Examples

Python Client

TypeScript Client

curl

Error Handling

Common Patterns

Iterate All Patients

Search and Filter

Bulk Case Creation (Research)

Gotchas

Resources