Your first API call

1. Make a key

Open Settings → API keys in an early-access account. Name the integration, select scopes and choose a monthly credit cap. The key is shown once. For this first read, select only books:read and cap 0.

Keep the key in a server environment variable named ALLOGLOT_API_KEY. Use a secret manager in a deployed service. Never put it in frontend code or a public repository. The examples use production by default. ALLOGLOT_API_BASE can point to your own test server. Do not send a production key to an untrusted server.

2. List your books

The following examples make the same read with curl, TypeScript or Python. Each is standalone. TypeScript runs as an .mts file with Node.js 24 or later. Python uses only its standard library.

curl

curl --fail-with-body "${ALLOGLOT_API_BASE:-https://app.alloglot.com/api/v1}/books?limit=20" \
  -H "Authorization: Bearer ${ALLOGLOT_API_KEY:?Set ALLOGLOT_API_KEY in your server environment}"

TypeScript

// Run as a server-side .mts file with Node.js 24+.
const base = process.env.ALLOGLOT_API_BASE ?? 'https://app.alloglot.com/api/v1';
const key = process.env.ALLOGLOT_API_KEY;
if (!key) throw new Error('Set ALLOGLOT_API_KEY');
const headers: Record<string, string> = { Authorization: `Bearer ${key}` };
const response = await fetch(base + `/books?limit=20`, {
  method: 'GET', headers, redirect: 'error',
});
const result = await response.json();
if (!response.ok) {
  throw new Error(`${response.status}: ${result.code}: ${result.error}`);
}
console.log(result);

Python

# Python 3, standard library only. Run on your server.
import json
import os
from urllib.request import Request, urlopen
from urllib.error import HTTPError
from urllib.parse import quote

base = os.environ.get('ALLOGLOT_API_BASE', 'https://app.alloglot.com/api/v1')
key = os.environ['ALLOGLOT_API_KEY']
headers = {'Authorization': f'Bearer {key}'}
data = None
request = Request(base + f'/books?limit=20', data=data, headers=headers, method='GET')
try:
    with urlopen(request, timeout=30) as response:
        print(json.load(response))
except HTTPError as error:
    # No automatic retry, especially for paid creation.
    print(error.code, error.read().decode('utf-8'))
    raise

The response has books and next. An empty shelf returns books: []. Pass next as the URL-encoded before query parameter for the next page. next: null means you are done. The maximum page size is 100.

3. Quote, then choose whether to create

List, export, balance, levels and quote calls cost 0 credits. Writing costs 13 credits for short, 30 for medium and 55 for long. Audiobook prices depend on language and your saved book settings. Always quote the same settings you will create.

For a quote, use a separate key with account:read. The quote examples request a short Spanish story at level 2 with audiobook: false. The response separates writing, audiobook and total credits, and includes your balance. A quote spends nothing and does not reserve a price or guarantee your plan permits creation.

Only after reviewing the quote, make a separate stories:write key with a deliberate spending cap and use the creation examples. That POST starts real writing. Public visibility makes the example compatible with Free, but your saved Spanish level must allow level 2. Paid readers can choose private. An omitted audiobook defaults to true. The full known price is reserved against the cap before work starts.

Creation returns HTTP 202 with an id and status writing. Keep that ID. Never automatically repeat the POST after a timeout. Check the app for existing work first.

4. Follow the story

Use a books:read key and the status examples about every 20 seconds while work is in progress. With audiobook: false, stop at ready. With audiobook: true, status reads start the requested audiobook once writing finishes. Stop at done and open book.url. Also stop at failed or canceled and show the error.

The writing charge appears once writing succeeds. An audiobook is charged when it starts. Failed writing releases its reservation, and refunded books stop counting against the cap. See safe retries and Your data and connected agents.