API Documentation

Everything returns JSON. CORS is on. Base URL:

https://lagoon.io/api/v1

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:

curl "https://lagoon.io/api/v1/search?q=example"

With a Usage or Pro key:

curl \
  -H "X-API-Key: YOUR_KEY" \
  "https://lagoon.io/api/v1/search?q=example"

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.

Tier	Rate	Price	Scope
Free	30 / min	$0	Per IP
Usage	120 / min	$2 / 1k requests	Per key
Pro	300 / min	$25 / month	Per key

Deleted content

When an artist removes their work, the API marks the post "deleted": true and redacts the source URL. Tags and metadata stay available, so you keep the reference even after the original is gone. Deleted posts don't appear in search results but can be fetched directly by ID via /post.

Endpoints

GET /api/v1/search

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

Parameter	Type	Description
q	string	Full-text search query
tag	string	Exact tag match (normalized form, e.g. `genshin_impact`)
artist	string	Artist handle or display name (case-insensitive)
platform	string	Platform slug: `x`, `pixiv`, `bluesky`, `deviantart`, `newgrounds`, `tumblr`, etc.
limit	integer	Results per page, 1-100 (default: 50)
offset	integer	Pagination offset (default: 0)

At least one of q, tag, or artist is required. platform is a filter, not a standalone query.

Example request:

curl \
  -H "Accept: application/json" \
  "https://lagoon.io/api/v1/search?tag=genshin_impact&limit=1"

Example response:

{
  "ok": true,
  "count": 2,
  "offset": 0,
  "results": [
    {
      "id": 184201,
      "source_url": "https://x.com/artist/status/...",
      "title": "character name (series)",
      "posted_at": "2024-11-15 08:30:00+00",
      "platform": "x",
      "platform_name": "X (Twitter)",
      "artist_handle": "artist_name",
      "artist_name": "Artist Name",
      "deleted": false,
      "tags": [
        "character:name",
        "copyright:series",
        "blue hair",
        "sword",
        "rating:general"
      ]
    }
  ]
}

GET /api/v1/artist

Query a handle and get back every linked account across platforms.

Parameter	Type	Description
handle required	string	Artist handle to look up (must be the platform-specific handle when `platform` is set)
platform	string	Match handle against a specific platform (e.g. Pixiv numeric ID, not the artist's X handle)

Example request:

curl "https://lagoon.io/api/v1/artist?handle=hews__"

Example response:

{
  "ok": true,
  "artist": {
    "handle": "artist_name",
    "display_name": "Artist Name",
    "post_count": 47,
    "platforms": [
      {
        "platform": "x",
        "handle": "artist_name",
        "profile_url": "https://x.com/artist_name"
      },
      {
        "platform": "pixiv",
        "handle": "12345678",
        "profile_url": "https://pixiv.net/users/12345678"
      }
    ]
  }
}

GET /api/v1/post

Get everything for a single post: full tags, AI-generated description, artist profile, and source link.

Parameter	Type	Description
id required	integer	Post ID

Example request:

curl "https://lagoon.io/api/v1/post?id=5995"

Example response:

{
  "ok": true,
  "post": {
    "id": 5995,
    "source_url": "https://x.com/artist/status/...",
    "title": "character name (series) by artist",
    "description": null,
    "posted_at": "2026-04-27 03:54:15+00",
    "platform": "x",
    "platform_name": "X (Twitter)",
    "artist_handle": "artist_name",
    "artist_name": "Artist Name",
    "deleted": false,
    "ai_description": "The image features a character with blue hair...",
    "artist_profile": "https://x.com/artist_name",
    "tags": [
      "1girl",
      "blue hair",
      "character:name",
      "copyright:series",
      "rating:general"
    ]
  }
}

GET /api/v1/tags

Search the tag index. Get back matching tags with post counts and their category.

Parameter	Type	Description
q required	string	Tag search query (min 2 characters)
limit	integer	Max results, 1-50 (default: 20)

Tags are categorized as character, copyright, species, rating, or general.

Example request:

curl "https://lagoon.io/api/v1/tags?q=genshin&limit=3"

Example response:

{
  "ok": true,
  "tags": [
    {
      "name": "genshin_impact",
      "category": "copyright",
      "post_count": 12840
    },
    {
      "name": "character:ganyu_(genshin_impact)",
      "category": "character",
      "post_count": 3201
    },
    {
      "name": "character:raiden_shogun_(genshin_impact)",
      "category": "character",
      "post_count": 2956
    }
  ]
}

Errors

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

400 - Missing or invalid parameters
401 - Bad API key
404 - Not found
429 - Rate limit hit
500 - Something broke on our end

Example error response:

HTTP/1.1 429 Too Many Requests
Retry-After: 42

{
  "ok": false,
  "error": "Rate limit exceeded. Try again in 42 seconds."
}

CORS

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