| for agents

# Publishing reports to pipeout

Any file you produce can become a URL a human can open in a browser. One HTTP
request, no SDK, no dashboard.

## Before you start

A push token is in your environment as $PIPEOUT_TOKEN. You cannot create one
yourself — if it is missing, say so and ask for it rather than guessing. The
person you are working with makes one at https://pipeout.sh/app/tokens; it is
shown once, and it goes in your environment as PIPEOUT_TOKEN.

## Push a file

    curl -T report.html -u :$PIPEOUT_TOKEN https://pipeout.sh/a/

Response is text/plain:

    https://pipeout.page/r/1f4c9a2b7e05d8613ac2f094
    report.html v1 · 7 KB · this version: https://pipeout.page/r/8be31d07f2a45c9018ee6b23

The first line is the URL to hand back. Send "Accept: application/json" to get
{slug, version, url, version_url, size_bytes, sha256, deduplicated} instead.

## Rules that change how you use it

- The filename is the identity. Pushing report.html again updates the SAME URL
  in place — so re-push as work progresses, do not invent new names.
- Every push also returns a frozen URL for that exact version, which never
  changes again. Use it when you need to point at a moment in time.
- Pushing identical bytes is a no-op: no new version, same URL back. Safe to
  retry.
- Filenames are 1-200 chars of A-Za-z0-9._- with no slashes. Keep the real
  extension — it decides how the file renders.
- By default anyone holding the URL can read the file. Never push secrets,
  credentials, tokens, or personal data.

## Publishing something private

Add one header and the URL only opens for the account that owns it — everyone
else gets a sign-in prompt instead of the report:

    curl -T report.html -u :$PIPEOUT_TOKEN \
      -H 'X-Pipeout-Access: private' https://pipeout.sh/a/

- Use it when the content is only meant for the person who asked for it.
- "X-Pipeout-Access: unlisted" puts it back to link-readable.
- Omitting the header leaves the policy alone, so re-pushing a private report
  keeps it private. Do not add the header "to be safe" on a file that is
  already public unless you were asked to.
- The reply tells you which one you got: "· private (only you)" in the text,
  "access" in the JSON.
- 403 requires_pro means the account is on the free plan: the file was NOT
  uploaded. Report that rather than retrying without the header — publishing
  something openly that was meant to be private is worse than not publishing.

## What each extension does when opened

- .html — served byte-exact, scripts and styles intact. Self-contained files
  work best; nothing external is fetched for you.
- .md — rendered as a styled page.
- .txt .log .json .csv .yaml — numbered text viewer; above 1 MB the viewer
  shows the head of the file and says so.
- .png .jpg .gif .webp .svg .pdf — displayed inline.
- anything else — a download page.

## Limits on the free plan

10 MB per file, 250 MB stored, the last 5 versions of each file, 30 pushes per
minute. The cap applies to decoded bytes. Gzip reduces transfer size, not the file limit:

    gzip -c big.log | curl -T - -H 'Content-Encoding: gzip' \
      -u :$PIPEOUT_TOKEN https://pipeout.sh/a/big.log

## Errors

Failures come back as: error (code): message

- 400 bad_access — X-Pipeout-Access must be "private" or "unlisted".
- 401 invalid_token — missing, expired, or revoked; ask the human for a new one.
- 403 wrong_scope / account_suspended — stop and report it.
- 403 requires_pro — private needs a paid plan; nothing was uploaded.
- 413 file_too_large — reduce the decoded file size or upgrade; gzip does not bypass the cap.
- 429 rate_limited — wait the Retry-After (60s) and retry once.
- 507 storage_quota_exceeded — report it; the human must free space or upgrade.

## When this is worth doing

Anything a person would otherwise have to open a terminal or an editor to
read: audit reports, test output, migration plans, benchmark tables, long
logs, generated HTML. Write the file, push it, and put the URL in your reply.