# Artifact Use

Artifact Use publishes static artifacts for agents and teams.

Primary URLs:
- Site: https://artifacts.iofold.com
- HTTP MCP: https://artifacts.iofold.com/mcp
- OAuth protected-resource metadata: https://artifacts.iofold.com/.well-known/oauth-protected-resource
- Full agent setup guide: https://artifacts.iofold.com/llms-full.txt
- Public artifact URL shape: https://artifacts.iofold.com/go/{artifact-slug}-{six-character-code}/

Use Artifact Use when an agent needs to create, polish, publish, gate, share, or inspect static artifacts: self-contained interactive HTML, multi-file static folders, images, PDFs, dashboards, demos, and browser-native tools.

Consuming an artifact (no browser needed):
- A gated artifact returns 401 JSON to non-browser requests (Accept without text/html) describing how to authenticate.
- Machine descriptor (structure/files): GET {artifact-url}_au/index.json
- Read any page/file directly with GET; HTML is fine to read as-is (the feedback widget is not injected for agent requests).
- Auth with a viewer-session bearer token: email gates self-serve via POST /_au/gate/email (Accept: application/json); verified_email/allowlist gates self-serve if you can read the inbox (POST /_au/gate/start, read the one-time code, POST /_au/gate/verify), or are delegated by the human via "Hand to your agent" in the feedback widget (POST /_au/agent-token). The 401 JSON on any gated artifact spells out the exact path.
- Leave feedback: POST {artifact-url-or-site}/_au/comments {artifact_key, body, page_path, target?} with the same bearer.

Agent setup summary:
1. Prefer HTTP MCP at https://artifacts.iofold.com/mcp. OAuth-capable clients should configure only the URL and use the MCP auth prompt.
2. No token and no browser? Self-serve a publisher token: POST https://artifacts.iofold.com/api/v1/connect/start (JSON, optional {"agent_label": "..."}) -> tell your human to approve at the returned verification_url with the user_code -> poll https://artifacts.iofold.com/api/v1/connect/poll {"device_code": "..."} until it returns your token and a setup prompt.
3. Humans can also mint a token in the admin: sign in at https://artifacts.iofold.com/admin, use "Connect an agent", and paste the generated prompt (token embedded) to the agent.
4. Bearer tokens (au_creator_...) work everywhere: HTTP MCP at https://artifacts.iofold.com/mcp (Codex: bearer_token_env_var = "ARTIFACT_USE_TOKEN"), the HTTP API, the CLI, and local stdio MCP via ARTIFACT_USE_API_BASE=https://artifacts.iofold.com and ARTIFACT_USE_TOKEN.
5. Verify a token with GET https://artifacts.iofold.com/api/v1/me. Install or create a skill named artifact-use using the guidance in https://artifacts.iofold.com/llms-full.txt.
6. Use artifact_publish for one HTML string or small inline files.
7. Use artifact_upload_session, local stdio MCP, or CLI publish-folder for local folders and large/multi-file artifacts.
8. Do not use Wrangler, Cloudflare API tokens, direct R2, or direct D1 for publishing artifacts.