# Notchpin agent API reference For the normal flow, start with the [agent quickstart](https://notchpin.space/agents). Browser agents can use the [agent form](https://notchpin.space/agents/browser) in one JavaScript-enabled tab; keep that tab for subsequent operations. ## Session and permissions Send POST requests as application/json without query parameters. Chat enrollment accepts handle and optional scopes. Without scopes you get list, read, create, update, status, complete. An explicit scopes array replaces those defaults. Request only what the task needs. For example, to find a task by title and read its description: {"handle":"@river-quill","scopes":["list","read","read-body"]} For a retryable enrollment, generate 32 random bytes, encode as unpadded base64url, and send as Idempotency-Key. Keep that key private: replaying the same enrollment with it can recover the bearer. Do not reuse it for a different request. A pending response's expiresAt is the deadline for the owner to verify this request. The owner opens activationUrl and signs in for this request even if already signed in. A link preview or chat reply alone does not authorize access. If you cannot wait, resume when the owner replies. Check the original statusUrl after pollAfterSeconds. An unanswered or unrecognized handle can remain pending until expiry. Stop if the owner cancels. Do not request an email, password or login code. Task POSTs cannot read or write before approval; after the owner returns there is no need to poll before trying the task. A 401 is not proof of expiry. If status is pending, wait; if approved, check you used the matching saved bearer. Do not loop on errors. After approval, result.expiresAt is the session deadline. The activated token works for anyone who holds it; all holders share the same scopes, 10-minute window and 20-operation budget. The owner can revoke early. Keep credentials out of chat, logs and URLs; the only link to share is activationUrl. Do not use account cookies. A chat-session operation needs no handle; if supplied it must match. ## Operations List (scope list): returns up to 10 personal non-archived task summaries per page, including completed tasks. Title is an exact, case-insensitive match. To list open tasks, paginate and exclude done. Keep the original filter and add the returned nextCursor as cursor until nextCursor is null. Zero matches: say so. Multiple matches: ask which task. {"action":"list","title":"Work on evaluations","cursor":""} Read (read): returns task metadata, including id and version. To include the description, request read AND read-body and set includeBody to true. {"action":"read","taskId":"","includeBody":true} Create (create): title and optional body and dueDate (YYYY-MM-DD). Optional status starts the task in the requested column in one write; default todo. Initial in_progress or blocked also requires status; done also requires complete. The receipt confirms taskId, version and initial status. {"action":"create","title":"Video analysis","body":"Review the first cut","dueDate":"2027-01-15"} Move by exact title (list plus status, or list plus complete for done): the server finds a unique personal task and changes its status in one transaction. A near-match never counts. On ambiguous_title no task changed; list the exact title and paginate if necessary, ask the owner which task, then use update with that ID and version. On not_found no task changed. {"action":"move","title":"Work on evaluations","status":"in_progress"} Update by ID (update for title/body/dueDate; status for todo/in_progress/blocked; complete for done). Combine scopes if changing fields and status together. A successful status change confirms the applied status at the returned version, including on a retry. Use the current expectedVersion. An empty body or null dueDate clears that field. {"action":"update","taskId":"","expectedVersion":1,"dueDate":null,"status":"blocked"} Delete (delete): permanently removes the specified task. Request delete explicitly only when the user asks. Use list or read if you need the current ID or version. {"action":"delete","taskId":"","expectedVersion":1} ## Recovery A write receipt is success; an activation or HTTP 202 is not. If a write's response is lost, retry the same body and write key in the same session. If that session is lost, reconcile task state before attempting another write. On version_conflict, read the current task; if the requested change still applies, send a new versioned write with a new key. On a scope or handle mismatch, use the correct session or request a new link with the needed scopes. On expiration, revocation or session_limit, request fresh access only if work remains. For a rate limit with Retry-After, wait before retrying.