Austi Classics Pro API

Overview

The API currently provides read-only access to:

• the Austi Classics catalogue;
• canonical navigation structures for plays and prose;
• canonical text and stable text-node identifiers;
• published annotation sets; and
• filtered and paginated annotations.

Base URL

https://austi-classics-pro-next-api-production.up.railway.app

Authentication

Every /api/v1 request requires an API key. Send the key in the X-API-Key request header:

X-API-Key: YOUR_API_KEY

Quick start

cURL

curl "https://austi-classics-pro-next-api-production.up.railway.app/api/v1/books" \
  -H "X-API-Key: YOUR_API_KEY"

PowerShell

$headers = @{
    "X-API-Key" = "YOUR_API_KEY"
}

$response = Invoke-RestMethod `
    -Uri "https://austi-classics-pro-next-api-production.up.railway.app/api/v1/books" `
    -Headers $headers

$response | ConvertTo-Json -Depth 10

Server-side JavaScript

const response = await fetch(
  "https://austi-classics-pro-next-api-production.up.railway.app/api/v1/books",
  {
    headers: {
      "X-API-Key": process.env.AUSTI_API_KEY
    }
  }
);

if (!response.ok) {
  throw new Error(
    "Austi API request failed: " + response.status
  );
}

const result = await response.json();

Supported endpoints

For complete parameter definitions, response schemas, and interactive testing, visit the interactive API reference.

Typical workflow

1. Call /api/v1/books to discover a book and its book_id.
2. Call /api/v1/books/{book_id}/navigation to obtain canonical node identifiers.
3. Call /api/v1/text/{node_id} to retrieve canonical text.
4. Call /api/v1/books/{book_id}/annotation-sets to discover published annotation sources.
5. Call /api/v1/annotations to retrieve annotations for the book, annotation set, or canonical target.

Annotation queries

The annotations endpoint requires a book_id and supports optional filtering and pagination:

Examples

GET /api/v1/annotations?book_id=macbeth

GET /api/v1/annotations?book_id=macbeth&annotation_set_id=hudson_1880

GET /api/v1/annotations?book_id=macbeth&target_id=macbeth_a1_s3_p003_s001

GET /api/v1/annotations?book_id=macbeth&limit=10&offset=10

Annotation responses include a pagination object containing total, limit, offset, and returned.

Search canonical text

Use /api/v1/search to find matching sentences across the Austi catalogue. Search is case-insensitive but otherwise literal, so punctuation within a phrase remains significant.

Examples

GET /api/v1/search?q=spot&book_id=macbeth

GET /api/v1/search?q=ambition&book_id=macbeth

GET /api/v1/search?q=ambition&book_id=macbeth&character_id=macbeth_char_008

GET /api/v1/search?q=love&limit=10&offset=0

Each result includes the matching sentence, its stable node_id, character identifier, line number, and canonical act, scene, chapter, and paragraph location where applicable.

Rate limit

Each API key may make up to 60 requests within a rolling 60-second window. The limit is shared across all /api/v1 endpoints for that key.

Requests over the limit receive HTTP 429 Too Many Requests:

{
  "detail": "Rate limit exceeded: maximum 60 requests per 60 seconds"
}

Errors

Errors normally use the following JSON shape:

{
  "detail": "Error description"
}

Reference integration

See how an application can retrieve canonical Macbeth text and published annotations through the Austi Classics Pro API.

Request API access

API access is currently available to approved developers and services. Please tell us briefly about your project, its intended audience, and how you expect to use Austi content.

Never send passwords, existing API keys, or other credentials by email or through the contact form.