Public API Documentation

Keyless avatar searches remain on /api/v1 and /vrcx_search. Matching /v1 avatar and world endpoints are available to trusted app tokens and staff API keys only. Both avatar submission endpoints require a registered whitelisted client.

Keyless Avatar Search

60 requests per minute per client IP (per application process).

GET /api/v1/avatars/search?search=fox&limit=20

Search public, non-blacklisted cached avatars. One of: search (or q), authorId, authorName, fileId. Optional limit max 1000.

{"data":[{"id":"avtr_example","name":"Example","authorId":"usr_example","authorName":"Creator","description":null,"thumbnailImageUrl":null,"releaseStatus":"public"}],"meta":{"count":1,"limit":20}}

Try avatar search

VRCX-compatible Search

GET /vrcx_search?search=fox&limit=20 — raw JSON array of avatar objects, public without a key.

For legacy GET results use /vrcx_search?search=fox&limit=20. The legacy /v1/vrchat/avatars/search/* POST variants require trusted application or staff credentials; use the keyless GET API for anonymous search.

Avatar search in VRChat-world format remains available through GET /vrchat_world_search?search=fox and its GET aliases /api/vrchat/world/search and /api/vrchat/world/avatars/search.

60 requests per minute per client IP per search limiter.

World Metadata

GET /api/v1/worlds/search?search=club&platform=pc — name search; also accepts q. Optional platform: pc, quest, ios.

GET /api/v1/worlds/browse?sort=popular&page=1 — 24 worlds per page; sort: updated, newest, oldest, popular.

GET /api/v1/worlds/by-author/usr_example — cached worlds by author.

GET /api/v1/worlds/wrld_example — world details by ID.

The v1 routes return {"data":...,"meta":...}. API v1 uses a 60-requests-per-minute per-IP limiter. Legacy GET /api/vrchat/worlds/search?search=club returns {"worlds":[],"count":0}; GET /api/vrchat/worlds/lookup?worldId=wrld_example returns a world object directly.

Avatar Submission (Registered Clients)

POST https://api-avatar.nekosunevr.co.uk/v1/vrchat/avatars/store/putavatarExternal

Not an anonymous public-write API. Requires a registered whitelisted User-Agent prefix. Contact the site owner to register your client. No Bearer API key is required by this handler.

Content-Type: application/json
User-Agent: YourRegisteredApp/1.0

{"id":"avtr_example","userid":"YOUR_DISCORD_USER_ID"}

id is the VRChat avatar ID; userid identifies the submitting Discord user. Successful accepted submissions enter the pending scan/update queue, rather than immediately publishing an avatar. The handler uses status.status and status.message in its JSON response. It can return HTTP 200 (already exists or pending), HTTP 404 (newly queued, legacy behavior), HTTP 400 (missing id/userid), HTTP 403 (unapproved client), HTTP 429 (rate limited) and HTTP 503 (submissions paused).

The Internal URL is POST https://api-avatar.nekosunevr.co.uk/v1/vrchat/avatars/store/putavatarInternal. Both putavatarExternal and putavatarInternal use the same registered-client User-Agent whitelist and share a 50 requests/minute per-IP rate limiter. Internal uses the same JSON body as External, but queues updates for the VRChat queue rather than the Discord queue.

Private /v1 API for Application & Staff

Private /v1 search routes require an app token or a generated staff API key. Staff keys can be created and revoked in Admin → Tools. Do not put keys in client-side JavaScript.

GET /v1/avatars/search?search=fox&limit=20

GET /v1/worlds/search?search=club

GET /v1/worlds/browse?sort=popular&page=1

GET /v1/worlds/by-author/usr_example

GET /v1/worlds/wrld_example

Send Authorization: Bearer STAFF_API_KEY or X-Avatar-App-Token: PRIVATE_APP_TOKEN. The equivalent /api/v1 routes remain keyless for public use. Legacy /v1/vrchat/avatars/search POST routes also require these private credentials.

Protected VRChat User, Group & Print Lookups

All these /v1 endpoints require a private application token or Staff API key. They are not anonymous public APIs. Submit JSON with Content-Type: application/json. Requests depend on the upstream scanning service.

POST /v1/vrchat/users/search/userid        {"userid":"usr_example"}
POST /v1/vrchat/users/search/search        {"search":"example"}
POST /v1/vrchat/users/search/usergroups    {"userid":"usr_example"}
POST /v1/vrchat/users/search/prints        {"printsid":"usr_example"}

The groups and prints endpoints pass through upstream response data; their fields depend on the upstream service. The private admin interface can log returned group and print metadata. It does not expose user membership lists or unreviewed print images via public APIs.

Print moderation: entries default to pending_review and remain private. No automatic NSFW classification is enabled on this resource-constrained server; an image must be reviewed before approval.

Groups & Prints

GET /api/v1/groups/search?search=music&page=1 — visible public groups.

GET /api/v1/prints/search?page=1 — staff-approved prints only.

These use the 60/minute public API limiter. Equivalent /v1 routes require a private app token or staff key.

Public browsing pages: /groups and /prints. Group data is discovered when linked VRChat users visit their profile. Only active, non-blacklisted groups are listed. Prints are kept pending until staff explicitly approves them; rejected NSFW prints remain hidden. Linked users can manage owned groups and prints at /my-vrchat-content. Staff review pending prints at /admin/prints-review.

A verified linked VRChat account can hide only groups or prints whose stored ownerId matches the linked account. Submitting an ID is not evidence of ownership.

Whitelisted logging endpoints

POST /v1/vrchat/groups/store/putgroupExternal — queues a group ID for discovery; publishing waits for trusted metadata. You may include userid as a VRChat usr_ profile discovery hint.

POST /v1/vrchat/prints/store/putprintExternal

{"id":"prnt_example"}

Enqueues a print ID for staff review, returns HTTP 202; not immediately published.

POST /v1/vrchat/worlds/store/putworldExternal

{"id":"wrld_example","userid":"YOUR_DISCORD_USER_ID"}

Enqueues a world ID in the Discord-world scan queue, returns HTTP 202. Both endpoints require a registered whitelisted User-Agent and share the submission rate limiter (50/minute/IP). They do not accept arbitrary client-supplied metadata.

General Notes

Public search endpoints do not require an API key. HTTP 429 indicates a rate limit; retry after backing off. In-memory limits are independent across process instances and may be supplemented by gateway protection. Cached results can be stale; use sensible polling and caching. Legacy error envelopes vary from the v1 API. Example IDs are placeholders.