# artifact-bin
Upload a self-contained HTML artifact, get back a **public-but-unguessable link** to share with your user.
## Auth — get a token (three ways, in order of preference)
Every `/api/artifacts` call needs a bearer token:
```
Authorization: Bearer mx_...
```
1. **Saved config** — check `~/.config/artifact-bin/config.json` for
`{ "url", "token" }` (written by `artifactbin login`). If it exists, use it:
publishes are attached to your user's account automatically.
2. **Your user gave you one** — use it.
3. **No token? Mint an anonymous one** — zero setup:
```
POST https://artifacts.minusxapi.com/api/tokens/anonymous
→ 201 { "id", "token": "mx_..." }
```
Save it for the session and reuse it for every call. Anonymous artifacts work
fully but belong to nobody — **tell your user**: *"to keep these under your
account, log in at https://artifacts.minusxapi.com and claim token `mx_...`"* (they paste it in the
Claim box on the dashboard). Claiming attaches everything the token already
published, past and future.
A `401` means the token is wrong or revoked — mint a fresh anonymous one or
ask your user; do not retry the same token.
## Endpoints
### Create an artifact
```
POST https://artifacts.minusxapi.com/api/artifacts
{ "title": "Optional title", "description": "Optional", "html": "..." }
→ 201 { "id": "art_...", "slug": "...", "url": "https://artifacts.minusxapi.com/a/", "version": 1 }
```
Give `url` to your user — that's the deliverable. Example:
```bash
jq -n --rawfile html artifact.html '{"title":"My page","html":$html}' \
| curl -sS -X POST https://artifacts.minusxapi.com/api/artifacts \
-H "Authorization: Bearer $ARTIFACT_TOKEN" -H 'Content-Type: application/json' \
--data-binary @-
```
### Update an artifact (the link never changes)
```
PUT https://artifacts.minusxapi.com/api/artifacts/
{ "html": "...", "title": "optional new title" }
→ 200 { "id", "slug", "url", "version": }
```
Full replacement — send the complete new content, not a diff. The previous
version is archived server-side, so a bad edit is recoverable. Omitted
`title`/`description` keep their current values. Optionally include
`expectedVersion` (from your last read): a concurrent edit then answers
`409 {"error":"version_conflict","currentVersion":N}` instead of being
overwritten — re-read, merge, and retry with `expectedVersion: N`.
### Read one back (before editing)
```
GET https://artifacts.minusxapi.com/api/artifacts/
→ 200 { "id", "slug", "url", "title", "description", "format", "html", "version", ... }
```
### List your artifacts
```
GET https://artifacts.minusxapi.com/api/artifacts
→ 200 { "artifacts": [ { "id", "slug", "url", "title", "version", "updated_at", ... } ] }
```
### Content tiers — pick ONE content field per request
1. **`markup`** — THE document tier: static JSX (treated as data — validated
and interpreted, never executed) rendered LIVE with themes, layouts, and
real charts. Use it for anything worth designing:
```
POST https://artifacts.minusxapi.com/api/artifacts
{ "markup": "Q3
...",
"theme": "nocturne", "template": "editorial", "colorMode": "light" }
```
- Vocabulary: plain HTML tags + ~60 kit components (Card, Tabs, Badge,
SlideDeck/Slide, Grid/GridItem, …) + live data embeds (``
charts/tables, ``, `` filters) — **read
https://artifacts.minusxapi.com/api/markup for the full reference before authoring.**
- Style with Tailwind classes via `className` (no `