# Notchpin: instructions for AI agents Use the user's @handle and an email-approved session. Never sign in to the human workspace, open the user's inbox, or ask for an email link, password, or token. Browser agent? Open https://notchpin.space/agents/browser in the same tab for this conversation. Enter the handle, select the permissions needed for the user's request, and request a session. If that tab already has the right session, use it. After the user approves by email, choose Check approval, then run the JSON operations below. The form handles credentials for you. HTTP client? No installation or account cookies are needed. 1. Reuse your own unexpired session for this exact origin, handle, and approved permissions. Otherwise: POST https://notchpin.space/agents/session/request Content-Type: application/json {"handle":"@river-quill","scopes":["list","status"]} For safe enrollment retries, send Idempotency-Key: 32 cryptographically random bytes as unpadded base64url (43 characters). Reuse it only for an identical retry. 2. A 202 is pending, not approval. Keep sessionToken and statusUrl private. Tell the user: “Check your email to approve this session.” Share the matching phrase so they can verify the email. Wait pollAfterSeconds; GET the returned statusUrl, in the same conversation. If the user says they approved, check that same request. Only status "approved" activates access; a pending request cannot change tasks. 3. POST https://notchpin.space/agents/session Content-Type: application/json Authorization: Bearer {sessionToken} Include handle in every JSON body. For each create, update, or delete, set Idempotency-Key to a new random UUID; reuse the same body and key if delivery is uncertain. Only report success after a successful operation response. Example: “Set Work on evaluations to In progress.” Substitute the user's real handle. Find it: {"handle":"@river-quill","action":"list","title":"Work on evaluations"} If exactly one task matches, use its returned id and version: {"handle":"@river-quill","action":"update","taskId":"","expectedVersion":1,"status":"in_progress"} Do not guess an ID. If multiple match, ask which one the user means. If none match, tell the user. If nextCursor is present, continue with the same filter and cursor before deciding a match is unique. Operations and consent (request only the scopes needed): - list: {"action":"list"} lists summaries; optional title is an exact case-insensitive filter. Follow nextCursor by adding "cursor" to the same query. Summaries include id, title, status, dueDate and version. - read: {"action":"read","taskId":""}. For a description, request read AND read-body and add "includeBody":true. - create: {"action":"create","title":"Renew passport"}. Optional body and dueDate (YYYY-MM-DD). - update: {"action":"update","taskId":"","expectedVersion":1,"title":"New title"}. Change title, body or dueDate; empty body or null dueDate clears it. - status: use update with status todo, in_progress, or blocked. For status done request complete. If also editing text or dueDate, ask for update too. - delete: {"action":"delete","taskId":"","expectedVersion":1}. Ask for delete only if the user wants to delete a task. Add the real handle to each example. A read or list is needed to look up unknown IDs or versions. Writes return taskId and version. Sessions allow at most 20 operations within 10 minutes after approval. They can be revoked earlier. On an expired, revoked or exhausted session, request a new session for the user's current task. A scope or handle mismatch never grants more access: use the correct session or ask for a new email approval. On version_conflict, read the latest task before retrying. If a write had an unknown outcome and its session is lost, reconcile with a read before attempting another write. Keep credentials out of URLs, chat, logs and shared storage; never reuse a grant across users or agents. If your tool can only read or search webpages and cannot operate a browser or send HTTPS POST, it can read this guide but cannot access tasks. Do not send the user to workspace sign-in.