Every AI agent eventually hits the same wall: it produced something valuable — a PDF report, a rendered chart, a transcribed call, a scanned document — and now it has nowhere to put it. A local file path is useless to a Discord channel, an email client, or a human who needs to click a link. Agent Media Tools solves that with the durable artifact API: upload bytes once, get a public HTTPS URL that stays live for hours, days, or months, and hand that link to anyone.
This post walks through the full artifact lifecycle with real curl and Python requests examples: creating artifacts from files, text, or URLs; controlling expiry; protecting downloads with passphrases or one-time links; and managing everything from an MCP client.
An artifact is a stored file with a stable public identity. Every artifact gets a short slug, and the API returns three ways to reach it:
url — a human-friendly page at /a/{slug} where anyone can preview and download the file.raw_url — the raw bytes at /api/artifact/{slug}/raw, perfect for scripts, curl -O, or embedding in a pipeline.download_url — the API metadata endpoint, which returns JSON describing the artifact.Unlike a paste that expires when your chat window closes, artifacts live on the Agent Media Tools service. They survive agent restarts, disconnected sessions, and full machine rebuilds. For agents that deliver work to humans, this is the difference between "I made a file" and "here is your file."
| Method | Path | Purpose |
|---|---|---|
| POST | /api/artifact | Create an artifact from a file upload, text, base64, or a URL fetch |
| GET | /api/artifacts | List your active artifacts (Bearer key or login) |
| GET | /api/artifact/:slug | Fetch metadata for one artifact |
| GET | /api/artifact/:slug/raw | Download the raw file bytes |
| DELETE | /api/artifact/:slug | Delete an artifact you own |
| POST | /api/artifact/:slug/extend | Extend the expiry (capped by your plan) |
Authentication is a Bearer agent key (Authorization: Bearer mt_…) or a browser session. Listing, deleting, and extending require an authenticated owner. Creating and downloading can work anonymously within the short free-tier limits, but anonymous artifacts cannot later be listed, extended, or deleted through an owner account.
| Plan | Max file size | Max TTL | Default TTL | Max active files |
|---|---|---|---|---|
| Free | 5 MB | 24 hours | 24 hours | 10 |
| Pro | 25 MB | 30 days | 7 days | 100 |
| Builder | 50 MB | 90 days | 30 days | 250 |
Uploads over the plan cap return a 400 with the limit in the error body. Running over the active-file count returns a 402 telling you to delete old artifacts or upgrade.
The simplest case is a multipart file upload. The form field is named file:
curl -F "file=@report.pdf" \
-F 'label=Monthly security report' \
https://agentmediatools.com/api/artifact
You can create an artifact without an API key — the response already includes your shareable links:
{
"success": true,
"slug": "ab12cd34ef56",
"filename": "report.pdf",
"label": "Monthly security report",
"size": 128432,
"mime": "application/pdf",
"content_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"expires_at": "2026-09-02T06:00:00.000Z",
"ttl_hours": 24,
"plan": "free",
"url": "https://agentmediatools.com/a/ab12cd34ef56",
"download_url": "https://agentmediatools.com/api/artifact/ab12cd34ef56",
"raw_url": "https://agentmediatools.com/api/artifact/ab12cd34ef56/raw"
}
Note the content_hash: a SHA-256 of the stored bytes. When you download the raw file, the server returns the same hash in the X-Content-SHA256 response header, so you can verify integrity without a second round-trip.
Agents usually don't have a file on disk — they have a string in memory. Post JSON with content for text, or content_base64 for binary:
import requests
r = requests.post("https://agentmediatools.com/api/artifact", json={
"content": "Call summary: customer approved the renewal.\nNext step: send invoice.",
"filename": "call-summary.txt",
"label": "sales-call-042",
"ttl_hours": 168, # 7 days
}, headers={"Authorization": "Bearer mt_your_agent_key"})
data = r.json()
print(data["url"]) # human page
print(data["raw_url"]) # direct download
print(data["expires_at"]) # ISO expiry
For binary data you already hold in memory — a generated image, a converted document — base64 works the same way:
import base64, requests
with open("chart.png", "rb") as f:
b64 = base64.b64encode(f.read()).decode()
r = requests.post("https://agentmediatools.com/api/artifact", json={
"content_base64": b64,
"filename": "chart.png",
"mime": "image/png",
"one_time": True,
}, headers={"Authorization": "Bearer mt_your_agent_key"})
print(r.json()["raw_url"])
Sometimes the bytes live at another URL. Instead of downloading them yourself, pass url and the artifact service fetches (and size-checks) the remote file for you:
curl -X POST https://agentmediatools.com/api/artifact \
-H "Authorization: Bearer mt_your_agent_key" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/invoice.pdf", "filename": "invoice.pdf"}'
This is handy in pipelines where an upstream tool emits a signed URL — the agent just re-hosts it with a controlled TTL and a shareable link.
For sensitive deliverables, artifacts support two extra guards:
one_time: true (or max_downloads: 1) and the service removes the artifact after the first download stream closes.passphrase at creation. API clients should send it in the X-passphrase header; the human download page provides a form.curl -F "file=@handoff.zip" \
-F "passphrase=s3cret" \
-F "one_time=true" \
-F "ttl_hours=48" \
https://agentmediatools.com/api/artifact
Downloading that artifact later requires the passphrase, and a later attempt returns 410 after the one-time download has been consumed. Expired artifacts also return 410; unknown slugs return 404. Do not put passphrases in URLs, logs, or chat transcripts.
Owned artifacts can be managed like any other resource. List them with the same Bearer key that created them:
curl -H "Authorization: Bearer mt_your_agent_key" \
"https://agentmediatools.com/api/artifacts?limit=50"
The response includes plan, the current limits, and each artifact's slug, size, hash, download count, and expiry — useful for garbage-collecting old files before you hit the active-count cap.
Running long jobs that outlive the default TTL? Extend before it expires:
curl -X POST https://agentmediatools.com/api/artifact/ab12cd34ef56/extend \
-H "Authorization: Bearer mt_your_agent_key" \
-H "Content-Type: application/json" \
-d '{"ttl_hours": 72}'
And when the deliverable is consumed, delete it outright — deletion removes both the database row and the stored file:
curl -X DELETE -H "Authorization: Bearer mt_your_agent_key" \
https://agentmediatools.com/api/artifact/ab12cd34ef56
The same feature is exposed as MCP tools, so Claude or any MCP-capable agent can store and share deliverables without writing HTTP code. The hosted MCP server ships create_artifact, list_artifacts, and delete_artifact; set MEDIA_TOOL_AGENT_KEY in the environment and the tools authenticate automatically. create_artifact accepts content, content_base64, or url plus filename, label, ttl_hours, passphrase, and one_time — the same fields as the REST API.
Your scheduled agent finishes a report and stores it with a 7-day TTL, then writes the returned url into its summary message.
The human clicks /a/{slug}, previews or downloads the file, and the agent's next run lists its artifacts and extends or cleans up as needed.
For confidential files, the agent sets a passphrase and one-time download so the link is useless after the recipient grabs it.
That is the whole pattern: store once, share everywhere, expire on schedule. No object storage to configure, no bucket policies, no CDN invalidation — one POST and your agent has a real, durable, shareable URL.
Create and manage artifacts from the browser, or call the same API from your agent with a key. Full reference: durable artifacts docs.
Open toolbox