Docs

API documentation

JSON over HTTP. Each endpoint returns plain objects you can model in any client; the field tables below describe the stable response shape. Where a resource embeds another (e.g. bounties on a character), that is called out explicitly.

Conventions

Shared rules across list endpoints.

Base URL: your deployment origin, or http://localhost:3000 locally.
Pagination: ?page= (1-based, default 1), ?limit= (default 20).
Timestamps: created_at values are ISO 8601 date-time strings (UTC).
Errors: failed requests return JSON { "error": string }. Most server errors return HTTP 500; some detail routes return 404 when an id is missing.

Discovery

Canonical production URLs for routes.

GET /api returns a small map of endpoint URLs (useful for clients and tooling).

{
  "characters": "https://onepieceapi.com/api/characters",
  "devilFruits": "https://onepieceapi.com/api/devil-fruits",
  "bounties": "https://onepieceapi.com/api/bounties",
  "ships": "https://onepieceapi.com/api/ships",
  "islands": "https://onepieceapi.com/api/islands"
}

Localized JSON fields

Some columns are stored as JSON and usually follow a shared shape.

Columns like characters.name, devil_fruits.name, and devil_fruits.model may be null or a localized JSON object. When localized, the convention is:

type CharacterNameJson = {
  en: string
  jp: string
  romaji: string
}

// Example
const name: CharacterNameJson = {
  en: "Monkey D. Luffy",
  jp: "モンキー・D・ルフィ",
  romaji: "Monkī Dī Rufi",
}

Clients typically pick a primary label in priority order en → romaji → jp.

Characters

Paginated characters; each item includes related bounties.

GET /api/characters

Query:

?page= / ?limit= pagination.
?q= searches localized name fields (en, jp, romaji) case-insensitively.
?ageBand= filters numeric age with one of 0-12, 13-17, 18-29, 30-59, 60+. When set, rows with age = null are excluded.

Response: a JSON array of character objects. Each object includes the fields below, plus a bounties array of bounty objects (same shape as GET /api/bounties items).

Character object

Field	Type	Notes
id	string	UUID primary key
created_at	string	ISO 8601 timestamp
name	object \| null	Localized name; see CharacterNameJson when present
age	number \| null	—
birthday	object \| null	Structured birthday payload when present
blood_type	string	—
height	number \| null	—
status	string	—
image_url	string \| null	—
extra_data	object \| null	Free-form extra fields, e.g. origin, epithet, occupation, affiliation, first_appearance

Nested bounties[] items

Field	Type	Notes
id	string	UUID primary key
created_at	string	ISO 8601 timestamp
amount	number \| null	—
character_id	string \| null	FK → characters.id
is_active	boolean	—

Character detail

Fetch a single character by id (includes related bounties).

GET /api/characters/[id]

Response: a single character object (same fields as list items), or 404 when not found.

Bounties

Paginated bounty rows; optional filters and sort order.

GET /api/bounties

Query: ?isActive=true or ?isActive=false filters is_active. If omitted, no filter is applied (returns both active and inactive).

Sort: ?sort=high orders by amount descending (largest first); ?sort=low ascending (smallest first). Omit sort for newest first by created_at.

Response: a JSON array of bounty objects (fields below).

Field	Type	Notes
id	string	UUID primary key
created_at	string	ISO 8601 timestamp
amount	number \| null	—
character_id	string \| null	FK → characters.id
is_active	boolean	—

Devil fruits

Paginated devil fruit resources.

GET /api/devil-fruits

Query: pagination via ?page= / ?limit=.

Response: a JSON array of devil fruit objects (fields below).

Field	Type	Notes
id	string	UUID primary key
created_at	string	ISO 8601 timestamp
name	object \| null	Localized fruit name; CharacterNameJson when present (en, jp, romaji)
model	object \| null	Localized model name; same CharacterNameJson shape when present
type	string \| null	e.g. Paramecia, Zoan, Logia
sub_type	string \| null	—
image_url	string \| null	—

Ships

Paginated ship resources.

GET /api/ships

Query: pagination via ?page= / ?limit=.

Response: a JSON array of ship objects (fields below).

Field	Type	Notes
id	string	UUID primary key
created_at	string	ISO 8601 timestamp
name	object \| null	Localized name; CharacterNameJson shape when present
status	string	e.g. Active, Destroyed, Unknown
type	string \| null	Ship class, when known
image_url	string \| null	—
extra_data	object \| null	Free-form extra fields, e.g. affiliation, first_appearance, length, height

Islands

Paginated island resources.

GET /api/islands

Query: pagination via ?page= / ?limit=.

Response: a JSON array of island objects (fields below).

Field	Type	Notes
id	string	UUID primary key
created_at	string	ISO 8601 timestamp
name	object \| null	Localized name; CharacterNameJson shape when present
sea	string \| null	e.g. East Blue, Paradise, New World, Sky
image_url	string \| null	—
extra_data	object \| null	Free-form extra fields, e.g. affiliation, type, population, first_appearance

Resources not exposed yet

Planned or internal data not available as HTTP endpoints today.

Affiliations are part of the broader dataset but do not have a public route in this API yet. When it ships, it will be documented here with the same field-table style.