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

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	—

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	—

Resources not exposed yet

Planned or internal data not available as HTTP endpoints today.

Affiliations, islands, and ships are part of the broader dataset but do not have public routes in this API yet. When they ship, they will be documented here with the same field-table style.