Saga20 LogoSaga20Developers
Quickstart

Get started

Quickstart

Create a campaign key in Settings, make your first request and use the returned cursor to read the next page.

You need a campaign of your own and somewhere to run curl. A shell on your own machine or a server works for every example.

1. Create a key

  1. Open the campaign you plan to connect.
  2. Pick the campaign name in the sidebar, then open Settings.
  3. Choose API and look for the campaign name under Public API.
  4. Select Generate key.
  5. Next to Key, use Copy key to keep the whole key in a private spot.

The full key shows up one time only. Copy it before you leave the page. Regenerate swaps it out and halts the old key right away.

Managing the key is reserved for the campaign owner. For the Settings steps, see Create and manage a Public API key.

Point SAGA20_API_KEY at the full key you copied. Swap out the placeholder below before you run any request.

Save the key
export SAGA20_API_KEY='paste-your-full-key-here'

2. Make your first request

GET/api/public/v1/sessions

To request a single session, use limit=1. The example campaign holds another public session, which is why the response carries a cursor.

When data comes back empty, check whether some session in this campaign has public visibility. In the case of a 401, compare the full key and the bearer header with authentication.

Request
curl "https://app.saga20.com/api/public/v1/sessions?limit=1" \
  -H "Authorization: Bearer $SAGA20_API_KEY"
Response
{
  "data": [
    {
      "id": "7b1e3f0a-52c4-4d1e-9a2b-3c8f6d1a9e41",
      "title": "The Broken Gate",
      "status": "completed",
      "recording_date": "2026-09-24T00:00:00+00:00",
      "created_at": "2026-09-24T19:12:45+00:00",
      "updated_at": "2026-09-25T08:03:10+00:00",
      "session_type": "audio",
      "visibility": "public"
    }
  ],
  "pagination": {
    "next_cursor": "eyJvZmZzZXQiOjF9",
    "has_more": true
  }
}

3. Read the next page

Drop pagination.next_cursor from your response into the following request to that same endpoint. Leave the page size unchanged. The request below uses the example cursor.

Keep going as long as pagination.has_more is true. Stop once it reads false and next_cursor is null.

Next request
curl "https://app.saga20.com/api/public/v1/sessions?limit=1&cursor=eyJvZmZzZXQiOjF9" \
  -H "Authorization: Bearer $SAGA20_API_KEY"
Last page
{
  "data": [
    {
      "id": "0c9d2e77-1b3a-4f56-8e0d-92a4b7c5d318",
      "title": "Ashes at Greywatch",
      "status": "completed",
      "recording_date": "2026-09-17T00:00:00+00:00",
      "created_at": "2026-09-17T20:30:02+00:00",
      "updated_at": "2026-09-18T07:41:55+00:00",
      "session_type": "audio",
      "visibility": "public"
    }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false
  }
}

Read a summary or world entry

Take an id from a list response to fetch one record. Sessions explains how to read a summary, while endpoints names the world entry paths.

Before you build a request loop for larger imports, go read pagination and rate limits.