{ "openapi": "3.1.0", "info": { "title": "Pending You person API", "version": "2026-10-05", "summary": "Apps that answer as the person: their cards, their assistants, their presence.", "description": "The person API lets an app act as the person who signs it in: list the cards their assistants ask them, show one, answer it, write to its assistant, put it in Later, hand it to another assistant, see which assistants are running, and keep their phone quiet while they’re at the app.\n\nPending You never answers for the person: an app answers only when the person presses something in it. High-stakes cards (they spend money, can’t be undone or go public) can be read but never acted on: send the person to the card’s `url`. Account, sign-in, billing, secrets and managing assistants aren’t in this API at all.\n\nSign-in is OAuth 2.1 at Pending You: by device code (RFC 8628, `x-pendingyou-device`) for terminals and plugins, which proves the computer’s key, and authorization code with PKCE for web and desktop apps. Public apps’ tokens are bound to a key that stays on their computer (DPoP, RFC 9449): send `Authorization: DPoP ` with a `DPoP` proof for each request (`x-pendingyou-dpop`).\n\nRefusals past sign-in are problem details (RFC 9457) with a stable `code`. Sign-in’s own (a token, its proof, its scope) are OAuth’s: 401 or 403 with `WWW-Authenticate`.\n\n/v1 only ever adds: paths, optional input fields, output fields and enum values. Ignore fields you don’t know. Behaviour changes are dated: send `Pending-You-Version` to pin one." }, "servers": [ { "url": "https://www.pendingyou.com" } ], "externalDocs": { "description": "The person API", "url": "https://www.pendingyou.com/docs/api" }, "tags": [ { "name": "me", "description": "This sign-in." }, { "name": "cards", "description": "The person’s cards: read them, and act as the person." }, { "name": "changes", "description": "The change feed." }, { "name": "assistants", "description": "The person’s assistants and their agents." }, { "name": "presence", "description": "The person at the app." } ], "security": [ { "oauth2": [] } ], "paths": { "/v1/me": { "get": { "operationId": "getMe", "summary": "Who and what this sign-in is", "description": "The person, their workspace, the app and this sign-in: its scopes, its reach (one computer or every card), its computer, and when it ends. Any scope.", "tags": [ "me" ], "security": [ { "oauth2": [] } ], "parameters": [ { "$ref": "#/components/parameters/PendingYouVersion" }, { "$ref": "#/components/parameters/DPoP" }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "Who and what this sign-in is", "headers": { "Pending-You-Version": { "$ref": "#/components/headers/PendingYouVersion" }, "DPoP-Nonce": { "$ref": "#/components/headers/DPoPNonce" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "304": { "description": "Not modified: If-None-Match named this answer’s ETag." }, "400": { "description": "invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "invalid" ] }, "401": { "description": "invalid_token, invalid_dpop_proof or use_dpop_nonce (OAuth, with WWW-Authenticate)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "app_not_available; insufficient_scope (OAuth, with WWW-Authenticate naming the scope)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } }, "x-pendingyou-problems": [ "app_not_available" ] }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "rate_limited" ] }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "server_error" ] }, "503": { "description": "unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "unavailable" ] } }, "x-pendingyou-name": "me", "x-pendingyou-scope": null, "x-pendingyou-limits": [ "read", "workspace" ] } }, "/v1/cards": { "get": { "operationId": "listCards", "summary": "The cards in reach, one list at a time", "description": "Waiting on the person in the stack’s order (pending), in Later soonest back first (snoozed), with a helper (delegated), or done in the last 30 days newest first. Filters repeat (`?area=prj_…&area=prj_…`); pages follow `next`. The first `whole` cards come whole.", "tags": [ "cards" ], "security": [ { "oauth2": [ "cards:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/PendingYouVersion" }, { "$ref": "#/components/parameters/DPoP" }, { "$ref": "#/components/parameters/IfNoneMatch" }, { "name": "status", "in": "query", "required": false, "schema": { "default": "pending", "type": "string", "enum": [ "pending", "snoozed", "delegated", "done" ] } }, { "name": "area", "in": "query", "required": false, "schema": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string", "pattern": "^prj_[A-Za-z0-9-]+$" } }, "style": "form", "explode": true }, { "name": "assistant", "in": "query", "required": false, "schema": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string", "pattern": "^con_[A-Za-z0-9-]+$" } }, "style": "form", "explode": true }, { "name": "agent", "in": "query", "required": false, "schema": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string", "pattern": "^agt_[A-Za-z0-9-]+$" } }, "style": "form", "explode": true }, { "name": "app", "in": "query", "required": false, "schema": { "minItems": 1, "maxItems": 13, "type": "array", "items": { "type": "string", "enum": [ "claude-code", "codex", "cursor", "gemini-cli", "opencode", "pi", "grok", "muse", "chatgpt", "claude", "dots", "other", "webhook" ] } }, "style": "form", "explode": true }, { "name": "machine", "in": "query", "required": false, "schema": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "string", "pattern": "^mch_[A-Za-z0-9-]+$" } }, "style": "form", "explode": true }, { "name": "threadId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^req_[A-Za-z0-9-]+$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "whole", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "minimum": 0, "maximum": 3 } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "The cards in reach, one list at a time", "headers": { "Pending-You-Version": { "$ref": "#/components/headers/PendingYouVersion" }, "DPoP-Nonce": { "$ref": "#/components/headers/DPoPNonce" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardList" } } } }, "304": { "description": "Not modified: If-None-Match named this answer’s ETag." }, "400": { "description": "invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "invalid" ] }, "401": { "description": "invalid_token, invalid_dpop_proof or use_dpop_nonce (OAuth, with WWW-Authenticate)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "app_not_available; insufficient_scope (OAuth, with WWW-Authenticate naming the scope)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } }, "x-pendingyou-problems": [ "app_not_available" ] }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "rate_limited" ] }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "server_error" ] }, "503": { "description": "unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "unavailable" ] } }, "x-pendingyou-name": "cards.list", "x-pendingyou-scope": "cards:read", "x-pendingyou-limits": [ "read", "workspace" ] } }, "/v1/cards/{id}": { "get": { "operationId": "getCard", "summary": "One card, whole", "description": "A card out of reach is not found, exactly as one that doesn’t exist.", "tags": [ "cards" ], "security": [ { "oauth2": [ "cards:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/CardId" }, { "$ref": "#/components/parameters/PendingYouVersion" }, { "$ref": "#/components/parameters/DPoP" }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "One card, whole", "headers": { "Pending-You-Version": { "$ref": "#/components/headers/PendingYouVersion" }, "DPoP-Nonce": { "$ref": "#/components/headers/DPoPNonce" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardResponse" } } } }, "304": { "description": "Not modified: If-None-Match named this answer’s ETag." }, "400": { "description": "invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "invalid" ] }, "401": { "description": "invalid_token, invalid_dpop_proof or use_dpop_nonce (OAuth, with WWW-Authenticate)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "app_not_available; insufficient_scope (OAuth, with WWW-Authenticate naming the scope)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } }, "x-pendingyou-problems": [ "app_not_available" ] }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "not_found" ] }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "rate_limited" ] }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "server_error" ] }, "503": { "description": "unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "unavailable" ] } }, "x-pendingyou-name": "cards.get", "x-pendingyou-scope": "cards:read", "x-pendingyou-limits": [ "read", "workspace" ] } }, "/v1/cards/{id}/answer": { "post": { "operationId": "answerCard", "summary": "Answer a card", "description": "With the version you showed the person. Its assistant hears it once its 5 seconds are over; until `undoUntil` this app may take it back.", "tags": [ "cards" ], "security": [ { "oauth2": [ "cards:answer" ] } ], "parameters": [ { "$ref": "#/components/parameters/CardId" }, { "$ref": "#/components/parameters/PendingYouVersion" }, { "$ref": "#/components/parameters/DPoP" }, { "$ref": "#/components/parameters/IdempotencyKeyRequired" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnswerRequest" } } } }, "responses": { "200": { "description": "Answer a card", "headers": { "Pending-You-Version": { "$ref": "#/components/headers/PendingYouVersion" }, "DPoP-Nonce": { "$ref": "#/components/headers/DPoPNonce" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnswerResponse" } } } }, "400": { "description": "invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "invalid" ] }, "401": { "description": "invalid_token, invalid_dpop_proof or use_dpop_nonce (OAuth, with WWW-Authenticate)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "app_not_available; high_stakes; area_change; forbidden; insufficient_scope (OAuth, with WWW-Authenticate naming the scope)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } }, "x-pendingyou-problems": [ "app_not_available", "high_stakes", "area_change", "forbidden" ] }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "not_found" ] }, "409": { "description": "version_conflict; not_waiting; delegated; conflict; idempotency_in_progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "version_conflict", "not_waiting", "delegated", "conflict", "idempotency_in_progress" ] }, "422": { "description": "idempotency_mismatch", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "idempotency_mismatch" ] }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "rate_limited" ] }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "server_error" ] }, "501": { "description": "not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "not_available" ] }, "503": { "description": "unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "unavailable" ] } }, "x-pendingyou-name": "cards.answer", "x-pendingyou-scope": "cards:answer", "x-pendingyou-limits": [ "answers", "write", "workspace" ], "x-pendingyou-idempotency": "required" } }, "/v1/cards/{id}/undo": { "post": { "operationId": "undoAnswer", "summary": "Take this app’s answer back", "description": "Within its 5 seconds, and only an answer given in this app.", "tags": [ "cards" ], "security": [ { "oauth2": [ "cards:answer" ] } ], "parameters": [ { "$ref": "#/components/parameters/CardId" }, { "$ref": "#/components/parameters/PendingYouVersion" }, { "$ref": "#/components/parameters/DPoP" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UndoRequest" } } } }, "responses": { "200": { "description": "Take this app’s answer back", "headers": { "Pending-You-Version": { "$ref": "#/components/headers/PendingYouVersion" }, "DPoP-Nonce": { "$ref": "#/components/headers/DPoPNonce" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardBack" } } } }, "400": { "description": "invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "invalid" ] }, "401": { "description": "invalid_token, invalid_dpop_proof or use_dpop_nonce (OAuth, with WWW-Authenticate)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "app_not_available; high_stakes; not_your_answer; forbidden; insufficient_scope (OAuth, with WWW-Authenticate naming the scope)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } }, "x-pendingyou-problems": [ "app_not_available", "high_stakes", "not_your_answer", "forbidden" ] }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "not_found" ] }, "409": { "description": "not_waiting; hold_over; conflict; idempotency_in_progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "not_waiting", "hold_over", "conflict", "idempotency_in_progress" ] }, "422": { "description": "idempotency_mismatch", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "idempotency_mismatch" ] }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "rate_limited" ] }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "server_error" ] }, "503": { "description": "unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "unavailable" ] } }, "x-pendingyou-name": "cards.undo", "x-pendingyou-scope": "cards:answer", "x-pendingyou-limits": [ "write", "workspace" ], "x-pendingyou-idempotency": "optional" } }, "/v1/cards/{id}/messages": { "post": { "operationId": "replyToCard", "summary": "Write to the assistant that asked", "description": "The person’s words, on its card. They hand it the turn and it acts on them as the answer, so they count against the answers’ limit.", "tags": [ "cards" ], "security": [ { "oauth2": [ "cards:reply" ] } ], "parameters": [ { "$ref": "#/components/parameters/CardId" }, { "$ref": "#/components/parameters/PendingYouVersion" }, { "$ref": "#/components/parameters/DPoP" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageRequest" } } } }, "responses": { "200": { "description": "Write to the assistant that asked", "headers": { "Pending-You-Version": { "$ref": "#/components/headers/PendingYouVersion" }, "DPoP-Nonce": { "$ref": "#/components/headers/DPoPNonce" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "400": { "description": "invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "invalid" ] }, "401": { "description": "invalid_token, invalid_dpop_proof or use_dpop_nonce (OAuth, with WWW-Authenticate)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "app_not_available; high_stakes; forbidden; insufficient_scope (OAuth, with WWW-Authenticate naming the scope)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } }, "x-pendingyou-problems": [ "app_not_available", "high_stakes", "forbidden" ] }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "not_found" ] }, "409": { "description": "not_waiting; delegated; conflict; idempotency_in_progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "not_waiting", "delegated", "conflict", "idempotency_in_progress" ] }, "422": { "description": "idempotency_mismatch", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "idempotency_mismatch" ] }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "rate_limited" ] }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "server_error" ] }, "503": { "description": "unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "unavailable" ] } }, "x-pendingyou-name": "cards.messages", "x-pendingyou-scope": "cards:reply", "x-pendingyou-limits": [ "answers", "write", "workspace" ], "x-pendingyou-idempotency": "optional" } }, "/v1/cards/{id}/later": { "post": { "operationId": "putCardInLater", "summary": "Put a card in Later", "description": "Until a time (a minute to two months ahead) or a preset, `1h`, `tonight` or `tomorrow`, in `timeZone`.", "tags": [ "cards" ], "security": [ { "oauth2": [ "cards:later" ] } ], "parameters": [ { "$ref": "#/components/parameters/CardId" }, { "$ref": "#/components/parameters/PendingYouVersion" }, { "$ref": "#/components/parameters/DPoP" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaterRequest" } } } }, "responses": { "200": { "description": "Put a card in Later", "headers": { "Pending-You-Version": { "$ref": "#/components/headers/PendingYouVersion" }, "DPoP-Nonce": { "$ref": "#/components/headers/DPoPNonce" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaterResponse" } } } }, "400": { "description": "invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "invalid" ] }, "401": { "description": "invalid_token, invalid_dpop_proof or use_dpop_nonce (OAuth, with WWW-Authenticate)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "app_not_available; high_stakes; forbidden; insufficient_scope (OAuth, with WWW-Authenticate naming the scope)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } }, "x-pendingyou-problems": [ "app_not_available", "high_stakes", "forbidden" ] }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "not_found" ] }, "409": { "description": "not_waiting; delegated; conflict; idempotency_in_progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "not_waiting", "delegated", "conflict", "idempotency_in_progress" ] }, "422": { "description": "idempotency_mismatch", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "idempotency_mismatch" ] }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "rate_limited" ] }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "server_error" ] }, "503": { "description": "unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "unavailable" ] } }, "x-pendingyou-name": "cards.later", "x-pendingyou-scope": "cards:later", "x-pendingyou-limits": [ "write", "workspace" ], "x-pendingyou-idempotency": "optional" } }, "/v1/cards/{id}/back": { "post": { "operationId": "bringCardBack", "summary": "Bring a card back from Later", "description": "Now, to its place in the stack. One already back answers with its version.", "tags": [ "cards" ], "security": [ { "oauth2": [ "cards:later" ] } ], "parameters": [ { "$ref": "#/components/parameters/CardId" }, { "$ref": "#/components/parameters/PendingYouVersion" }, { "$ref": "#/components/parameters/DPoP" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackRequest" } } } }, "responses": { "200": { "description": "Bring a card back from Later", "headers": { "Pending-You-Version": { "$ref": "#/components/headers/PendingYouVersion" }, "DPoP-Nonce": { "$ref": "#/components/headers/DPoPNonce" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardBack" } } } }, "400": { "description": "invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "invalid" ] }, "401": { "description": "invalid_token, invalid_dpop_proof or use_dpop_nonce (OAuth, with WWW-Authenticate)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "app_not_available; high_stakes; forbidden; insufficient_scope (OAuth, with WWW-Authenticate naming the scope)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } }, "x-pendingyou-problems": [ "app_not_available", "high_stakes", "forbidden" ] }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "not_found" ] }, "409": { "description": "not_waiting; conflict; idempotency_in_progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "not_waiting", "conflict", "idempotency_in_progress" ] }, "422": { "description": "idempotency_mismatch", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "idempotency_mismatch" ] }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "rate_limited" ] }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "server_error" ] }, "503": { "description": "unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "unavailable" ] } }, "x-pendingyou-name": "cards.back", "x-pendingyou-scope": "cards:later", "x-pendingyou-limits": [ "write", "workspace" ], "x-pendingyou-idempotency": "optional" } }, "/v1/cards/{id}/delegate": { "post": { "operationId": "delegateCard", "summary": "Hand a card to another assistant", "description": "One of the person’s assistants in reach (GET /v1/assistants). `freely`: its answer goes straight back; `loop`: it comes to the person first. Until `undoUntil` the helper can’t see it.", "tags": [ "cards" ], "security": [ { "oauth2": [ "cards:delegate" ] } ], "parameters": [ { "$ref": "#/components/parameters/CardId" }, { "$ref": "#/components/parameters/PendingYouVersion" }, { "$ref": "#/components/parameters/DPoP" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegateRequest" } } } }, "responses": { "200": { "description": "Hand a card to another assistant", "headers": { "Pending-You-Version": { "$ref": "#/components/headers/PendingYouVersion" }, "DPoP-Nonce": { "$ref": "#/components/headers/DPoPNonce" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegateResponse" } } } }, "400": { "description": "invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "invalid" ] }, "401": { "description": "invalid_token, invalid_dpop_proof or use_dpop_nonce (OAuth, with WWW-Authenticate)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "app_not_available; high_stakes; forbidden; insufficient_scope (OAuth, with WWW-Authenticate naming the scope)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } }, "x-pendingyou-problems": [ "app_not_available", "high_stakes", "forbidden" ] }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "not_found" ] }, "409": { "description": "not_waiting; delegated; conflict; idempotency_in_progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "not_waiting", "delegated", "conflict", "idempotency_in_progress" ] }, "422": { "description": "idempotency_mismatch", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "idempotency_mismatch" ] }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "rate_limited" ] }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "server_error" ] }, "503": { "description": "unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "unavailable" ] } }, "x-pendingyou-name": "cards.delegate", "x-pendingyou-scope": "cards:delegate", "x-pendingyou-limits": [ "write", "workspace" ], "x-pendingyou-idempotency": "optional" } }, "/v1/cards/{id}/take-back": { "post": { "operationId": "takeCardBack", "summary": "Take a card back from its helper", "description": "Before the helper answers it: the card waits on the person again.", "tags": [ "cards" ], "security": [ { "oauth2": [ "cards:delegate" ] } ], "parameters": [ { "$ref": "#/components/parameters/CardId" }, { "$ref": "#/components/parameters/PendingYouVersion" }, { "$ref": "#/components/parameters/DPoP" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TakeBackRequest" } } } }, "responses": { "200": { "description": "Take a card back from its helper", "headers": { "Pending-You-Version": { "$ref": "#/components/headers/PendingYouVersion" }, "DPoP-Nonce": { "$ref": "#/components/headers/DPoPNonce" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardBack" } } } }, "400": { "description": "invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "invalid" ] }, "401": { "description": "invalid_token, invalid_dpop_proof or use_dpop_nonce (OAuth, with WWW-Authenticate)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "app_not_available; high_stakes; forbidden; insufficient_scope (OAuth, with WWW-Authenticate naming the scope)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } }, "x-pendingyou-problems": [ "app_not_available", "high_stakes", "forbidden" ] }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "not_found" ] }, "409": { "description": "not_waiting; conflict; idempotency_in_progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "not_waiting", "conflict", "idempotency_in_progress" ] }, "422": { "description": "idempotency_mismatch", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "idempotency_mismatch" ] }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "rate_limited" ] }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "server_error" ] }, "503": { "description": "unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "unavailable" ] } }, "x-pendingyou-name": "cards.take_back", "x-pendingyou-scope": "cards:delegate", "x-pendingyou-limits": [ "write", "workspace" ], "x-pendingyou-idempotency": "optional" } }, "/v1/changes": { "get": { "operationId": "listChanges", "summary": "What changed since a cursor", "description": "Ids and types only, in commit order, kept to the reach. Without `after`: from now. With `wait` (up to 25 seconds) it waits for the first change. Read GET /v1/cards again on start and every 10 minutes too: a card that comes into reach makes no change.", "tags": [ "changes" ], "security": [ { "oauth2": [ "cards:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/PendingYouVersion" }, { "$ref": "#/components/parameters/DPoP" }, { "$ref": "#/components/parameters/IfNoneMatch" }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "wait", "in": "query", "required": false, "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 25 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "What changed since a cursor", "headers": { "Pending-You-Version": { "$ref": "#/components/headers/PendingYouVersion" }, "DPoP-Nonce": { "$ref": "#/components/headers/DPoPNonce" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeList" } } } }, "304": { "description": "Not modified: If-None-Match named this answer’s ETag." }, "400": { "description": "invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "invalid" ] }, "401": { "description": "invalid_token, invalid_dpop_proof or use_dpop_nonce (OAuth, with WWW-Authenticate)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "app_not_available; insufficient_scope (OAuth, with WWW-Authenticate naming the scope)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } }, "x-pendingyou-problems": [ "app_not_available" ] }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "rate_limited" ] }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "server_error" ] }, "503": { "description": "unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "unavailable" ] } }, "x-pendingyou-name": "changes", "x-pendingyou-scope": "cards:read", "x-pendingyou-limits": [ "read", "workspace", "wait" ] } }, "/v1/assistants": { "get": { "operationId": "listAssistants", "summary": "The assistants in reach", "description": "Each sign-in, its computer and how it hears answers, and its agents: live, recent or quiet, their open cards, and the sessions running now with the terminal each runs in. Live ones first.", "tags": [ "assistants" ], "security": [ { "oauth2": [ "assistants:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/PendingYouVersion" }, { "$ref": "#/components/parameters/DPoP" }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "The assistants in reach", "headers": { "Pending-You-Version": { "$ref": "#/components/headers/PendingYouVersion" }, "DPoP-Nonce": { "$ref": "#/components/headers/DPoPNonce" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantList" } } } }, "304": { "description": "Not modified: If-None-Match named this answer’s ETag." }, "400": { "description": "invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "invalid" ] }, "401": { "description": "invalid_token, invalid_dpop_proof or use_dpop_nonce (OAuth, with WWW-Authenticate)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "app_not_available; insufficient_scope (OAuth, with WWW-Authenticate naming the scope)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } }, "x-pendingyou-problems": [ "app_not_available" ] }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "rate_limited" ] }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "server_error" ] }, "503": { "description": "unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "unavailable" ] } }, "x-pendingyou-name": "assistants", "x-pendingyou-scope": "assistants:read", "x-pendingyou-limits": [ "read", "workspace" ] } }, "/v1/presence": { "post": { "operationId": "setPresence", "summary": "Say the person is at this app", "description": "`here: true` every 30 seconds while they’re active in it (it lasts 75), `here: false` when they leave. Meanwhile their phones stay quiet, as with Pending You open on a computer. Answers 204.", "tags": [ "presence" ], "security": [ { "oauth2": [ "presence:desk" ] } ], "parameters": [ { "$ref": "#/components/parameters/PendingYouVersion" }, { "$ref": "#/components/parameters/DPoP" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresenceRequest" } } } }, "responses": { "204": { "description": "Say the person is at this app" }, "400": { "description": "invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "invalid" ] }, "401": { "description": "invalid_token, invalid_dpop_proof or use_dpop_nonce (OAuth, with WWW-Authenticate)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "app_not_available; insufficient_scope (OAuth, with WWW-Authenticate naming the scope)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } }, "x-pendingyou-problems": [ "app_not_available" ] }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "rate_limited" ] }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "server_error" ] }, "503": { "description": "unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "x-pendingyou-problems": [ "unavailable" ] } }, "x-pendingyou-name": "presence", "x-pendingyou-scope": "presence:desk", "x-pendingyou-limits": [ "write", "workspace" ] } } }, "components": { "schemas": { "Me": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^usr_[A-Za-z0-9-]+$" } }, "required": [ "id" ], "additionalProperties": false }, "workspace": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^ws_[A-Za-z0-9-]+$" } }, "required": [ "id" ], "additionalProperties": false }, "app": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^app_[A-Za-z0-9-]+$" }, "name": { "type": "string" }, "verified": { "type": "boolean" } }, "required": [ "id", "name", "verified" ], "additionalProperties": false }, "grant": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^apg_[A-Za-z0-9-]+$" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "cards:read", "cards:read:all", "cards:answer", "cards:reply", "cards:later", "cards:delegate", "assistants:read", "presence:desk" ] } }, "reach": { "type": "string", "enum": [ "machine", "all" ] }, "machine": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^mch_[A-Za-z0-9-]+$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "dpop": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "scopes", "reach", "dpop", "createdAt", "expiresAt" ], "additionalProperties": false } }, "required": [ "user", "workspace", "app", "grant" ], "additionalProperties": false }, "Card": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^req_[A-Za-z0-9-]+$" }, "version": { "type": "integer", "exclusiveMinimum": 0 }, "status": { "type": "string", "enum": [ "pending", "delegated", "answered", "resolved", "snoozed", "expired", "cancelled" ] }, "turn": { "type": "string", "enum": [ "you", "agent" ] }, "kind": { "type": "string", "enum": [ "choice", "multi", "approve", "text", "review", "action", "fyi", "group" ] }, "intent": { "type": "string", "enum": [ "decide", "approve", "do", "tell", "heads_up" ] }, "title": { "type": "string" }, "summary": { "type": "string" }, "urgency": { "type": "string", "enum": [ "now", "today", "whenever" ] }, "blocking": { "type": "boolean" }, "fallback": { "type": "object", "properties": { "text": { "type": "string" }, "at": { "type": "string", "format": "date-time" } }, "required": [ "text", "at" ], "additionalProperties": false }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string", "maxLength": 80 }, "detail": { "type": "string", "maxLength": 200 }, "consequence": { "type": "string", "maxLength": 200 }, "sends": { "type": "object", "properties": { "to": { "type": "string", "maxLength": 120 } }, "required": [ "to" ], "additionalProperties": false } }, "required": [ "id", "label" ], "additionalProperties": false } }, "recommendedIds": { "type": "array", "items": { "type": "string" } }, "rationale": { "type": "string" }, "multi": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "required": [ "min", "max" ], "additionalProperties": false }, "approve": { "type": "object", "properties": { "action": { "type": "string" }, "command": { "type": "string" }, "risk": { "type": "string", "enum": [ "low", "medium", "high" ] }, "reversible": { "type": "boolean" }, "because": { "type": "string", "enum": [ "spends", "irreversible", "public" ] } }, "required": [ "action", "risk", "reversible" ], "additionalProperties": false }, "text": { "type": "object", "properties": { "placeholder": { "type": "string" }, "suggestions": { "type": "array", "items": { "type": "string" } }, "long": { "type": "boolean" } }, "required": [ "placeholder" ], "additionalProperties": false }, "action": { "type": "object", "properties": { "where": { "type": "string" }, "steps": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "text": { "type": "string" }, "command": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false } ] } }, "done": { "type": "string" }, "command": { "type": "string" }, "verify": { "type": "string" } }, "required": [ "steps" ], "additionalProperties": false }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,40}$" }, "kind": { "type": "string", "enum": [ "choice", "multi", "approve", "text" ] }, "title": { "type": "string", "maxLength": 140 }, "detail": { "type": "string", "maxLength": 200 }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string", "maxLength": 80 }, "detail": { "type": "string", "maxLength": 200 }, "consequence": { "type": "string", "maxLength": 200 }, "sends": { "type": "object", "properties": { "to": { "type": "string", "maxLength": 120 } }, "required": [ "to" ], "additionalProperties": false } }, "required": [ "id", "label" ], "additionalProperties": false } }, "recommendedIds": { "type": "array", "items": { "type": "string" } }, "rationale": { "type": "string", "maxLength": 200 }, "multi": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" } }, "required": [ "min", "max" ], "additionalProperties": false }, "approve": { "type": "object", "properties": { "action": { "type": "string" }, "command": { "type": "string" }, "risk": { "type": "string", "enum": [ "low", "medium", "high" ] }, "reversible": { "type": "boolean" }, "because": { "type": "string", "enum": [ "spends", "irreversible", "public" ] } }, "required": [ "action", "risk", "reversible" ], "additionalProperties": false }, "highStakes": { "type": "boolean" }, "text": { "type": "object", "properties": { "placeholder": { "type": "string" }, "suggestions": { "type": "array", "items": { "type": "string" } }, "long": { "type": "boolean" } }, "required": [ "placeholder" ], "additionalProperties": false } }, "required": [ "id", "kind", "title" ], "additionalProperties": false } }, "about": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "email", "pr", "booking", "document", "other" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "ref": { "type": "string", "minLength": 1, "maxLength": 300 } }, "required": [ "kind", "title" ], "additionalProperties": false }, "threadId": { "type": "string", "pattern": "^req_[A-Za-z0-9-]+$" }, "follows": { "type": "string", "pattern": "^req_[A-Za-z0-9-]+$" }, "highStakes": { "type": "boolean" }, "actions": { "type": "array", "items": { "type": "string", "enum": [ "answer", "undo", "reply", "later", "back", "delegate", "take_back" ] } }, "area": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^prj_[A-Za-z0-9-]+$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "asker": { "type": "object", "properties": { "assistant": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^con_[A-Za-z0-9-]+$" }, "name": { "type": "string" }, "app": { "type": "string", "enum": [ "claude-code", "codex", "cursor", "gemini-cli", "opencode", "pi", "grok", "muse", "chatgpt", "claude", "dots", "other", "webhook" ] }, "appName": { "type": "string" } }, "required": [ "id", "name", "app", "appName" ], "additionalProperties": false }, "agent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^agt_[A-Za-z0-9-]+$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "task": { "type": "object", "properties": { "label": { "type": "string" }, "cwd": { "type": "string" }, "branch": { "type": "string" } }, "required": [ "label" ], "additionalProperties": false }, "machine": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^mch_[A-Za-z0-9-]+$" }, "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "assistant", "task" ], "additionalProperties": false }, "askedFirst": { "type": "object", "properties": { "where": { "type": "string", "enum": [ "terminal", "chat" ] }, "at": { "type": "string", "format": "date-time" }, "why": { "type": "string", "enum": [ "quiet", "away" ] } }, "required": [ "where", "at" ], "additionalProperties": false }, "answer": { "$ref": "#/components/schemas/Answer" }, "undoUntil": { "type": "string", "format": "date-time" }, "snoozedUntil": { "type": "string", "format": "date-time" }, "delegation": { "type": "object", "properties": { "to": { "type": "object", "properties": { "assistantId": { "type": "string", "pattern": "^con_[A-Za-z0-9-]+$" }, "agentId": { "type": "string", "pattern": "^agt_[A-Za-z0-9-]+$" } }, "required": [ "assistantId" ], "additionalProperties": false }, "mode": { "type": "string", "enum": [ "freely", "loop" ] }, "state": { "type": "string", "enum": [ "working", "suggested", "answered", "returned", "taken_back" ] }, "at": { "type": "string", "format": "date-time" } }, "required": [ "to", "mode", "state", "at" ], "additionalProperties": false }, "ask": { "type": "object", "properties": { "id": { "type": "string" }, "from": { "type": "string", "enum": [ "helper", "asker" ] }, "name": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string", "maxLength": 80 }, "detail": { "type": "string", "maxLength": 200 }, "consequence": { "type": "string", "maxLength": 200 }, "sends": { "type": "object", "properties": { "to": { "type": "string", "maxLength": 120 } }, "required": [ "to" ], "additionalProperties": false } }, "required": [ "id", "label" ], "additionalProperties": false } }, "recommendedIds": { "type": "array", "items": { "type": "string" } }, "rationale": { "type": "string" }, "highStakes": { "type": "boolean" }, "at": { "type": "string", "format": "date-time" }, "answered": { "type": "object", "properties": { "choiceIds": { "type": "array", "items": { "type": "string" } }, "text": { "type": "string" }, "note": { "type": "string" }, "answeredAt": { "type": "string", "format": "date-time" } }, "required": [ "answeredAt" ], "additionalProperties": false } }, "required": [ "id", "from", "name", "title", "highStakes", "at" ], "additionalProperties": false }, "context": { "type": "object", "properties": { "background": { "type": "string" }, "trace": { "type": "array", "items": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "done", "paused", "warn", "failed" ] }, "text": { "type": "string" } }, "required": [ "state", "text" ], "additionalProperties": false } }, "filesTouched": { "type": "array", "items": { "type": "string" } }, "tried": { "type": "array", "items": { "type": "string" } }, "links": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" } }, "required": [ "label", "url" ], "additionalProperties": false } } }, "required": [ "background", "trace", "filesTouched", "tried", "links" ], "additionalProperties": false }, "artifacts": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "image", "diff", "url", "file", "draft", "code" ] }, "title": { "type": "string" }, "ref": { "type": "string" }, "attachmentId": { "type": "string" }, "upload": { "description": "image or file: true for an uploadUrl", "type": "boolean" }, "lines": { "type": "array", "items": { "type": "string" } }, "caption": { "type": "string" }, "lang": { "type": "string", "enum": [ "ts", "json", "shell", "sql", "yaml", "toml", "css", "markdown", "text" ] }, "startLine": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "kind", "title", "ref" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "path" }, "title": { "type": "string" }, "path": { "type": "string" }, "machine": { "type": "string" }, "bytes": { "type": "integer", "minimum": 0 }, "modifiedAt": { "type": "string", "format": "date-time" }, "note": { "type": "string" }, "fetch": { "type": "string" } }, "required": [ "kind", "title", "path" ], "additionalProperties": false } ] } }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" } }, "hasFiles": { "type": "boolean", "const": true }, "thread": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^msg_[A-Za-z0-9-]+$" }, "author": { "type": "string", "enum": [ "you", "agent", "pendingyou", "helper", "teammate" ] }, "teammate": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "body": { "type": "string" }, "via": { "type": "string", "enum": [ "voice", "text" ] }, "audioSeconds": { "type": "number" }, "attachmentIds": { "type": "array", "items": { "type": "string", "pattern": "^att_[A-Za-z0-9-]+$" } }, "app": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^app_[A-Za-z0-9-]+$" }, "name": { "type": "string", "minLength": 1, "maxLength": 40 }, "machine": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "id", "name" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "author", "body", "createdAt" ], "additionalProperties": false } }, "threadCount": { "type": "integer", "minimum": 0 }, "partial": { "type": "boolean", "const": true }, "url": { "type": "string", "format": "uri" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "version", "status", "turn", "kind", "title", "summary", "urgency", "blocking", "highStakes", "actions", "area", "asker", "threadCount", "url", "createdAt", "updatedAt" ], "additionalProperties": false }, "Answer": { "type": "object", "properties": { "answers": { "type": "object", "additionalProperties": { "type": "object", "properties": { "choiceIds": { "type": "array", "items": { "type": "string" } }, "approved": { "type": "boolean" }, "text": { "type": "string", "maxLength": 4000 }, "note": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 4000 }, "via": { "type": "string", "enum": [ "voice", "text" ] }, "audioSeconds": { "type": "number" } }, "required": [ "text", "via" ], "additionalProperties": false }, "theyDecide": { "type": "boolean" } }, "additionalProperties": false } }, "choiceIds": { "type": "array", "items": { "type": "string" } }, "approved": { "type": "boolean" }, "text": { "type": "string" }, "note": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 4000 }, "via": { "type": "string", "enum": [ "voice", "text" ] }, "audioSeconds": { "type": "number" } }, "required": [ "text", "via" ], "additionalProperties": false }, "theyDecide": { "type": "boolean" }, "failedStep": { "type": "integer", "exclusiveMinimum": 0 }, "by": { "type": "string", "enum": [ "you", "go-between", "helper", "teammate" ] }, "helper": { "type": "object", "properties": { "name": { "type": "string" }, "why": { "type": "string" }, "note": { "type": "string", "maxLength": 1000 } }, "required": [ "name", "why" ], "additionalProperties": false }, "where": { "type": "string", "enum": [ "app", "conversation" ] }, "app": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^app_[A-Za-z0-9-]+$" }, "name": { "type": "string", "minLength": 1, "maxLength": 40 }, "machine": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "id", "name" ], "additionalProperties": false }, "answeredAt": { "type": "string", "format": "date-time" } }, "required": [ "answeredAt" ], "additionalProperties": false }, "Attachment": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^att_[A-Za-z0-9-]+$" }, "place": { "type": "string", "enum": [ "card", "message", "answer" ] }, "title": { "type": "string" }, "contentType": { "type": "string" }, "bytes": { "type": "integer" }, "downloadUrl": { "type": "string", "format": "uri" }, "downloadExpiresAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "place", "title" ], "additionalProperties": false }, "CardList": { "type": "object", "properties": { "cards": { "type": "array", "items": { "$ref": "#/components/schemas/Card" } }, "counts": { "type": "object", "properties": { "pending": { "type": "integer", "minimum": 0 }, "waiting": { "type": "integer", "minimum": 0 }, "later": { "type": "integer", "minimum": 0 }, "delegated": { "type": "integer", "minimum": 0 }, "elsewhere": { "type": "integer", "minimum": 0 } }, "required": [ "pending", "waiting", "later", "delegated" ], "additionalProperties": false }, "next": { "type": "string" } }, "required": [ "cards", "counts" ], "additionalProperties": false }, "CardResponse": { "type": "object", "properties": { "card": { "$ref": "#/components/schemas/Card" } }, "required": [ "card" ], "additionalProperties": false }, "AnswerResponse": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^req_[A-Za-z0-9-]+$" }, "askId": { "type": "string" }, "status": { "type": "string", "const": "answered" }, "version": { "type": "integer", "exclusiveMinimum": 0 }, "undoUntil": { "type": "string", "format": "date-time" } }, "required": [ "id", "status", "version", "undoUntil" ], "additionalProperties": false }, "CardBack": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^req_[A-Za-z0-9-]+$" }, "status": { "type": "string", "const": "pending" }, "version": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "id", "status", "version" ], "additionalProperties": false }, "MessageResponse": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^req_[A-Za-z0-9-]+$" }, "messageId": { "type": "string", "pattern": "^msg_[A-Za-z0-9-]+$" }, "turn": { "type": "string", "const": "agent" }, "version": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "id", "messageId", "turn", "version" ], "additionalProperties": false }, "LaterResponse": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^req_[A-Za-z0-9-]+$" }, "status": { "type": "string", "const": "snoozed" }, "until": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "id", "status", "until", "version" ], "additionalProperties": false }, "DelegateResponse": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^req_[A-Za-z0-9-]+$" }, "status": { "type": "string", "const": "delegated" }, "version": { "type": "integer", "exclusiveMinimum": 0 }, "hears": { "type": "string", "enum": [ "instant", "every-15-min", "hourly", "while-working", "by-hand" ] }, "undoUntil": { "type": "string", "format": "date-time" } }, "required": [ "id", "status", "version", "undoUntil" ], "additionalProperties": false }, "ChangeList": { "type": "object", "properties": { "changes": { "type": "array", "items": { "$ref": "#/components/schemas/Change" } }, "cursor": { "type": "string" }, "more": { "type": "boolean" } }, "required": [ "changes", "cursor", "more" ], "additionalProperties": false }, "Change": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "card.created", "card.answered", "card.changed", "card.closed" ] }, "cardId": { "type": "string", "pattern": "^req_[A-Za-z0-9-]+$" }, "at": { "type": "string", "format": "date-time" } }, "required": [ "type", "cardId", "at" ], "additionalProperties": false }, "AssistantList": { "type": "object", "properties": { "assistants": { "type": "array", "items": { "$ref": "#/components/schemas/Assistant" } } }, "required": [ "assistants" ], "additionalProperties": false }, "Assistant": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^con_[A-Za-z0-9-]+$" }, "app": { "type": "string", "enum": [ "claude-code", "codex", "cursor", "gemini-cli", "opencode", "pi", "grok", "muse", "chatgpt", "claude", "dots", "other", "webhook" ] }, "appName": { "type": "string" }, "name": { "type": "string" }, "machine": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^mch_[A-Za-z0-9-]+$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "hears": { "type": "string", "enum": [ "instant", "every-15-min", "hourly", "while-working", "by-hand" ] }, "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^agt_[A-Za-z0-9-]+$" }, "name": { "type": "string" }, "about": { "type": "string" }, "state": { "type": "string", "enum": [ "live", "recent", "quiet" ] }, "liveAt": { "type": "string", "format": "date-time" }, "closedAt": { "type": "string", "format": "date-time" }, "openCards": { "type": "integer", "minimum": 0 }, "liveSessions": { "type": "array", "items": { "type": "object", "properties": { "appSessionId": { "type": "string" }, "cwd": { "type": "string" }, "areaId": { "type": "string", "pattern": "^prj_[A-Za-z0-9-]+$" }, "liveAt": { "type": "string", "format": "date-time" }, "terminal": { "type": "object", "properties": { "app": { "type": "string", "const": "herdr" }, "paneId": { "type": "string" }, "server": { "type": "string" } }, "required": [ "app", "paneId" ], "additionalProperties": false } }, "required": [ "appSessionId", "liveAt" ], "additionalProperties": false } } }, "required": [ "id", "name", "state", "openCards", "liveSessions" ], "additionalProperties": false } } }, "required": [ "id", "app", "appName", "name", "agents" ], "additionalProperties": false }, "Problem": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string", "enum": [ "invalid", "app_not_available", "high_stakes", "area_change", "not_your_answer", "forbidden", "not_found", "method_not_allowed", "version_conflict", "not_waiting", "hold_over", "delegated", "conflict", "idempotency_in_progress", "idempotency_mismatch", "rate_limited", "server_error", "not_available", "unavailable" ] }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string" } }, "reason": { "type": "string" }, "why": { "type": "string", "enum": [ "disabled", "unverified", "not_registered", "off" ] }, "url": { "type": "string", "format": "uri" }, "currentVersion": { "type": "integer" }, "cardStatus": { "type": "string", "enum": [ "pending", "delegated", "answered", "resolved", "snoozed", "expired", "cancelled" ] }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0 }, "scope": { "type": "string", "enum": [ "read", "write", "answers", "wait", "workspace" ] } }, "required": [ "type", "title", "status", "code", "detail" ], "additionalProperties": false }, "ListCardsQuery": { "type": "object", "properties": { "status": { "default": "pending", "type": "string", "enum": [ "pending", "snoozed", "delegated", "done" ] }, "area": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string", "pattern": "^prj_[A-Za-z0-9-]+$" } }, "assistant": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string", "pattern": "^con_[A-Za-z0-9-]+$" } }, "agent": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string", "pattern": "^agt_[A-Za-z0-9-]+$" } }, "app": { "minItems": 1, "maxItems": 13, "type": "array", "items": { "type": "string", "enum": [ "claude-code", "codex", "cursor", "gemini-cli", "opencode", "pi", "grok", "muse", "chatgpt", "claude", "dots", "other", "webhook" ] } }, "machine": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "string", "pattern": "^mch_[A-Za-z0-9-]+$" } }, "threadId": { "type": "string", "pattern": "^req_[A-Za-z0-9-]+$" }, "limit": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "whole": { "default": 1, "type": "integer", "minimum": 0, "maximum": 3 }, "after": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false }, "AnswerRequest": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0 }, "choiceIds": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string" } }, "approved": { "type": "boolean" }, "text": { "type": "string", "minLength": 1, "maxLength": 4000 }, "note": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 4000 }, "via": { "default": "text", "type": "string", "enum": [ "text", "voice" ] } }, "required": [ "text" ], "additionalProperties": false }, "theyDecide": { "type": "boolean", "const": true }, "answers": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,40}$" }, "additionalProperties": { "type": "object", "properties": { "choiceIds": { "type": "array", "items": { "type": "string" } }, "approved": { "type": "boolean" }, "text": { "type": "string", "maxLength": 4000 }, "note": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 4000 }, "via": { "type": "string", "enum": [ "voice", "text" ] }, "audioSeconds": { "type": "number" } }, "required": [ "text", "via" ], "additionalProperties": false }, "theyDecide": { "type": "boolean" } }, "additionalProperties": false } }, "failedStep": { "type": "integer", "exclusiveMinimum": 0 }, "askId": { "type": "string", "pattern": "^ask_[A-Za-z0-9-]+$" } }, "required": [ "version" ], "additionalProperties": false }, "UndoRequest": { "type": "object", "properties": {}, "additionalProperties": false }, "MessageRequest": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 2000 }, "via": { "default": "text", "type": "string", "enum": [ "text", "voice" ] } }, "required": [ "body" ], "additionalProperties": false }, "LaterRequest": { "type": "object", "properties": { "until": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "enum": [ "1h", "tonight", "tomorrow" ] } ], "description": "A time, or a preset: in an hour, tonight (6:00 PM) or tomorrow morning (8:00 AM), in timeZone." }, "timeZone": { "description": "The person’s IANA time zone, e.g. \"America/Chicago\", for the presets. Default UTC.", "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "until" ], "additionalProperties": false }, "BackRequest": { "type": "object", "properties": {}, "additionalProperties": false }, "DelegateRequest": { "type": "object", "properties": { "to": { "type": "object", "properties": { "assistantId": { "type": "string", "pattern": "^con_[A-Za-z0-9-]+$" }, "agentId": { "type": "string", "pattern": "^agt_[A-Za-z0-9-]+$" } }, "required": [ "assistantId" ], "additionalProperties": false }, "mode": { "type": "string", "enum": [ "freely", "loop" ] }, "note": { "type": "string", "minLength": 1, "maxLength": 400 } }, "required": [ "to", "mode" ], "additionalProperties": false }, "TakeBackRequest": { "type": "object", "properties": {}, "additionalProperties": false }, "ChangesQuery": { "type": "object", "properties": { "after": { "type": "string", "minLength": 1, "maxLength": 200 }, "wait": { "default": 0, "type": "integer", "minimum": 0, "maximum": 25 }, "limit": { "default": 100, "type": "integer", "minimum": 1, "maximum": 100 } }, "additionalProperties": false }, "PresenceRequest": { "type": "object", "properties": { "here": { "type": "boolean" } }, "required": [ "here" ], "additionalProperties": false } }, "securitySchemes": { "oauth2": { "type": "oauth2", "description": "OAuth 2.1 at Pending You, for the resource `/v1`. Public apps’ tokens are DPoP-bound (`x-pendingyou-dpop`): send them as `Authorization: DPoP ` with a proof.", "flows": { "authorizationCode": { "authorizationUrl": "https://www.pendingyou.com/oauth/authorize", "tokenUrl": "https://www.pendingyou.com/oauth/token", "refreshUrl": "https://www.pendingyou.com/oauth/token", "scopes": { "cards:read": "See the cards the assistants on the signed-in computer ask the person.", "cards:read:all": "See every card, from all the person’s computers and assistants.", "cards:answer": "Answer cards when the person presses something, and take an answer back in its 5 seconds.", "cards:reply": "Write to the assistant that asked, on its card.", "cards:later": "Put cards in Later and bring them back.", "cards:delegate": "Hand a card to another of the person’s assistants, and take it back.", "assistants:read": "See which assistants are running, and in which terminal.", "presence:desk": "Keep the person’s phone quiet while they’re using the app." } }, "x-pendingyou-device": { "description": "RFC 8628 for terminals and plugins: POST the form to `deviceAuthorizationUrl` with the app (`app` for Pending You’s own apps, else `client_id`), `scope`, `resource`, `machine` and `machine_attestation` (the computer’s key vouching for this sign-in and the grant’s DPoP key, `pendingyou machine attest`). The person allows it on their phone or at `verification_uri`; poll `tokenUrl` with `grant_type` below, a DPoP proof each time.", "deviceAuthorizationUrl": "https://www.pendingyou.com/oauth/device", "tokenUrl": "https://www.pendingyou.com/oauth/token", "refreshUrl": "https://www.pendingyou.com/oauth/token", "grantType": "urn:ietf:params:oauth:grant-type:device_code", "resource": "https://www.pendingyou.com/v1", "scopes": { "cards:read": "See the cards the assistants on the signed-in computer ask the person.", "cards:read:all": "See every card, from all the person’s computers and assistants.", "cards:answer": "Answer cards when the person presses something, and take an answer back in its 5 seconds.", "cards:reply": "Write to the assistant that asked, on its card.", "cards:later": "Put cards in Later and bring them back.", "cards:delegate": "Hand a card to another of the person’s assistants, and take it back.", "assistants:read": "See which assistants are running, and in which terminal.", "presence:desk": "Keep the person’s phone quiet while they’re using the app." } } } } }, "parameters": { "CardId": { "name": "id", "in": "path", "required": true, "description": "The card (`req_…`).", "schema": { "type": "string", "pattern": "^req_[A-Za-z0-9-]{1,64}$" } }, "PendingYouVersion": { "name": "Pending-You-Version", "in": "header", "required": false, "description": "The dated behaviour to follow. Without it: the app’s registered version.", "schema": { "type": "string", "enum": [ "2026-10-05" ] } }, "DPoP": { "name": "DPoP", "in": "header", "required": false, "description": "The request’s DPoP proof, for a bound token (every public app’s).", "schema": { "type": "string" } }, "IfNoneMatch": { "name": "If-None-Match", "in": "header", "required": false, "description": "The ETag you hold: 304 when nothing changed.", "schema": { "type": "string" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "8 to 200 visible characters. The same key and request within 24 hours get the first answer again.", "schema": { "type": "string", "pattern": "^[\\x21-\\x7E]{8,200}$" } }, "IdempotencyKeyRequired": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "8 to 200 visible characters, a new one for each answer. The same key and request within 24 hours get the first answer again.", "schema": { "type": "string", "pattern": "^[\\x21-\\x7E]{8,200}$" } } }, "headers": { "PendingYouVersion": { "description": "The dated behaviour this answer followed.", "schema": { "type": "string" } }, "DPoPNonce": { "description": "The current DPoP nonce: put it in your next proof.", "schema": { "type": "string" } }, "ETag": { "description": "Send it as If-None-Match to hear 304.", "schema": { "type": "string" } }, "IdempotentReplayed": { "description": "`true`: the first answer to this Idempotency-Key, again.", "schema": { "type": "string" } } } }, "x-pendingyou-dpop": { "required": "Every sign-in by device code; every public app.", "algs": [ "ES256" ], "proofHeader": "DPoP", "tokenType": "DPoP", "nonceHeader": "DPoP-Nonce", "claims": { "jti": "At least 96 random bits, once per key.", "htm": "The request’s method.", "htu": "The request’s address, without its query or fragment.", "iat": "When it was made, within 60 seconds of Pending You’s clock.", "ath": "At /v1: the access token’s SHA-256, base64url.", "nonce": "The last DPoP-Nonce Pending You sent: required at the token endpoint, optional at /v1." }, "useDpopNonce": "Asked for a current nonce: 400 at the token endpoint, 401 at /v1, with a DPoP-Nonce header. Make the proof again with it and send the request once more." }, "x-pendingyou-limits": { "read": "300 a minute per sign-in (every GET)", "write": "60 a minute per sign-in (every POST)", "answers": "30 a minute per sign-in (answers and words on a card)", "wait": "6 waits a minute per sign-in (GET /v1/changes with wait, up to 25 seconds)", "workspace": "1,200 a minute per person, every app together" } }