{ "openapi": "3.1.0", "info": { "title": "Pocket Clear read-only API", "version": "1.0.0", "summary": "Read-only access to a Pocket Clear user's synced spending data for AI assistants.", "description": "Read-only access to one Pocket Clear user's synced data, for AI assistants. Every endpoint is a GET; nothing can change the user's data.\n\n**Authentication — two equivalent forms.**\n\n1. `Authorization: Bearer pcai_…` on `https://api.pocketclear.app/api/ai/v1/` (the `bearerAuth` scheme).\n2. Token in the path, for tools that can only fetch a plain URL: `https://api.pocketclear.app/api/ai/v1/t/{token}/` — for example `/t/pcai_…/summary?month=2026-10`. Same endpoints, parameters and responses as the paths below.\n\nDo not show the token back to the user or put it in links you show them.\n\n**Conventions.** Amounts are plain positive numbers in the user's home currency (`currency` from /me). Dates are inclusive local dates in the user's time zone; with no dates, endpoints use the current calendar month. Transfers, lend/borrow rows and savings set-asides are never income or spending. Only the token owner's own data is returned (including entries a partner logged on their behalf). Notes appear only when the user included them for this token.\n\n**Limits.** 60 requests a minute and 2,000 a day per token (429 + Retry-After). Responses carry `Cache-Control: no-store`.\n\nHuman-readable reference: https://pocketclear.app/developers/ — Markdown reference for assistants: https://pocketclear.app/developers/api.md", "contact": { "name": "Pocket Clear", "email": "hello@pocketclear.app", "url": "https://pocketclear.app/developers/" }, "termsOfService": "https://pocketclear.app/terms.html" }, "externalDocs": { "description": "API reference for assistants (Markdown)", "url": "https://pocketclear.app/developers/api.md" }, "servers": [ { "url": "https://api.pocketclear.app/api/ai/v1", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/me": { "get": { "operationId": "getProfile", "summary": "Profile and token facts", "description": "Currency, secondary currency, time zone, period settings (as captured when the token was created), partner status and what this token can read. No email or name. Call this first.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "400": { "description": "`bad_request` — A parameter is wrong; the message says which.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`invalid_token | token_expired | token_revoked` — The token is wrong, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`pro_required` — The owner's Pocket Clear Pro has lapsed; the token works again once Pro is renewed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`cloud_sync_off` — Cloud Sync is off, so there is no data on the server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` — 60 requests a minute and 2,000 a day per token. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "`server_error` — Retry once, then tell the user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/summary": { "get": { "operationId": "getSummary", "summary": "Totals for a date range", "description": "Money in, money out, net, savings set aside, spending and income by category (refunds netted against the category they refund) and by month. Transfers, lend/borrow rows and savings set-asides are never income or spending. For a year view pass from=YYYY-01-01&to=YYYY-12-31 and use byMonth.", "parameters": [ { "$ref": "#/components/parameters/from" }, { "$ref": "#/components/parameters/to" }, { "$ref": "#/components/parameters/month" }, { "$ref": "#/components/parameters/tz" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Summary" } } } }, "400": { "description": "`bad_request` — A parameter is wrong; the message says which.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`invalid_token | token_expired | token_revoked` — The token is wrong, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`pro_required` — The owner's Pocket Clear Pro has lapsed; the token works again once Pro is renewed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`cloud_sync_off` — Cloud Sync is off, so there is no data on the server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` — 60 requests a minute and 2,000 a day per token. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "`server_error` — Retry once, then tell the user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/transactions": { "get": { "operationId": "listTransactions", "summary": "Transactions, newest first", "description": "Keyset-paginated. Keep calling with `cursor` = `nextCursor` until it is null when you need every row; prefer /summary for totals. A `category` that matches nothing returns an empty page with a `notice`.", "parameters": [ { "$ref": "#/components/parameters/from" }, { "$ref": "#/components/parameters/to" }, { "$ref": "#/components/parameters/month" }, { "$ref": "#/components/parameters/tz" }, { "name": "category", "in": "query", "description": "A category name (case-insensitive, e.g. `Groceries`) or id.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "income", "expense", "transfer" ] } }, { "name": "q", "in": "query", "description": "Text search over payee, category, subcategory, payment type, tags and loan person (and notes, only when notes are included). Max 200 characters.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "description": "Page size, default 100; values above 500 are capped at 500.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "cursor", "in": "query", "description": "`nextCursor` from the previous page.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionsPage" } } } }, "400": { "description": "`bad_request` — A parameter is wrong; the message says which.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`invalid_token | token_expired | token_revoked` — The token is wrong, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`pro_required` — The owner's Pocket Clear Pro has lapsed; the token works again once Pro is renewed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`cloud_sync_off` — Cloud Sync is off, so there is no data on the server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` — 60 requests a minute and 2,000 a day per token. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "`server_error` — Retry once, then tell the user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/categories": { "get": { "operationId": "listCategories", "summary": "Categories and subcategories", "description": "The user's own labels, in their language.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Categories" } } } }, "400": { "description": "`bad_request` — A parameter is wrong; the message says which.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`invalid_token | token_expired | token_revoked` — The token is wrong, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`pro_required` — The owner's Pocket Clear Pro has lapsed; the token works again once Pro is renewed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`cloud_sync_off` — Cloud Sync is off, so there is no data on the server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` — 60 requests a minute and 2,000 a day per token. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "`server_error` — Retry once, then tell the user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/budgets": { "get": { "operationId": "getBudgets", "summary": "Budgets with spending over a range", "description": "`spentInRange` is spending over exactly the range passed — for a monthly budget pass that month, for weekly pass the week. Monthly budgets with per-month amounts use the amount for the month of `from`. Rollover is not included.", "parameters": [ { "$ref": "#/components/parameters/from" }, { "$ref": "#/components/parameters/to" }, { "$ref": "#/components/parameters/month" }, { "$ref": "#/components/parameters/tz" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Budgets" } } } }, "400": { "description": "`bad_request` — A parameter is wrong; the message says which.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`invalid_token | token_expired | token_revoked` — The token is wrong, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`pro_required` — The owner's Pocket Clear Pro has lapsed; the token works again once Pro is renewed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`cloud_sync_off` — Cloud Sync is off, so there is no data on the server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` — 60 requests a minute and 2,000 a day per token. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "`server_error` — Retry once, then tell the user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/goals": { "get": { "operationId": "listGoals", "summary": "Savings goals with progress", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Goals" } } } }, "400": { "description": "`bad_request` — A parameter is wrong; the message says which.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`invalid_token | token_expired | token_revoked` — The token is wrong, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`pro_required` — The owner's Pocket Clear Pro has lapsed; the token works again once Pro is renewed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`cloud_sync_off` — Cloud Sync is off, so there is no data on the server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` — 60 requests a minute and 2,000 a day per token. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "`server_error` — Retry once, then tell the user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts": { "get": { "operationId": "listAccounts", "summary": "Payment types with all-time balances", "description": "`balance` = opening balance + money in − money out; transfers count on both accounts; savings set-asides are not counted (the app's default). A row named \"No payment method\" collects entries without one.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Accounts" } } } }, "400": { "description": "`bad_request` — A parameter is wrong; the message says which.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`invalid_token | token_expired | token_revoked` — The token is wrong, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`pro_required` — The owner's Pocket Clear Pro has lapsed; the token works again once Pro is renewed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`cloud_sync_off` — Cloud Sync is off, so there is no data on the server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` — 60 requests a minute and 2,000 a day per token. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "`server_error` — Retry once, then tell the user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "pcai_<64 hex>", "description": "A read-only token the user creates in Pocket Clear → Settings → Connect an AI assistant. Alternatively put it in the path: /t/{token}/." } }, "parameters": { "from": { "name": "from", "in": "query", "description": "Inclusive start date (YYYY-MM-DD) in the user's time zone. Default: first day of the current month. With only `from`, the range runs to today.", "schema": { "type": "string", "format": "date" } }, "to": { "name": "to", "in": "query", "description": "Inclusive end date (YYYY-MM-DD). Default: last day of the current month.", "schema": { "type": "string", "format": "date" } }, "month": { "name": "month", "in": "query", "description": "Shortcut for a whole calendar month, YYYY-MM. Takes precedence over from/to.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" } }, "tz": { "name": "tz", "in": "query", "description": "IANA time zone overriding the one captured with the token.", "schema": { "type": "string" } } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_token", "token_expired", "token_revoked", "pro_required", "cloud_sync_off", "not_found", "method_not_allowed", "rate_limited", "server_error" ] }, "message": { "type": "string" }, "docs": { "type": "string", "format": "uri" } }, "required": [ "error", "message" ] }, "Range": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "timeZone": { "type": "string" } }, "required": [ "from", "to", "timeZone" ] }, "Truncated": { "type": "boolean", "description": "True when the account is very large and the figures cover only the most recently edited 50,000 transactions — tell the user they are partial." }, "Me": { "type": "object", "properties": { "app": { "const": "Pocket Clear" }, "apiVersion": { "const": "v1" }, "currency": { "type": "string", "description": "ISO 4217 code; every amount in the API is in this currency." }, "secondaryCurrency": { "type": [ "string", "null" ] }, "timeZone": { "type": "string" }, "periodSettings": { "type": [ "object", "null" ], "properties": { "viewPeriod": { "type": "string" }, "periodStartDay": { "type": "integer" }, "note": { "type": "string" } } }, "hasPartner": { "type": "boolean" }, "dataScope": { "const": "own" }, "notesIncluded": { "type": "boolean" }, "readOnly": { "const": true }, "tokenExpiresAt": { "type": "string", "format": "date-time" }, "docs": { "type": "string", "format": "uri" } } }, "Summary": { "type": "object", "properties": { "currency": { "type": "string" }, "range": { "$ref": "#/components/schemas/Range" }, "totals": { "type": "object", "properties": { "moneyIn": { "type": "number" }, "moneyOut": { "type": "number" }, "net": { "type": "number" }, "refundsIncludedInMoneyIn": { "type": "number" }, "savingsSetAside": { "type": "number" }, "savingsWithdrawn": { "type": "number" }, "transactionCount": { "type": "integer" } } }, "spendingByCategory": { "type": "array", "items": { "type": "object", "properties": { "categoryId": { "type": "string" }, "category": { "type": "string" }, "amount": { "type": "number" }, "share": { "type": "number", "description": "Percentage of total spending." } } } }, "incomeByCategory": { "type": "array", "items": { "type": "object", "properties": { "categoryId": { "type": "string" }, "category": { "type": "string" }, "amount": { "type": "number" } } } }, "byMonth": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" }, "moneyIn": { "type": "number" }, "moneyOut": { "type": "number" }, "net": { "type": "number" } } } }, "excludedFromTotals": { "type": "object", "properties": { "transfers": { "type": "integer" }, "loanRows": { "type": "integer" } } }, "rules": { "type": "string" }, "truncated": { "$ref": "#/components/schemas/Truncated" } } }, "Transaction": { "type": "object", "properties": { "id": { "type": "string" }, "date": { "type": "string", "format": "date" }, "dateTime": { "type": "string", "format": "date-time" }, "amount": { "type": "number", "description": "Always positive; `type` / `kind` gives the direction." }, "type": { "type": "string", "enum": [ "income", "expense" ] }, "kind": { "type": "string", "enum": [ "expense", "income", "refund", "transfer", "loan", "loan_repayment", "savings_set_aside", "savings_withdrawal" ] }, "countsInTotals": { "type": "boolean", "description": "Only expense, income and refund count toward totals." }, "category": { "type": [ "string", "null" ] }, "categoryId": { "type": [ "string", "null" ] }, "subcategory": { "type": [ "string", "null" ] }, "paymentType": { "type": [ "string", "null" ] }, "payee": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "transferTo": { "type": "string" }, "loan": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "loan", "repayment" ] }, "person": { "type": "string" }, "dueDate": { "type": "string", "format": "date" } } }, "note": { "type": "string", "description": "Present only when the user included notes for this token." } } }, "TransactionsPage": { "type": "object", "properties": { "currency": { "type": "string" }, "range": { "$ref": "#/components/schemas/Range" }, "count": { "type": "integer" }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } }, "nextCursor": { "type": [ "string", "null" ] }, "truncated": { "$ref": "#/components/schemas/Truncated" }, "notice": { "type": "string" } } }, "Categories": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "income", "expense" ] }, "icon": { "type": "string" }, "sharedByPartner": { "type": "boolean" }, "subcategories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } } } } } }, "Budgets": { "type": "object", "properties": { "currency": { "type": "string" }, "range": { "$ref": "#/components/schemas/Range" }, "budgets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "overall", "category", "subcategory" ] }, "category": { "type": [ "string", "null" ] }, "subcategory": { "type": [ "string", "null" ] }, "period": { "type": "string" }, "limit": { "type": "number" }, "spentInRange": { "type": "number" }, "remaining": { "type": "number" }, "percentUsed": { "type": "number" } } } }, "note": { "type": "string" }, "truncated": { "$ref": "#/components/schemas/Truncated" } } }, "Goals": { "type": "object", "properties": { "currency": { "type": "string" }, "goals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "targetAmount": { "type": "number" }, "currentAmount": { "type": "number" }, "remaining": { "type": "number" }, "percentComplete": { "type": "number" }, "deadline": { "type": [ "string", "null" ], "format": "date" } } } } } }, "Accounts": { "type": "object", "properties": { "currency": { "type": "string" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "sharedByPartner": { "type": "boolean" }, "openingBalance": { "type": "number" }, "moneyInAllTime": { "type": "number" }, "moneyOutAllTime": { "type": "number" }, "balance": { "type": "number" } } } }, "note": { "type": "string" }, "truncated": { "$ref": "#/components/schemas/Truncated" } } } } } }