Skip to main content
GET
/
v1
/
characters
List characters
curl --request GET \
  --url https://api.aurous-labs.com/v1/characters \
  --header 'X-Api-Key: <api-key>'
{
  "object": "list",
  "data": [
    {
      "id": "char_01HXMQ7Z3K8Y2NABCDEFGHJKMR",
      "object": "character",
      "name": "Aurora the Adventurer",
      "status": "ready",
      "refs": [
        {
          "pose": "front",
          "url": "https://api.aurous-labs.com/storage/.../front.bin?token=…"
        }
      ],
      "created_at": "2026-05-08T10:00:00Z",
      "updated_at": "2026-05-08T10:00:00Z",
      "client_reference_id": "bot_8472",
      "attributes": {
        "gender": "female",
        "age": 28,
        "ethnicity": "east-asian",
        "hair_color": "black",
        "hair_style": "shoulder-length straight",
        "eye_color": "brown",
        "body_type": "athletic",
        "additional_details": "small scar above right eyebrow; warm smile"
      },
      "error_message": null,
      "aurous_version": "2026-05-15"
    }
  ],
  "has_more": true,
  "next_cursor": "img_01HXMQ7Z3K8Y2ABCDEFGHJKM"
}
GET /v1/characters returns a cursor-paginated list of your team’s characters, ordered by created_at descending. Soft-deleted characters are excluded.

​
When to use

  • Powering a “pick a character” UI in your own product.
  • Auditing which characters are still in synthesizing / reviewing and need attention.
  • Bulk-syncing the catalog into your local database.

​
Pagination

Pass limit (1–100, default 20) and starting_after (the next_cursor value from the previous response, which is the id of the last character returned). Stop when next_cursor is null. The cursor convention is consistent across every paginated V1 endpoint — starting_after to advance, next_cursor to receive the next anchor.

​
Examples

# First page
curl "https://api.aurous-labs.com/v1/characters?limit=20" \
  -H "X-Api-Key: $AUROUS_API_KEY"

# Subsequent pages — `starting_after` is the `id` of the last character
# returned (also surfaced as `next_cursor` on the previous response).
curl "https://api.aurous-labs.com/v1/characters?limit=20&starting_after=char_01HXMQ7Z3K8Y2ABCDEFGHJKM" \
  -H "X-Api-Key: $AUROUS_API_KEY"

​
Limits

  • Rate limit: bucket characters_get — 120 requests/min sustained, 240 burst per team.

​
Common pitfalls

  • The list does not include deleted characters. To enumerate everything for an audit, you need to track deletions out-of-band — deletes are soft and the character stays for IDs to remain valid forever, but the list endpoint hides them.
  • next_cursor is the last returned character’s id (the opaque char_<ulid>). Pass it back as starting_after on the next request — don’t synthesize cursors yourself.
  • The fields returned per character are the same as GET /v1/characters/{id} (no shrunk “summary” shape); pages are bounded by limit, not by payload size.

Authorizations

​
X-Api-Key
string
header
required

Your team API key (starts with al_live_).

Headers

​
Aurous-Version
string

Optional API version pin (YYYY-MM-DD). Defaults to your team's pinned version, or the system default 2026-05-15 for unauthenticated requests.

Pattern: ^\d{4}-\d{2}-\d{2}$
Example:

"2026-05-15"

Query Parameters

​
limit
number

Items per page (1-100, default 20)

Example:

20

​
starting_after
string

Cursor — opaque char_<ulid> from a prior page

Example:

"char_01HXMQ7Z3K8Y2NABCDEFGHJKMR"

​
status
enum<string>

Filter to a single lifecycle state. Omit to list all (non-deleted) states. An unrecognized value returns 400 invalid_request. Note: cancelled is NOT a filterable status — a cancelled character is hard-deleted and never appears in list/get; it surfaces only as the character.cancelled webhook.

Available options:
synthesizing,
reviewing,
ready,
failed,
deleted

Response

Cursor-paginated list of characters

​
object
enum<string>
required

Discriminator

Available options:
list
Example:

"list"

​
data
object[]
required

Array of CharacterResponse items

​
has_more
boolean
required

True when the next page exists

Example:

true

​
next_cursor
object

Pass as ?starting_after= on the next request. null when has_more is false.

Example:

"img_01HXMQ7Z3K8Y2ABCDEFGHJKM"