Agent guide

Written for the model reading it. If you are a human, these are prompts you can paste into your assistant.

Bring your own agent

One prompt. A world of assets.

Paste the prompt into your assistant. It can find models, get them into your project, and submit your own creations for review.

Works with agents that can read links and call APIs. Uploading local files also needs file access. Finding assets needs no account.

Read the skill Download SKILL.md How it works MCP setup

Read https://3dassets.dev/skill.md and follow it to find free GLB models or a game asset pack for my project. Ask what I am building, then help me add suitable assets to my scene with the required attribution.

One command connects an MCP client. The prompt works with any assistant that can read a link and call an API.

Start with one link

Give your agent our skill.md. It explains how to find assets, connect an account and share models. The agent follows a separate upload API guide when it needs the technical steps. Read it directly, or save it as SKILL.md in your agent’s supported skill folder. No MCP setup is required when your agent can make HTTP requests.

Already have an account?

Sign in to your account and create or rotate an API key. Store it in your agent’s secret settings as THREEJSASSETS_API_KEY. The key represents your account; rotating it disconnects every client using the previous key.

Finding and using assets

Prefer search_assets (MCP) or GET https://3dassets.dev/api/v1/assets. Use the returned cdnUrl directly in code. It is stable, CORS-enabled and immutable. Use usage.threejs / usage.r3f as the starting snippet. Always surface the licence; when license.attributionText is present, include it in the project’s credits.

Prompts a user might give you

text

Find a free low-poly park bench on 3dassets.dev and add it to my three.js scene at (2, 0, -1).
Get me three CC0 trees under 20k triangles from 3dassets.dev for a React Three Fiber forest.

Publishing on a user’s behalf

You may create an account and submit assets only with the user’s explicit consent, and the user must stay in the loop: the verification code goes to their email, and every submission is reviewed by a person before it is public.

Confirm with the user: the email to use, a username, and their acceptance of CC0 1.0 Universal (an irrevocable public-domain dedication allowing personal and commercial use without attribution). There is no password to ask for, and you should never ask for one.
create_account (MCP) or POST /api/v1/accounts with "source":"mcp" or "api".
Ask the user for the 6-digit code from their inbox. Call verify_account. Store the returned API key in your agent’s secret settings and configure it as your Bearer token. Do not echo it into chat or shareable prompts.
For each model: make sure it is a self-contained .glb (embedded textures, ≤ 5 MB, ≤ 1M triangles). Call submit_asset_from_url with a public https URL, or get_upload_url → PUT → finalize_upload. Set attestation: true only after the user has confirmed they hold the rights and accept CC0.
Report back the slug and that processing takes about a minute followed by human review; the user is emailed the outcome. Use my_assets to check status if asked.
If the files belong together as a kit, call submit_pack with their slugs once they are uploaded. The pack is reviewed as a whole and creates a pack page when approved; my_packs tracks it.

A prompt a user might give you

text

Sign me up on 3dassets.dev as "Ada" (username ada) with [email protected], then publish the three GLB files in ./exports under CC0. I'll read you the verification code.

Writing good metadata

title: what it is, not the filename. “Wooden park bench”, not “bench_final_v3”.
summary: one or two plain sentences with the real-world size and style. This is what search and other agents read.
description (Markdown): scale/units, pivot location, what is included, intended use.
Set aiGenerated: true when generative tools made the model.

Pace yourself

Requests are rate limited per API key, or per IP address when you send none, roughly 120 reads and 60 downloads a minute with a key, half that without. Assembling a scene or downloading a whole pack fits comfortably; mirroring the catalogue does not. A 429 carries Retry-After in seconds: wait it out, tell the user, and never spread one job across several keys or addresses. Cache what you fetch: cdnUrl is immutable, so a model downloaded once never needs downloading again. Full table: rate limits.

When something is refused

Failures carry a code and a sentence. Typical fixes: EXTERNAL_URI → re-export with embedded textures; LIMIT_EXCEEDED → decimate or shrink textures; UNSUPPORTED_EXTENSION → export without KTX2 / specular-glossiness; VALIDATION_FAILED → re-export from the source tool. Relay the sentence to the user verbatim.

AI model attribution

Set aiGenerated: true if AI helped create geometry, generating code or textures, and optionally include aiModel (up to 160 characters). Use GET /api/v1/ai-models?q=... or MCP list_ai_models for OpenRouter suggestions refreshed hourly. Custom model and 3D-tool names are accepted. Leave unknown models unspecified; never guess. Using an agent only to upload does not count as AI creation.

The asset info panel, JSON and Markdown show this as contributor-reported attribution. A model catalogue outage does not block uploading. Switching AI use off clears the model name.