{"openapi":"3.1.0","info":{"title":"YNAB (BYOK) API","version":"0.1.0","description":"YNAB (BYOK) lets an AI assistant read your own YNAB data through the YNAB API with a key you supply (personal access token). Read-only: 10 tools (get_user, list_plans, list_accounts, list_categories, list_payees, list_months, get_month, list_transactions, list_account_transactions, list_scheduled_transactions). The BYOK key travels with each request, is used for that one call only and is never...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-ynab.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-ynab/docs"},"termsOfService":"https://connectorbay.com/byok-ynab/terms"},"servers":[{"url":"https://byok-ynab.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-ynab/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_user":{"post":{"operationId":"get_user","summary":"Show the ID of the YNAB user the token belongs to. Use for \"Which YNAB user is my token connected to\".","description":"Show the ID of the YNAB user the token belongs to. Use for \"Which YNAB user is my token connected to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_userArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_plans":{"post":{"operationId":"list_plans","summary":"List your plans (budgets) with ID, name, last modified time, first and last month and currency format, optionally with t","description":"List your plans (budgets) with ID, name, last modified time, first and last month and currency format, optionally with their accounts. Use for \"Which YNAB plans do I have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"include_accounts":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include each plan's accounts.","title":"Include Accounts"}},"title":"list_plansArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_accounts":{"post":{"operationId":"list_accounts","summary":"List a plan's accounts with type, on-budget and closed flags, balances and linked-import status. Amounts are in milliuni","description":"List a plan's accounts with type, on-budget and closed flags, balances and linked-import status. Amounts are in milliunits (1000 = one currency unit); the *_formatted fields are text. Use for \"What are my YNAB account balances\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"plan_id":{"description":"Plan (budget) ID, or 'last-used' for the plan last used in the app, or 'default' when a default plan is set. List plans with list_plans.","maxLength":200,"title":"Plan Id","type":"string"},"last_knowledge_of_server":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only items changed since this server_knowledge value from an earlier answer; leave empty for everything.","title":"Last Knowledge Of Server"}},"required":["plan_id"],"title":"list_accountsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_categories":{"post":{"operationId":"list_categories","summary":"List a plan's category groups with their categories, including budgeted, activity and available balance for the current ","description":"List a plan's category groups with their categories, including budgeted, activity and available balance for the current plan month and goal info. Amounts are in milliunits (1000 = one currency unit); the *_formatted fields are text. Use for \"How much is left in each YNAB category this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"plan_id":{"description":"Plan (budget) ID, or 'last-used' for the plan last used in the app, or 'default' when a default plan is set. List plans with list_plans.","maxLength":200,"title":"Plan Id","type":"string"},"last_knowledge_of_server":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only items changed since this server_knowledge value from an earlier answer; leave empty for everything.","title":"Last Knowledge Of Server"}},"required":["plan_id"],"title":"list_categoriesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_payees":{"post":{"operationId":"list_payees","summary":"List a plan's payees with ID, name and transfer account (for transfer payees). Use for \"Which payees exist in my YNAB pl","description":"List a plan's payees with ID, name and transfer account (for transfer payees). Use for \"Which payees exist in my YNAB plan\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"plan_id":{"description":"Plan (budget) ID, or 'last-used' for the plan last used in the app, or 'default' when a default plan is set. List plans with list_plans.","maxLength":200,"title":"Plan Id","type":"string"},"last_knowledge_of_server":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only items changed since this server_knowledge value from an earlier answer; leave empty for everything.","title":"Last Knowledge Of Server"}},"required":["plan_id"],"title":"list_payeesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_months":{"post":{"operationId":"list_months","summary":"List a plan's months with income, budgeted, activity, to-be-budgeted and age of money. Amounts are in milliunits (1000 =","description":"List a plan's months with income, budgeted, activity, to-be-budgeted and age of money. Amounts are in milliunits (1000 = one currency unit); the *_formatted fields are text. Use for \"How did my YNAB budget look month by month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"plan_id":{"description":"Plan (budget) ID, or 'last-used' for the plan last used in the app, or 'default' when a default plan is set. List plans with list_plans.","maxLength":200,"title":"Plan Id","type":"string"},"last_knowledge_of_server":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only items changed since this server_knowledge value from an earlier answer; leave empty for everything.","title":"Last Knowledge Of Server"}},"required":["plan_id"],"title":"list_monthsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_month":{"post":{"operationId":"get_month","summary":"Get one plan month with its totals and the budgeted, activity and balance of every category. Amounts are in milliunits (","description":"Get one plan month with its totals and the budgeted, activity and balance of every category. Amounts are in milliunits (1000 = one currency unit); the *_formatted fields are text. Use for \"Show my YNAB budget for this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"plan_id":{"description":"Plan (budget) ID, or 'last-used' for the plan last used in the app, or 'default' when a default plan is set. List plans with list_plans.","maxLength":200,"title":"Plan Id","type":"string"},"month":{"description":"Plan month as the first day in ISO format, for example '2026-10-01', or 'current' for the present month.","maxLength":200,"title":"Month","type":"string"}},"required":["plan_id","month"],"title":"get_monthArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_transactions":{"post":{"operationId":"list_transactions","summary":"List a plan's transactions (pending ones excluded), optionally from a date, until a date or only uncategorized or unappr","description":"List a plan's transactions (pending ones excluded), optionally from a date, until a date or only uncategorized or unapproved ones. Large plans can be big: use since_date. Amounts are in milliunits (1000 = one currency unit); the *_formatted fields are text. Use for \"What did I spend in YNAB since the first of the month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"plan_id":{"description":"Plan (budget) ID, or 'last-used' for the plan last used in the app, or 'default' when a default plan is set. List plans with list_plans.","maxLength":200,"title":"Plan Id","type":"string"},"since_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only transactions on or after this date, YYYY-MM-DD.","title":"Since Date"},"until_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only transactions on or before this date, YYYY-MM-DD.","title":"Until Date"},"type":{"anyOf":[{"enum":["uncategorized","unapproved"],"type":"string"},{"type":"null"}],"default":null,"description":"Only 'uncategorized' or 'unapproved' transactions.","title":"Type"},"last_knowledge_of_server":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only items changed since this server_knowledge value from an earlier answer; leave empty for everything.","title":"Last Knowledge Of Server"}},"required":["plan_id"],"title":"list_transactionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_account_transactions":{"post":{"operationId":"list_account_transactions","summary":"List the transactions of one account, optionally from a date or only uncategorized or unapproved ones. Amounts are in mi","description":"List the transactions of one account, optionally from a date or only uncategorized or unapproved ones. Amounts are in milliunits (1000 = one currency unit); the *_formatted fields are text. Use for \"Show recent transactions of my YNAB checking account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"plan_id":{"description":"Plan (budget) ID, or 'last-used' for the plan last used in the app, or 'default' when a default plan is set. List plans with list_plans.","maxLength":200,"title":"Plan Id","type":"string"},"account_id":{"description":"Account ID from list_accounts.","maxLength":200,"title":"Account Id","type":"string"},"since_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only transactions on or after this date, YYYY-MM-DD.","title":"Since Date"},"type":{"anyOf":[{"enum":["uncategorized","unapproved"],"type":"string"},{"type":"null"}],"default":null,"description":"Only 'uncategorized' or 'unapproved' transactions.","title":"Type"},"last_knowledge_of_server":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only items changed since this server_knowledge value from an earlier answer; leave empty for everything.","title":"Last Knowledge Of Server"}},"required":["plan_id","account_id"],"title":"list_account_transactionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_scheduled_transactions":{"post":{"operationId":"list_scheduled_transactions","summary":"List a plan's scheduled (recurring) transactions with first and next date, frequency, amount, payee and category. Amount","description":"List a plan's scheduled (recurring) transactions with first and next date, frequency, amount, payee and category. Amounts are in milliunits (1000 = one currency unit); the *_formatted fields are text. Use for \"What recurring transactions are scheduled in YNAB\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"plan_id":{"description":"Plan (budget) ID, or 'last-used' for the plan last used in the app, or 'default' when a default plan is set. List plans with list_plans.","maxLength":200,"title":"Plan Id","type":"string"},"last_knowledge_of_server":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only items changed since this server_knowledge value from an earlier answer; leave empty for everything.","title":"Last Knowledge Of Server"}},"required":["plan_id"],"title":"list_scheduled_transactionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}