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. Copy the key now. It is shown only once.

For this walkthrough, select books:read, account:read and stories:write. Start with a small cap you are comfortable spending. A cap is a ceiling, not a purchase of credits.

Keep the key in an environment variable named ALLOGLOT_API_KEY. Use a secret manager in a deployed service. Never put it in frontend code or a public repository.

2. List your books with curl

curl --fail-with-body 'https://app.alloglot.com/api/v1/books?limit=20' \
  -H "Authorization: Bearer $ALLOGLOT_API_KEY"

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

3. Quote, then 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.

curl --fail-with-body 'https://app.alloglot.com/api/v1/stories/quote' \
  -H "Authorization: Bearer $ALLOGLOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"lang":"es","difficulty":2,"length":"short","audiobook":false}'

This text-only example quotes 13 credits. The response separates writing, audiobook and total credits, and includes your balance. An audiobook request defaults to true if you omit it. The full known price is reserved against your key cap before work starts.

curl --fail-with-body 'https://app.alloglot.com/api/v1/stories' \
  -H "Authorization: Bearer $ALLOGLOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"topic":"A lost cat finds its way home","lang":"es","difficulty":2,"length":"short","audiobook":false,"visibility":"public"}'

Creation returns HTTP 202 with an id and status writing. Public visibility makes the example compatible with Free, but your saved Spanish level must also allow level 2. Paid readers can choose private.

The same calls with JavaScript

Run this on your server or in Node.js with ALLOGLOT_API_KEY set. It creates a real story and spends credits when writing succeeds.

const base = 'https://app.alloglot.com/api/v1';
const key = process.env.ALLOGLOT_API_KEY;
if (!key) throw new Error('Set ALLOGLOT_API_KEY first');
async function call(path, body) {
  const response = await fetch(base + path, {
    method: body ? 'POST' : 'GET',
    headers: {
      Authorization: `Bearer ${key}`,
      ...(body ? { 'Content-Type': 'application/json' } : {}),
    },
    ...(body ? { body: JSON.stringify(body) } : {}),
  });
  const result = await response.json();
  if (!response.ok) {
    throw new Error(`${response.status}: ${result.code ?? 'error'}: ${result.error}`);
  }
  return result;
}
console.log(await call('/books?limit=20'));
const settings = {
  lang: 'es', difficulty: 2, length: 'short', audiobook: false,
};
const quote = await call('/stories/quote', settings);
console.log('Credits:', quote.credits);
// Review the quote before running the creation below.
const story = await call('/stories', {
  ...settings, topic: 'A lost cat finds its way home', visibility: 'public',
});
console.log(story.id, story.status);

Follow the story

Keep the returned ID. Call GET /api/v1/stories/{id} 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. A quote spends nothing and does not reserve a price or guarantee your plan permits creation.

Do not automatically repeat a create request after a timeout. It may already have started. See safe retries.