API Documentation

Everything returns JSON. CORS is on. Base URL:

The full specification is available as an OpenAPI document.

Authentication

No key needed to start. You get 30 requests per minute immediately. For higher limits, pass your Usage or Pro key in the X-API-Key header:

With a Usage or Pro key:

Rate Limits

Free requests are capped per IP. Usage and Pro keys are capped per key. Hit the limit and you'll get a 429 with a Retry-After header.

Deleted content

When an artist removes their work, the API marks the post "deleted": true and returns a null source URL. Tags and metadata stay available. The /search endpoint excludes deleted posts; /post returns them by ID. Thumbnails are removed for deleted posts; the /thumb endpoint returns 404.

Endpoints

GET /api/v1/search

Find posts by natural language, text, tag, artist, or platform. Combine parameters to narrow results.

At least one of nl, q, tag, artist, since, or color is required.

Choosing your search approach

The search endpoint offers three ways to query, depending on where the input comes from and how much control you need.

nl: Natural language. Use when the input comes from a human typing freeform text. The API parses platform, artist, dates, tags, rating, sort, and exclusions out of the text. Multi-word phrases that match known tags (like "white hair" or "dark skin") are resolved to exact tag filters. Anything left becomes a full-text search. Best for: search bars, chatbot commands, user-facing input where you don't want to build your own parser.

q: Full-text search. Use when you want direct control over what gets searched against post titles, descriptions, and indexed content. No parsing, no extraction. The string goes straight to the search engine. Supports PostgreSQL websearch_to_tsquery syntax: quoted phrases for exact match, OR for alternatives, -word to exclude. Best for: programmatic queries where you've already parsed the input yourself, or when you want to combine structured params with a specific text search.

Explicit parameters: tag, artist, platform, from, to, sfw, rating. Use when you have structured UI controls (dropdowns, date pickers, checkboxes, tag selectors) and know exactly what each filter is. Best for: filter panels, faceted search, data pipelines, automated queries.

Combining them. All three compose. Explicit parameters override anything the NL parser extracts for the same field. This lets you have a search bar (nl) alongside structured controls (checkboxes, dropdowns) that always take priority.

Content rating tags

Every post carries a rating tag that classifies the source artwork. The API returns this as a text tag in the JSON response alongside all other tags. Lagoon serves structured metadata and scaled thumbnails for identification purposes. Full-resolution artwork is not hosted or transmitted.

SFW filtering is on by default. All queries return only general and sensitive content unless you opt out:

Use-case examples

Gallery app with tag browsing. Your app shows a grid of art filtered by tag with pagination. SFW filtering is on by default.

Discord bot search command. Users type /search touhou on twitter newest. Pass their input directly to nl. The parsed filters in the response tell you what was extracted, which you can show back to the user.

Monitoring an artist for new posts. Check for new work by a specific artist on a specific platform since a given date. Run this on a schedule to alert when new posts appear.

Index monitoring with since. Track newly indexed content by ingestion time. Unlike from/to (which filter by publication date), since filters by when the post was added to the index. Use this to build feeds or detect new content without fragile offset tracking.

Search bar with structured controls. Your UI has a text input, a platform dropdown, and an SFW checkbox. The text input feeds nl, the dropdown feeds platform, and the checkbox feeds sfw. Explicit params override anything the NL parser finds.

Date-bounded data export. Pull all posts matching a tag within a date range. Page through the full result set.

Browsing an artist's full portfolio. First look up the artist to see all their linked accounts, then search for their posts.

Faceted search for filter panels. Pass facets=1 to get the total result count and breakdowns by platform and rating. Use this to build filter UIs with accurate counts.

Color palette search. Filter posts by dominant colors in their extracted palette. Combine with other filters to find art with specific color schemes.

Full-text search with OR and exclusion. Use q directly when you need PostgreSQL search syntax that the NL parser doesn't handle.

Parameter precedence

When nl is combined with explicit parameters, the explicit parameter always wins for the same field:

Pagination

Use limit and offset to page through results. The response count tells you how many results were returned in this page. To get the next page, add the current limit to the current offset. When count is less than limit, you've reached the last page.

Example response:

width and height are the original image dimensions in pixels (null when not available from the source platform; ~99.8% coverage). palette is an array of up to 6 dominant hex colors extracted from the image, ordered roughly by dominance (null when not available; ~79% coverage).

When facets=1 is passed, the response includes a facets object with the total unpaginated count and breakdowns by platform and content rating:

Natural language search

The nl parameter accepts plain English queries. The API parses your text into structured filters, runs the search, and returns both the results and the filters it extracted so you can see exactly how the query was interpreted.

The parser recognizes:

Filler words like "show me", "find", "art", "posts", "please" are stripped automatically. Multi-word phrases left after parsing are matched against known tags and converted to exact tag filters when found (e.g. "dark skin" resolves to the dark_skin tag). Any remaining text becomes the full-text search query (q).

When nl is used, the response includes a filters key showing what was extracted:

More NL examples:

GET /api/v1/random

Return random posts from the index. Accepts the same filters as /search (tag, platform, artist, date range, rating, NL) to narrow the pool before sampling. No required parameters.

Example requests:

Response format is identical to /search, with each result including tags and description_long. When nl is used, the response includes a filters key showing what was extracted.

GET /api/v1/artist

Query a handle and get back every linked account across platforms. Use this to build profile pages, cross-reference artists, or verify that two handles belong to the same person.

When to use this vs. /search?artist=: This endpoint returns the artist's profile (linked accounts, post count). The artist param on /search returns the artist's posts. Use this first to confirm you have the right artist, then search their posts.

Example request:

Example response:

Use-case: disambiguating a Pixiv artist by their numeric ID.

GET /api/v1/post

Get full metadata for a single post by ID: tags, extended description, artist profile, and source link. Use this when you already have a post ID from a search result and want the complete data (search results include core fields; this endpoint adds description_long and artist_profile).

Example request:

Example response:

GET /api/v1/tags

Search the tag index by name. Use this to discover available tags, build tag autocomplete, or check tag post counts before searching. Returns matching tags sorted by category priority (character, copyright, then general) and by post count within each category.

Tags are categorized as character, copyright, species, rating, or general. Use this to find the exact normalized tag name before passing it to /search?tag=.

Example: building a tag autocomplete. User types "gen" into your search field, you query the tag index to show suggestions.

Example response:

Then use the tag name in a search:

GET /api/v1/stats

Returns index-wide statistics: total posts, artists, tags, and a per-platform breakdown of searchable post counts. No parameters required.

Use this to check data coverage before integrating, display index size in your UI, or verify which platforms are tracked.

Example request:

Example response:

GET /api/v1/co-occurrence Analytics

Tag co-occurrence data. Returns tags that frequently appear alongside a given tag, with counts and Jaccard similarity scores. Requires an API key (not available on the free tier). Billed at the analytics rate: 10 mills per call ($10/1,000 requests).

Example request:

Example response:

GET /api/v1/trending Analytics

Tags that are appearing disproportionately often in recently indexed posts compared to their historical rate. The trend score is the ratio of observed frequency to expected frequency: a score of 10 means the tag appeared 10x more than its baseline rate in the window. Requires an API key (not available on the free tier). Billed at the analytics rate: 10 mills per call ($10/1,000 requests).

Example request:

Example response:

Filter to specific tag categories to focus on what matters:

GET /api/v1/batch-similar Compute

Pairwise cosine similarity matrix for a set of post IDs. Returns all pairs above a similarity threshold. Requires an API key (not available on the free tier). Billed per input post ID: 10 mills each. N=50 posts costs 500 mills ($0.50).

Response

Pairs are sorted by similarity descending. Duplicate IDs in the input are deduplicated. Each unique pair appears once (id_a < id_b).

GET /api/v1/similar

Find semantically similar posts using vector embeddings. Two modes: pass a post ID to find posts similar to it, or pass a text query to find posts matching a description. All filters from /search (platform, artist, SFW, rating) compose with similarity.

At least one of id or q is required.

How it works

Every post has a vector embedding derived from its tags and metadata. The endpoint ranks results by cosine similarity (0 to 1, where 1 is identical), then applies any filters you specify.

When using q, your text is encoded at request time. Describe what you're looking for in plain language and get results ranked by semantic relevance, not keyword overlap.

Similar by ID

Find posts similar to one you already have:

Semantic text search

Describe what you're looking for. Unlike /search?q= (which matches keywords in titles and descriptions), this matches against the semantic content of posts:

When to use /similar vs. /search

Example response:

The similarity field ranges from 0 to 1. Values above 0.8 indicate strong similarity; values above 0.9 typically mean the posts share most of the same tags and subject matter.

GET /api/v1/similar-artists Analytics

Find artists with a similar visual style. Each artist in the index has a pre-computed style vector derived from their body of work. Pass an artist handle to find stylistically similar artists, or a post ID to find artists whose overall style matches that post. Requires an API key (not available on the free tier). Billed at the analytics rate: 10 mills per call ($10/1,000 requests).

Similar artists by handle

Similar artists by post

Response

When searching by handle, the source artist and all their linked handles are excluded from results. When searching by post ID, no artist is excluded.

GET /api/v1/thumb

Returns a scaled thumbnail image for a post. The response is a WebP image (max 360px on the longest side), not JSON. Errors are still returned as JSON.

Thumbnail requests do not require an API key and do not count toward API rate limits or usage billing. They have a separate IP-based limit of 300 per minute.

Every post object returned by /search, /post, /similar, and /random includes a thumb_url field pointing to this endpoint.

Responses include Cache-Control: public, max-age=86400 and Last-Modified headers. Conditional requests with If-Modified-Since return 304 when the thumbnail has not changed.

Returns 404 for posts that do not exist, have been removed at source, or have no cached thumbnail.

Example:

Errors

Every error returns "ok": false with an "error" message. Standard HTTP codes:

• 400 - Missing or invalid parameters
• 401 - Bad or expired API key
• 402 - Insufficient balance (Usage tier, balance is zero)
• 404 - Not found
• 429 - Rate limit hit (check Retry-After header)
• 500 - Server error

Example error response:

CORS

Every endpoint allows * origins and responds to OPTIONS preflight, so you can call from the browser without a proxy.