API Reference

Publish and update artifacts programmatically from Claude Code, scripts, or any HTTP client. All endpoints require an API key — create one at /settings.

Authentication

Pass your API key in the Authorization header on every request:

Authorization: Bearer artfly_<your-key>

API keys are shown once on creation. If you lose a key, revoke it and create a new one.

Base URL

https://www.artfly.net

All endpoints below are relative to this base URL.

Endpoints

POST

/api/v1/artifacts

Create a new artifact

PUT

/api/v1/artifacts/:publicId

Publish a new version of an existing artifact

GET

/api/v1/artifacts

List your artifacts

Create artifact

POST/api/v1/artifacts

Request body (JSON)

Field	Type	Description
`html`	string *	Full HTML content. Max 10 MB.
`title`	string	Title. Extracted from `<title>` if omitted.
`expires_in`	"never" \| "7d" \| "30d"	Expiration window. Default: `"never"`.
`allow_indexing`	boolean	Allow search engines to index. Default: `false`.
`comments_enabled`	boolean	Enable comments. Default: `false`.

Example

curl -X POST https://www.artfly.net/api/v1/artifacts \
  -H "Authorization: Bearer artfly_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<!DOCTYPE html><html><body><h1>Hello</h1></body></html>",
    "title": "My artifact"
  }'

Response (201)

{
  "artifact_id": "uuid",
  "public_id": "aB3kX9mNpQ",
  "url": "https://www.artfly.net/a/aB3kX9mNpQ",
  "title": "My artifact",
  "privacy": "public"
}

Update artifact (new version)

PUT/api/v1/artifacts/:publicId

Publishes a new version. The artifact URL stays the same — visitors always see the latest version.

Request body (JSON)

Field	Type	Description
`html`	string *	New HTML content. Max 10 MB.
`title`	string	Override title. Extracted from HTML if omitted.

Example

curl -X PUT https://www.artfly.net/api/v1/artifacts/aB3kX9mNpQ \
  -H "Authorization: Bearer artfly_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<!DOCTYPE html><html><body><h1>Updated!</h1></body></html>"
  }'

Response (200)

{
  "public_id": "aB3kX9mNpQ",
  "url": "https://www.artfly.net/a/aB3kX9mNpQ",
  "version_number": 2,
  "title": "Updated!"
}

List artifacts

GET/api/v1/artifacts

Query parameters

Param	Default	Description
`page`	1	Page number (1-indexed).
`per_page`	20	Results per page. Max 50.

Example

curl "https://www.artfly.net/api/v1/artifacts?per_page=5" \
  -H "Authorization: Bearer artfly_<your-key>"

Response (200)

{
  "artifacts": [
    {
      "id": "uuid",
      "public_id": "aB3kX9mNpQ",
      "title": "My artifact",
      "privacy": "public",
      "status": "active",
      "url": "https://www.artfly.net/a/aB3kX9mNpQ",
      "updated_at": "2024-01-15T10:30:00Z",
      "created_at": "2024-01-15T10:00:00Z"
    }
  ],
  "page": 1,
  "per_page": 5,
  "total": 42
}

Error responses

All errors return JSON with an error object:

{ "error": { "code": "UNAUTHENTICATED", "message": "Authentication required" } }

Code	Status	Meaning
`UNAUTHENTICATED`	401	Missing or invalid API key
`VALIDATION_ERROR`	400	Invalid request body or parameters
`PAYLOAD_TOO_LARGE`	413	HTML exceeds the 10 MB limit
`ARTIFACT_NOT_FOUND`	404	No artifact with that public_id owned by you
`RATE_LIMITED`	429	Too many requests — slow down

Claude Code integration

Use the /artfly Claude Code skill to publish artifacts directly from your editor — no shell scripting needed. The skill handles JSON encoding, calls the API, and prints the URL.

Install the skill

Download the skill file and save it to .claude/commands/artfly.md inside any project where you want to use it.
Set your API key once in your shell or .env.local: ARTFLY_API_KEY=artfly_<your-key>
Run /artfly inside Claude Code — it will prompt for a file or let you paste HTML.

Download artfly.md

Usage

# Publish a new artifact
/artfly path/to/artifact.html

# Publish a new version of an existing artifact
/artfly update aB3kX9mNpQ path/to/artifact.html