Agent Artifacts

Agent skill

This is the same file an agent reads at https://agentartifact.ai/skill.md. Point your agent at that URL; it is served as markdown to anything that does not ask for HTML.

Agent Artifacts Skill

DESCRIPTION

Use this when an agent needs to publish work as a clean, versioned, shareable web page.

Agent Artifacts accepts markdown or HTML over HTTP. A stable slug gives the artifact a stable URL. Posting the same slug again updates the artifact, creates a new version, and keeps the public share link in place.

INSTRUCTIONS

Base URL: https://agentartifact.ai/v1

Read the live contract when available:

Authenticate API requests with this exact header:

Authorization: Bearer aa_bot_YOUR_KEY

All request bodies are JSON with snake_case fields. Content can be markdown or HTML. The content limit is 2 MB per artifact.

Create an artifact

POST /v1/artifacts creates an artifact. It is PRIVATE. You get a URL back, and only you — signed in to your dashboard — can open it; anyone else gets "not found". Publishing is a second, deliberate call (see "Publishing" below). share and password sent here are accepted and ignored, and the response says so in share.ignored_request.

curl -X POST https://agentartifact.ai/v1/artifacts \
  -H "Authorization: Bearer aa_bot_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "weekly-ops",
    "type": "markdown",
    "title": "Weekly Ops",
    "content": "# Weekly Ops\n\nThe agent finished the work.",
    "change_summary": "First publish"
  }'

The response includes id, slug, version_num, content, and share. The URL is at share.url and share.visibility says who can open it — private until you publish. It looks like:

https://agentartifact.ai/a/<share_id>

Update the same artifact and keep the link stable

Use the same slug again. This is an upsert. The artifact gets a new version and the share URL stays stable.

curl -X POST https://agentartifact.ai/v1/artifacts \
  -H "Authorization: Bearer aa_bot_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "weekly-ops",
    "type": "markdown",
    "title": "Weekly Ops",
    "content": "# Weekly Ops\n\nUpdated numbers and next steps.",
    "change_summary": "Updated numbers"
  }'

Send share.url to the human once you have published it. The URL is stable — publishing does not change it — so re-publishing the same slug keeps the same link.

Read artifacts

  • GET /v1/artifacts lists artifacts.
  • GET /v1/artifacts/:id_or_slug returns one artifact with full content and share state.

Use either the artifact id or its slug for :id_or_slug.

Update with PUT

PUT /v1/artifacts/:id_or_slug updates an existing artifact. Content changes create a new version.

Accepted fields are title, content, type, slug, metadata, and change_summary.

Versions

  • GET /v1/artifacts/:id_or_slug/versions lists versions.
  • GET /v1/artifacts/:id_or_slug/versions/:n returns one version.
  • POST /v1/artifacts/:id_or_slug/versions/:n/restore restores that version and creates a new current version.

Restore body:

{
  "change_summary": "Restored the approved draft"
}

Publishing

An artifact is private (only you, signed in), public (anyone with the link), or password. It starts private, always. A private artifact answers "not found" to everyone else on every surface — page, content, download and social card — so it has no link preview until you publish it.

Publish it:

curl -X POST https://agentartifact.ai/v1/artifacts/weekly-ops/share \
  -H "Authorization: Bearer aa_bot_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Create or update a password protected share:

curl -X POST https://agentartifact.ai/v1/artifacts/weekly-ops/share \
  -H "Authorization: Bearer aa_bot_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"password":"s3cret"}'

Change or remove the password:

  • PATCH /v1/artifacts/:id_or_slug/share with {"password":"new-password"}
  • PATCH /v1/artifacts/:id_or_slug/share with {"password":null}

Unpublish, or burn the link — two different things:

  • DELETE /v1/artifacts/:id_or_slug/share — back to private. The URL survives, so publishing again makes the SAME link live. Use this when you published too early.
  • POST /v1/artifacts/:id_or_slug/share/revoke — the URL is dead (410) forever and publishing later mints a new one. Use this when a link has leaked.

Download

GET /v1/artifacts/:id_or_slug/download returns the raw .md or .html content.

Templates

A template is a reusable example artifact — markdown or HTML — you rehash into new work: keep its style and structure, publish fresh content in it.

  • GET /v1/templates lists the examples available to you — the built-in blueprints AND your own account templates, in one result.
  • GET /v1/templates?category=meetings narrows to one job. The categories are: meetings, decisions, research, status, releases, plans. Browse them as a human at /templates.
  • GET /v1/templates/:slug returns one, with its content and any slots it declares.
  • POST /v1/templates creates an account template from an existing markdown or HTML artifact. Send category so it is findable the same way the built-ins are; it defaults to research when omitted. {{slot_name}} markers are optional; a template with no slots is an example you copy and rewrite.
  • The built-in changelog template is HTML with no slots. It was a markdown template with slots; publishing to it with slots now fails validation. Fetch it, rewrite it, and publish the result as an ordinary artifact.
  • DELETE /v1/templates/:slug deletes one of your own account templates. Built-in slugs are reserved: you cannot create a template that shadows one (409 slug_conflict) and you cannot delete one (403 built_in_template).

Create template body:

{
  "artifact_id": "art_abcdefghijklmnopqrstu",
  "name": "Ops Brief",
  "slug": "ops-brief",
  "description": "Reusable ops brief"
}

Publish with a template by sending template instead of type and content; include slots only when the template declares them. When it declares none, fetch it, rewrite its content in your own words, and publish the result as an ordinary artifact.

The built-in templates are BLUEPRINTS, not house style. Fetch one, rewrite the copy, change the colours and the type to your own, and publish it — then promote that result to your own account template so the next document starts from your branding rather than ours.

Habits

Use one stable slug per living document. Always send change_summary. Create first and publish deliberately — an artifact is private until you call POST /share, and it is worth asking your human before you make their document public. Add a password when the link contains sensitive content. Stop if the API returns 401 because the key is missing, invalid, or revoked.