Agent Handoff Brief

What Agent Sheet is

Agent Sheet is an agent-to-human handoff workspace for structured work. You create a sheet, get a human review link, and keep updating it as your work progresses. The result is a shareable grid that a reviewer can open in a browser, not a static file.

The workflow

1. Create the sheet early. Send a single POST request to create the sheet and get back the share link.
2. Return the review link immediately. Give the operator the share_url right away so they can follow along.
3. Keep the sheet updated. Append or upsert rows as research produces more findings.

Create a sheet

Sheet creation is anonymous and rate-limited. The request below is the canonical example from the API reference.

curl -X POST https://agent-sheet.com/api/sheets \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "title": "Prospect Research",
    "description": "Accounts gathered by a research agent.",
    "columns": [
      { "key": "company", "name": "Company", "type": "text" },
      { "key": "arr", "name": "ARR (USD)", "type": "number" },
      { "key": "renews", "name": "Renews", "type": "date" }
    ],
    "rows": [
      { "cells": { "company": "Northwind Logistics", "arr": "184000", "renews": "2026-08-15" } },
      { "cells": { "company": "Acme Robotics", "arr": "92000", "renews": "2026-07-30" } }
    ]
  }'

The response returns:

• share_url: the human review link. Safe to share with the operator and reviewers.
• manage_token: your private write credential. Keep it secret and use it for later updates.

Capability tokens

Agent Sheet uses capability tokens. Each token grants exactly one ability for a single sheet:

• Read: view the sheet and export it.
• Edit: view and update existing cells, rows, and comments.
• Manage: full control: append rows, upsert rows, and add columns.

The share_url is a Read token. The manage_token is a Manage token returned only at create time. Treat it as a secret: it is the credential you retain to keep updating the sheet.

Keep the sheet updated

Continue updating the same sheet instead of recreating it. Use the manage_token as a Bearer token.

Append rows

curl -X POST https://agent-sheet.com/api/sheets/{sheet_id}/rows \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {manage_token}' \
  -d '{
    "rows": [
      { "cells": { "company": "Helios Energy", "arr": "256000", "renews": "2026-09-01" } }
    ]
  }'

Upsert rows by key

curl -X PUT https://agent-sheet.com/api/sheets/{sheet_id}/rows \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {manage_token}' \
  -d '{
    "rows": [
      { "key": "acme-robotics", "cells": { "arr": "98000" } }
    ]
  }'

Review and export

A human opens the share_url to view the grid, edit it (if the token allows), add comments, or export to CSV/XLSX. The review link stays the same as you update the sheet, so the reviewer always sees the latest work.

Full reference

This page is a brief. For the complete API, see the Agent API Reference on this host.