Developer API

Ratings, reviews and tags — in plain JSON.

A small read-only API on top of the community data. No account, no API key, no SDK: send a GET, parse JSON. Write access (reviews, votes, tags) uses the same API with a normal account token.

Base URL https://boothpl.alicevrc.cn/api/v1

Public read endpoints

No account required. All responses are JSON; errors use {"detail":{"code":"...","message":"..."}}.

GET/booths/{booth_id}

The one-call aggregate: cached item meta, rating summary with distribution, tags, and a page of reviews. This is the only endpoint with open CORS (Access-Control-Allow-Origin: *), so it can be fetched straight from any page.

Param	Type	Default	Notes
`booth_id`	path	—	BOOTH item id, e.g. `1234567`
`limit`	int	20	1–50 reviews
`offset`	int	0	0–5000
`sort`	enum	new	`new` · `helpful` · `rating`

Rate limit: 60 requests / minute / IP → 429 RATE_LIMITED. Responses are sent with Cache-Control: no-store.

GET/booths/{booth_id}/reviews

A paged review list with its rating summary. Supports filtering by minimum rating and by “has images”.

Param	Type	Default	Notes
`sort`	enum	new	`new` · `helpful` · `rating`
`limit` / `offset`	int	10 / 0	limit 1–50
`min_rating`	int?	—	0–10
`has_images`	bool	false	only reviews with photos

GET/booths/{booth_id}/tags

Every community tag on one item, with up / down counts. score is up - down.

Param	Type	Default	Notes
`sort`	enum	hot	`hot` · `new`

GET/tags/search

Search every tagged item by keyword, tag names and price cap. Same engine as the web finder.

Param	Type	Default	Notes
`q`	str	""	keyword / title search
`tags`	str	""	comma separated, e.g. `3D,かわいい`
`match`	enum	any	`all` · `any`
`max_price`	int?	—	JPY, 0–10,000,000
`sort`	enum	relevant	`relevant` · `new` · `price` · `rating`
`limit` / `offset`	int	20 / 0	limit 1–50

GET/tags/popular

The most used tags across all items, for suggestions and browsing.

Param	Type	Default	Notes
`limit`	int	12	1–50 (+5 min cache)

Example

One request, one object. Timestamps are UTC but carry no offset — add “Z” before Date.parse if you need local time.

# aggregate: meta + rating + tags + first two reviews
curl "https://boothpl.alicevrc.cn/api/v1/booths/1234567?limit=2&sort=helpful"

{
  "booth_id": "1234567",
  "booth_url": "https://booth.pm/ja/items/1234567",
  "meta": { "title": "Pastel Bunny 3D Model", "price_jpy": 1200, "thumb": "https://..." },
  "rating": { "average": 8.4, "count": 12, "comments": 5,
              "distribution": [ { "score": 10, "count": 6, "pct": 50 } ] },
  "tags": [ { "name": "3Dモデル", "up": 9, "down": 1, "score": 8 } ],
  "reviews": { "total": 5, "has_more": true, "items": [
    { "rid": "a1b2c3d4", "rating": 9, "content": "Rig is clean.",
      "images": [], "user": { "username": "alice" },
      "helpful": 4, "created_at": "2026-11-06T12:00:00", "edited_at": null } ] },
  "generated_at": "2026-11-07T01:50:00"
}

Writing is not public

This API is read-only for third parties. Posting reviews, voting, adding tags and account actions are reserved for the official extension and this site; requests from any other client are rejected with 403 CLIENT_REQUIRED. Need a feed or an integration? Contact the site owner.

Errors & limits

Errors always come back as JSON with a stable machine-readable code.

Status	Code	When
404	`*_NOT_FOUND`	unknown booth, review or invite
409	`SHOP_ALREADY_CLAIMED` · `INVITE_*` · `CANNOT_TRANSFER_SELF`	state conflicts
422	`VALIDATION_ERROR`	bad parameter type or range
429	`RATE_LIMITED` · `INVITE_LIMIT`	too many requests

Public booth aggregate: 60 req/min/IP. Rate limits are per server worker; back off and retry after a minute. The API may change while the site is in beta — pin your client and handle unknown fields gracefully.