🖼️Image Upload•POST /v1/upload

Image Upload

Upload an image and return a durable hosted URL for downstream agent steps.

What it does

Accepts a file upload and returns a hosted image URL so agents can hand off screenshots, generated images, or user media without local storage.

Endpoint

Method: POST

Path: POST /v1/upload

Auth: x-agent-id + x-api-key

Request shape

•file: multipart/form-data
•retentionHours?: number

Example requests

Copy-pasteable examples for agents and automation.

cURL

curl -X POST https://www.agent-utils.com/v1/upload \
  -H "x-agent-id: worker-1" -H "x-api-key: agutil_agt_…" \
  -F "file=@screenshot.png" \
  -F "retentionHours=24"

Python

import requests

with open("screenshot.png", "rb") as f:
    resp = requests.post(
        "https://www.agent-utils.com/v1/upload",
        headers={
            "x-agent-id": "worker-1",
            "x-api-key": "agutil_agt_…",
        },
        files={"file": f},
        data={"retentionHours": 24},
    )
image_url = resp.json()["data"]["url"]

JavaScript

const form = new FormData();
form.append("file", fs.createReadStream("screenshot.png"));
form.append("retentionHours", "24");

const res = await fetch("https://www.agent-utils.com/v1/upload", {
  method: "POST",
  headers: {
    "x-agent-id": "worker-1",
    "x-api-key": "agutil_agt_…",
  },
  body: form,
});
const { data } = await res.json();
console.log(data.url);

How agents use it

A QA agent uploads a screenshot and drops the URL into a bug report.

A multimodal agent stores a generated image before sending it to the next model.

A support bot uploads customer-provided media for later review by a human.

When to use it

✓An agent needs to persist screenshots or generated images between steps.
✓You want to hand off a stable URL to another service or human reviewer.
✓Your workflow should not depend on temporary files on disk.

When not to use it

•You need a full media CDN with transformations and image editing.
•The payload is not an image file.

Failure modes

•Large files may exceed upload or retention limits.
•If the agent discards the returned URL, the asset becomes hard to reference later.
•Temporary uploads should be purged or expiry can surprise downstream steps.

Machine-readable summary

This JSON block is stable for crawlers, agents, and downstream documentation pipelines.

{
  "slug": "image-upload",
  "title": "Image Upload",
  "canonical": "/docs/image-upload",
  "endpoint": "POST /v1/upload",
  "method": "POST",
  "auth": "x-agent-id + x-api-key",
  "machine_readable": true,
  "request_shape": [
    "file: multipart/form-data",
    "retentionHours?: number"
  ],
  "agent_workflows": [
    "A QA agent uploads a screenshot and drops the URL into a bug report.",
    "A multimodal agent stores a generated image before sending it to the next model.",
    "A support bot uploads customer-provided media for later review by a human."
  ],
  "failure_modes": [
    "Large files may exceed upload or retention limits.",
    "If the agent discards the returned URL, the asset becomes hard to reference later.",
    "Temporary uploads should be purged or expiry can surprise downstream steps."
  ]
}

Related docs

dlq checkpoint