Castaways

API Reference

The Character API is organized around REST. Our API returns JSON-encoded responses and uses standard HTTP response codes to indicate success or failure.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests do not require an API key or authentication.

Castaways encourages you to build awesome experiences, so you can use the API for free. We cache all responses for 300 seconds to prevent abuse.

Base URL

https://character-api.castaways.com

Content Type

Content-Type: application/json

Need help?

Join our Discord community for support, updates, and to connect with other developers.

Join the Discord

Characters

Characters are at the heart of Castaways. Each character has been carefully crafted with unique personalities, backstories, and traits that make them come alive in your applications.

We encourage developers to use these characters creatively, whether you're building fan sites, games, or interactive experiences. Our API provides comprehensive access to character data, making it easy to integrate these beloved characters into your projects.

All character data is available through our REST API endpoints, with responses formatted in JSON for easy integration with any platform or programming language.

ENDPOINTS

GET /v1/characters
GET /v1/characters/:name
GET /v1/characters/:id

The Character Object

Properties

id string

External unique identifier for the character. This can be used to identify the character in other API endpoints.

uuid string

Internal UUID string for the character. This can be used to request character images from the Character Assets CDN.

name string

The character's public display name.

description string

The character's description. This is meant to be displayable to users.

attributes array of objects

The character's traits. These are all of the possible traits for any character.

Attributes are always returned in the order shown above.

reveal_at timestamp

When the character became publicly available.

created_at timestamp

When the character was created.

updated_at timestamp

When the character was last updated.

avatar_image string

URL to the character's avatar image.

full_body_image string

URL to the character's full body image.

The Character Object

{
  "id": 1,
  "uuid": "390c53cb-dbad-4e21-929f-3f842826db17",
  "name": "Ooga",
  "description": "A strong but sluggish nomad...",
  "attributes": [
    {"value": "Male", "trait_type": "Gender"},
    {"value": "Unknown", "trait_type": "Hometown"},
    {"value": "10,000 B.C.", "trait_type": "Birthday"},
    {"value": "Taurus", "trait_type": "Zodiac"},
    {"value": "#f2ba66", "trait_type": "Favorite Color"},
    {"value": "Strength", "trait_type": "Aspiration"},
    {"value": "Lazy", "trait_type": "Personality"},
    {"value": "Aloof", "trait_type": "Personality"},
    {"value": "Clumsy", "trait_type": "Personality"}
  ],
  "reveal_at": "2025-02-20T08:00:00.000Z",
  "created_at": "2025-02-20T22:07:24.252Z",
  "updated_at": "2025-02-22T09:15:36.622Z",
  "avatar_image": "https://character-assets.castaways.com/2d/390c53cb-dbad-4e21-929f-3f842826db17/avatar.jpg",
  "full_body_image": "https://character-assets.castaways.com/2d/390c53cb-dbad-4e21-929f-3f842826db17/full_body.jpg"
}

Get All Characters

Parameters

This endpoint has no parameters.

Example:

GET /v1/characters

Returns

An array of character objects for all available characters.

Endpoint

GET /v1/characters

RESPONSE

{
  "1": {
    "id": 1,
    "uuid": "390c53cb-dbad-4e21-929f-3f842826db17",
    "name": "Ooga",
    "description": "A strong but sluggish nomad...",
    "attributes": [
      {"value": "Male", "trait_type": "Gender"},
      {"value": "Unknown", "trait_type": "Hometown"},
      {"value": "10,000 B.C.", "trait_type": "Birthday"},
      {"value": "Taurus", "trait_type": "Zodiac"},
      {"value": "#f2ba66", "trait_type": "Favorite Color"},
      {"value": "Strength", "trait_type": "Aspiration"},
      {"value": "Lazy", "trait_type": "Personality"},
      {"value": "Aloof", "trait_type": "Personality"},
      {"value": "Clumsy", "trait_type": "Personality"}
    ],
    "reveal_at": "2025-02-20T08:00:00.000Z",
    "created_at": "2025-02-20T22:07:24.252Z",
    "updated_at": "2025-02-22T09:15:36.622Z",
    "avatar_image": "https://character-assets.castaways.com/2d/390c53cb-dbad-4e21-929f-3f842826db17/avatar.jpg",
    "full_body_image": "https://character-assets.castaways.com/2d/390c53cb-dbad-4e21-929f-3f842826db17/full_body.jpg"
  },
  "2": {
    "id": 2,
    "uuid": "9d5078c2-8959-4bf3-9d35-9ebf2d0bb6ff",
    "name": "Buuga",
    "description": "A spirited adventurer...",
    "attributes": [
      {"value": "Female", "trait_type": "Gender"},
      {"value": "Unknown", "trait_type": "Hometown"},
      {"value": "10,000 B.C.", "trait_type": "Birthday"},
      {"value": "Sagittarius", "trait_type": "Zodiac"},
      {"value": "#7fdedd", "trait_type": "Favorite Color"},
      {"value": "Adventure", "trait_type": "Aspiration"},
      {"value": "Aloof", "trait_type": "Personality"},
      {"value": "Good", "trait_type": "Personality"},
      {"value": "Smug", "trait_type": "Personality"}
    ],
    "reveal_at": "2025-02-21T08:00:00.000Z",
    "created_at": "2025-02-21T01:52:44.577Z",
    "updated_at": "2025-02-21T01:52:44.577Z",
    "avatar_image": "https://character-assets.castaways.com/2d/9d5078c2-8959-4bf3-9d35-9ebf2d0bb6ff/avatar.jpg",
    "full_body_image": "https://character-assets.castaways.com/2d/9d5078c2-8959-4bf3-9d35-9ebf2d0bb6ff/full_body.jpg"
  }
  // Additional characters...
}

Get Character by Name

Parameters

name string

Only return the character with the exact name provided. If a character's name contains a space, it must be replaced with a dash (-).

Example:

GET /v1/characters/ooga

Returns

The character object for the character with the exact name provided.

Endpoint

GET /v1/characters/:name

RESPONSE

{
  "id": 1,
  "uuid": "390c53cb-dbad-4e21-929f-3f842826db17",
  "name": "Ooga",
  "description": "A strong but sluggish nomad...",
  "attributes": [
    {"value": "Male", "trait_type": "Gender"},
    {"value": "Unknown", "trait_type": "Hometown"},
    {"value": "10,000 B.C.", "trait_type": "Birthday"},
    {"value": "Taurus", "trait_type": "Zodiac"},
    {"value": "#f2ba66", "trait_type": "Favorite Color"},
    {"value": "Strength", "trait_type": "Aspiration"},
    {"value": "Lazy", "trait_type": "Personality"},
    {"value": "Aloof", "trait_type": "Personality"},
    {"value": "Clumsy", "trait_type": "Personality"}
  ],
  "reveal_at": "2025-02-20T08:00:00.000Z",
  "created_at": "2025-02-20T22:07:24.252Z",
  "updated_at": "2025-02-22T09:15:36.622Z",
  "avatar_image": "https://character-assets.castaways.com/2d/390c53cb-dbad-4e21-929f-3f842826db17/avatar.jpg",
  "full_body_image": "https://character-assets.castaways.com/2d/390c53cb-dbad-4e21-929f-3f842826db17/full_body.jpg"
}

Get Character by ID

Parameters

id integer

Only return the character with the exact ID provided.

Example:

GET /v1/characters/2

Returns

The character object for the character with the exact ID provided.

Endpoint

GET /v1/characters/:id

RESPONSE

{
  "id": 2,
  "uuid": "9d5078c2-8959-4bf3-9d35-9ebf2d0bb6ff",
  "name": "Buuga",
  "description": "A spirited adventurer...",
  "attributes": [
    {"value": "Female", "trait_type": "Gender"},
    {"value": "Unknown", "trait_type": "Hometown"},
    {"value": "10,000 B.C.", "trait_type": "Birthday"},
    {"value": "Sagittarius", "trait_type": "Zodiac"},
    {"value": "#7fdedd", "trait_type": "Favorite Color"},
    {"value": "Adventure", "trait_type": "Aspiration"},
    {"value": "Aloof", "trait_type": "Personality"},
    {"value": "Good", "trait_type": "Personality"},
    {"value": "Smug", "trait_type": "Personality"}
  ],
  "reveal_at": "2025-02-21T08:00:00.000Z",
  "created_at": "2025-02-21T01:52:44.577Z",
  "updated_at": "2025-02-21T01:52:44.577Z",
  "avatar_image": "https://character-assets.castaways.com/2d/9d5078c2-8959-4bf3-9d35-9ebf2d0bb6ff/avatar.jpg",
  "full_body_image": "https://character-assets.castaways.com/2d/9d5078c2-8959-4bf3-9d35-9ebf2d0bb6ff/full_body.jpg"
}