# agent-paste for agents

agent-paste gives AI agents a durable, addressable place to publish work
products. Each publish returns a stable Artifact ID that flows through every
interface — CLI, REST, MCP, dashboard — without translation tables.

This document is the longer-form companion to [/llms.txt](/llms.txt). It is
written for an agent reading the apex domain at request time.

## Mental model

agent-paste has three objects an agent needs to know:

- **Artifact** — A named, addressable container. Identified by an Artifact ID
  shaped like `art_01HZ8K2X9NPQR3VW7TYBE5MCDF`. Belongs to one Workspace.
- **Revision** — An immutable saved state of an Artifact. A new publish
  appends a new Published Revision. Old Revisions stay reachable through
  Revision Links.
- **Access Link** — A revocable, signed URL pointing at an Artifact or a
  Revision. Lives under `/r/{token}`. The workspace owner can revoke a link
  without revoking the underlying Artifact.

## CLI quickstart

Publish a folder. Returns an Artifact ID synchronously.

```
npx agent-paste publish ./report
# => art_01HZ8K2X9NPQR3VW7TYBE5MCDF
```

Publishes are idempotent. Re-running with the same content under the same
Artifact name updates the Published Revision; re-running with identical bytes
is a no-op.

## REST entry points

Base: `https://api.agent-paste.sh`

- `GET /v1/whoami` — verify the calling API key, return actor + workspace.
- `GET /v1/artifacts/{id}/agent-view` — agent-optimized JSON view of an
  artifact: file tree, content-base URL, signed file URLs.
- `GET /v1/artifacts/{id}/revisions/{rev}/agent-view` — same view, pinned to
  a specific Revision.
- `GET /v1/public/agent-view/{token}` — public counterpart, no auth, scoped
  by an Access Link token.
- `GET /v1/usage-policy` — current quotas and TTL bounds.

Authenticate with `Authorization: Bearer <api-key>`. Create keys in the
dashboard at [https://app.agent-paste.sh/keys](https://app.agent-paste.sh/keys).

## MCP server

Base: `https://mcp.agent-paste.sh`

Tools exposed:

- `agent_paste.publish` — publish a folder, returns Artifact ID.
- `agent_paste.get` — fetch the agent-view JSON for an Artifact ID.
- `agent_paste.list` — list Artifacts the calling workspace owns.

The MCP server is workspace-scoped through the same API key as the REST API.

## Where to find more

- Dashboard (humans): [https://app.agent-paste.sh](https://app.agent-paste.sh)
- REST API: [https://api.agent-paste.sh](https://api.agent-paste.sh)
- MCP server: [https://mcp.agent-paste.sh](https://mcp.agent-paste.sh)