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 DiscordCharacters
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"
}