The Pincher API provides many tools and resources that enable you to visualize your personal finances through an envelope-based framework, in which every dollar is assigned to a particular \"job\" or, as defined by the Pincher API, a category.
\nBy adding accounts to a single budget with values that mirror identical balances as seen in one or more banks, you can manage one pool of money, assigning any or all of the total to one or more categories that may be organized in groups.
\nThe Pincher API also allows you to add other users to the budgets you create, granting them limited sets of permissions to view, contribute to, or manage the resources that belong to them.
\nNOTE: Full documentation is currently in progress. Some endpoints may exist that are not yet documented.
\nTo start using the Pincher API, first follow the \"Get Started\" section listed on the public repository on Github.
\nBe aware that:
\nThe API stores amounts in the PostgreSQL database as numbers. It is recommended that transaction amounts are stored in the smallest unit of measure for any given currency, so that you do not lose precision. For example, if you were to log a transaction with a cost of $35 USD, you would measure it in US Cents: 3500.
The API returns request responses in JSON format. When an API request returns an error, it is sent in the JSON response as an error key.
\nThe Pincher API uses JSON Web Tokens for authentication, as well as a refresh token system that allows these access tokens to be shorter-lived for tighter security.
\nTo acquire an access token:
\nCreate a user
\nLog in with that user
\nUpon a successful response from the login endpoint, you should receive a JSON response body containing information about the user logged in, a token (your access token), and a refresh_token. Store the refresh token to provide later to an dedicated endpoint dedicated to acquiring new access tokens.
All budget-related endpoints, as well as those for deleting and updating users, will expect to find a valid access token in the Authorization header of the request(s) sent to them.
To acquire a new access token after an existing one expires, send a POST request to the /api/refresh endpoint with a valid refresh_token string included in the Authorization header. This will return a JSON response body including your new token. If the query ?with-user is included, information about the authenticated user will be included as well.
If a JWT is missing from the header you will receive an HTTP 400 response code.
\nIf a JWT is invalid, you will receive an HTTP 401 Unauthorized response code.
\nIf you're unfamiliar with envelope budgeting, you can read about it [here](https://en.wikipedia.org/wiki/Envelope_system).
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"📄 Get started here","slug":"get-started-here"}],"owner":"51711822","collectionId":"8601f817-735e-4ff1-ae0d-9cb7b36c6a6c","publishedId":"2sBXVkAUL6","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"F79269"},"publishDate":"2026-01-22T05:05:42.000Z"},"item":[{"name":"users","item":[{"name":"Create a user","id":"2b4f09ab-937b-4cf1-b316-05923190a5c9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"username\": \"{{username}}\",\n \"password\": \"{{password}}\"\n}","options":{"raw":{"language":"json"}}},"url":"http://{{pincher_instance}}/api/users","urlObject":{"protocol":"http","path":["api","users"],"host":["{{pincher_instance}}"],"query":[],"variable":[]}},"response":[{"id":"136e8df8-2a6e-4f25-95a8-151c17c42453","name":"Success","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"username\": \"{{username}}\",\n \"password\": \"{{password}}\"\n}","options":{"raw":{"language":"json"}}},"url":"http://{{pincher_instance}}/api/users"},"status":"Created","code":201,"_postman_previewlanguage":null,"header":[{"key":"Content-Type","value":"application/json"},{"key":"Date","value":"Wed, 21 Jan 2026 20:32:54 GMT"},{"key":"Content-Length","value":"149"}],"cookie":[],"responseTime":null,"body":"{\n \"id\": \"9dbd0552-4c90-41e4-af49-240311f740ba\",\n \"created_at\": \"2026-01-21T21:02:44.368291Z\",\n \"updated_at\": \"2026-01-21T21:02:44.368291Z\",\n \"username\": \"moss\"\n}"}],"_postman_id":"2b4f09ab-937b-4cf1-b316-05923190a5c9"},{"name":"Log in as a user","id":"bd6bcf65-98dc-4700-9437-9f674bfb7a07","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"username\": \"{{username}}\",\n \"password\": \"{{password}}\"\n}","options":{"raw":{"language":"json"}}},"url":"http://{{pincher_instance}}/api/login","urlObject":{"protocol":"http","path":["api","login"],"host":["{{pincher_instance}}"],"query":[],"variable":[]}},"response":[{"id":"6e091dd7-be75-49ac-a6d2-6b7c84a47d72","name":"Success","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"username\": \"{{username}}\",\n \"password\": \"{{password}}\"\n}","options":{"raw":{"language":"json"}}},"url":"http://{{pincher_instance}}/api/login"},"status":"OK","code":200,"_postman_previewlanguage":"","header":[{"key":"Content-Type","value":"application/json"},{"key":"Date","value":"Wed, 21 Jan 2026 20:36:16 GMT"},{"key":"Content-Length","value":"452"}],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"id\": \"9dbd0552-4c90-41e4-af49-240311f740ba\",\n \"created_at\": \"2026-01-21T21:02:44.368291Z\",\n \"updated_at\": \"2026-01-21T21:02:44.368291Z\",\n \"username\": \"moss\",\n \"token\": \"\",\n \"refresh_token\": \"\"\n}"}],"_postman_id":"bd6bcf65-98dc-4700-9437-9f674bfb7a07"},{"name":"Get new access token","id":"b9853b2f-4181-45c6-b16b-4127c9d57f66","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"Bearer {{refresh_token}}","type":"text"}],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":"http://{{pincher_instance}}/api/refresh","urlObject":{"protocol":"http","path":["api","refresh"],"host":["{{pincher_instance}}"],"query":[],"variable":[]}},"response":[{"id":"6cc2a746-31a2-4a11-8372-37e8cbdecfc5","name":"Success","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Bearer {{refresh_token}}","type":"text"}],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":"http://{{pincher_instance}}/api/refresh"},"status":"OK","code":200,"_postman_previewlanguage":"","header":[{"key":"Content-Type","value":"application/json"},{"key":"Date","value":"Wed, 21 Jan 2026 20:46:01 GMT"},{"key":"Content-Length","value":"221"}],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"token\": \"\"\n}"}],"_postman_id":"b9853b2f-4181-45c6-b16b-4127c9d57f66"},{"name":"Get new access token and associated user","id":"f549bf84-72c4-44af-b922-261406d38c87","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{refresh_token}}"}]},"isInherited":false},"method":"POST","header":[{"key":"Authorization","value":"Bearer {{refresh_token}}","type":"text"}],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":"http://{{pincher_instance}}/api/refresh?with-user","urlObject":{"protocol":"http","path":["api","refresh"],"host":["{{pincher_instance}}"],"query":[{"key":"with-user","value":null}],"variable":[]}},"response":[{"id":"e7723ccb-98d8-413b-9717-7ac1b7ed8ade","name":"Success","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Bearer {{refresh_token}}","type":"text"}],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":{"raw":"http://{{pincher_instance}}/api/refresh?with-user","protocol":"http","host":["{{pincher_instance}}"],"path":["api","refresh"],"query":[{"key":"with-user","value":null}]}},"status":"OK","code":200,"_postman_previewlanguage":"","header":[{"key":"Content-Type","value":"application/json"},{"key":"Date","value":"Wed, 21 Jan 2026 20:51:38 GMT"},{"key":"Content-Length","value":"452"}],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"id\": \"66d82876-518c-49e1-a03a-5f4ccb4ff471\",\n \"created_at\": \"2026-01-21T21:02:44.368291Z\",\n \"updated_at\": \"2026-01-21T21:02:44.368291Z\",\n \"username\": \"moss\",\n \"token\": \"\",\n \"refresh_token\": \"{{refresh_token}}\"\n}"}],"_postman_id":"f549bf84-72c4-44af-b922-261406d38c87"},{"name":"Delete user","id":"9dd8dd8c-49be-4aea-be2b-ffa1a2e5dfec","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"DELETE","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"username\": \"{{username}}\",\n \"password\": \"{{password}}\"\n}"},"url":"http://{{pincher_instance}}/api/users","urlObject":{"protocol":"http","path":["api","users"],"host":["{{pincher_instance}}"],"query":[],"variable":[]}},"response":[{"id":"d04f57bc-275a-4cd9-9e24-de487e7f731f","name":"Success","originalRequest":{"method":"DELETE","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"username\": \"{{username}}\",\n \"password\": \"{{password}}\"\n}"},"url":"http://{{pincher_instance}}/api/users"},"status":"No Content","code":204,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Wed, 21 Jan 2026 21:01:27 GMT"}],"cookie":[],"responseTime":null,"body":null}],"_postman_id":"9dd8dd8c-49be-4aea-be2b-ffa1a2e5dfec"},{"name":"Update user credentials","id":"57458770-e053-4ebe-bfe9-8161dbb711c0","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"PUT","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"username\": \"{{username}}\",\n \"password\": \"{{password}}\"\n}","options":{"raw":{"language":"json"}}},"url":"http://{{pincher_instance}}/api/users","urlObject":{"protocol":"http","path":["api","users"],"host":["{{pincher_instance}}"],"query":[],"variable":[]}},"response":[{"id":"f553d407-1f41-4767-9a06-97c8034e87b8","name":"Success","originalRequest":{"method":"PUT","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"username\": \"{{username}}\",\n \"password\": \"{{password}}\"\n}","options":{"raw":{"language":"json"}}},"url":"http://{{pincher_instance}}/api/users"},"status":"No Content","code":204,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Wed, 21 Jan 2026 21:11:22 GMT"}],"cookie":[],"responseTime":null,"body":null}],"_postman_id":"57458770-e053-4ebe-bfe9-8161dbb711c0"}],"id":"09894d25-427e-430e-b1a1-356b10eb7793","description":"The /users endpoints let you create a user, log in as an existing user, get new access tokens, or manage information about the authenticated user.
The id of the budget from which to revoke a user's existing membership.
\n","type":"text/plain"},"type":"any","value":"{{budget_id}}","key":"budget_id"},{"description":{"content":"The user_id of the user whose membership we want to revoke.
\n","type":"text/plain"},"type":"any","value":"{{member_user_id}}","key":"user_id"}]}},"response":[{"id":"6eb17ca1-b5cf-44ea-a742-215d85f03d6d","name":"Success","originalRequest":{"method":"DELETE","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":{"raw":"http://{{pincher_instance}}/api/budgets/:budget_id/members/:user_id","protocol":"http","host":["{{pincher_instance}}"],"path":["api","budgets",":budget_id","members",":user_id"],"variable":[{"key":"budget_id","value":"{{budget_id}}","description":"The id of the budget from which to revoke a user's existing membership."},{"key":"user_id","value":"{{member_user_id}}","description":"The user_id of the user whose membership we want to revoke."}]}},"status":"No Content","code":204,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Wed, 21 Jan 2026 23:15:10 GMT"}],"cookie":[],"responseTime":null,"body":null}],"_postman_id":"b3bff8f3-16ae-4af0-81eb-ccc9766af45f"},{"name":"Update budget info","id":"6e78e1dc-99d1-4695-92a0-8686dc3dccb5","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"PUT","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"name\": \"my-budget\",\n \"notes\": \"My budget for visualizing my personal finances!\"\n}","options":{"raw":{"language":"json"}}},"url":"http://{{pincher_instance}}/api/budgets/:budget_id","urlObject":{"protocol":"http","path":["api","budgets",":budget_id"],"host":["{{pincher_instance}}"],"query":[],"variable":[{"id":"8bf97c75-b691-4fc4-b951-ef8011016590","type":"any","value":"{{budget_id}}","key":"budget_id"}]}},"response":[{"id":"7ec623ad-3bd5-4c84-83c6-9bb66a4920c1","name":"Success","originalRequest":{"method":"PUT","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"name\": \"my-budget\",\n \"notes\": \"My budget for visualizing my personal finances!\"\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"http://{{pincher_instance}}/api/budgets/:budget_id","protocol":"http","host":["{{pincher_instance}}"],"path":["api","budgets",":budget_id"],"variable":[{"key":"budget_id","value":"{{budget_id}}"}]}},"status":"No Content","code":204,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Wed, 21 Jan 2026 21:39:08 GMT"}],"cookie":[],"responseTime":null,"body":null}],"_postman_id":"6e78e1dc-99d1-4695-92a0-8686dc3dccb5"},{"name":"Get budget","id":"81ee603d-947b-494a-8be3-286e82e02bcb","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":"http://{{pincher_instance}}/api/budgets/:budget_id","urlObject":{"protocol":"http","path":["api","budgets",":budget_id"],"host":["{{pincher_instance}}"],"query":[],"variable":[{"id":"916fd046-a351-45e2-a21d-d28a3bf6150a","type":"any","value":"{{budget_id}}","key":"budget_id"}]}},"response":[{"id":"c9e5d7e8-43f6-4ae3-a024-caae977cae4a","name":"Success","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":{"raw":"http://{{pincher_instance}}/api/budgets/:budget_id","protocol":"http","host":["{{pincher_instance}}"],"path":["api","budgets",":budget_id"],"variable":[{"key":"budget_id","value":"{{budget_id}}"}]}},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"Content-Type","value":"application/json"},{"key":"Date","value":"Wed, 21 Jan 2026 21:39:53 GMT"},{"key":"Content-Length","value":"258"}],"cookie":[],"responseTime":null,"body":"{\n \"id\": \"ec680816-ef63-4530-9496-169f113e5782\",\n \"created_at\": \"2026-01-21T15:24:44.132576Z\",\n \"updated_at\": \"2026-01-21T15:39:08.332985Z\",\n \"admin_id\": \"9dbd0552-4c90-41e4-af49-240311f740ba\",\n \"name\": \"my-budget\",\n \"notes\": \"My budget for visualizing my personal finances!\"\n}"}],"_postman_id":"81ee603d-947b-494a-8be3-286e82e02bcb"},{"name":"Get budget capital","id":"20cbe1f2-ade6-4142-b73f-62313b5c33eb","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":"http://{{pincher_instance}}/api/budgets/:budget_id/capital","description":"Responds with the total amount of money between all ON_BUDGET accounts.
\n","urlObject":{"protocol":"http","path":["api","budgets",":budget_id","capital"],"host":["{{pincher_instance}}"],"query":[],"variable":[{"type":"any","value":"{{budget_id}}","key":"budget_id"}]}},"response":[],"_postman_id":"20cbe1f2-ade6-4142-b73f-62313b5c33eb"},{"name":"Get all user budgets","id":"d719cbd6-97c7-453c-8c47-3695e733e8b7","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":"http://{{pincher_instance}}/api/budgets","description":"Get ALL budgets that the authenticate user is a part of.
\n","urlObject":{"protocol":"http","path":["api","budgets"],"host":["{{pincher_instance}}"],"query":[],"variable":[]}},"response":[{"id":"3236afb7-880a-443a-800f-7f27a187a431","name":"Success","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":"http://{{pincher_instance}}/api/budgets"},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"Content-Type","value":"application/json"},{"key":"Date","value":"Wed, 21 Jan 2026 21:45:34 GMT"},{"key":"Content-Length","value":"272"}],"cookie":[],"responseTime":null,"body":"{\n \"budgets\": [\n {\n \"id\": \"ec680816-ef63-4530-9496-169f113e5782\",\n \"created_at\": \"2026-01-21T15:24:44.132576Z\",\n \"updated_at\": \"2026-01-21T15:45:16.063515Z\",\n \"admin_id\": \"9dbd0552-4c90-41e4-af49-240311f740ba\",\n \"name\": \"my-budget\",\n \"notes\": \"My budget for visualizing my personal finances!\"\n }\n ]\n}"}],"_postman_id":"d719cbd6-97c7-453c-8c47-3695e733e8b7"}],"id":"4f6f120d-d3aa-4d7a-b79f-b4c02b514c5d","description":"A budget is a SINGLE resource holding an entire ecosystem of subresources such as accounts, payees, categories, transactions, and more.
\nRather than only manging one budget on the web server, the Pincher API allows you to create one OR MORE budgets as one of potentially many users.
\nRelationships between users and budgets are defined as memberships.
\nA budget member can hold one of four roles:
\nAdmin
\nManager
\nContributor
\nViewer
\nThe ADMIN role is reserved for the creator of the budget.
The MANAGER role carries almost all of the same privileges as the ADMIN role, save for budget deletion.
The CONTRIBUTOR role allows users to add and delete both payees and transactions.
The VIEWER role limits users to only viewing all resources.
As of January 2026, this is as granular as permission sets get, but new features are planned to offer tighter controls on a per-user basis. You can track the related issue in the public Github repository here.
\n","event":[{"listen":"prerequest","script":{"id":"458bd155-00af-4ece-88f4-a4f39f0a83c3","type":"text/javascript","packages":{},"requests":{},"exec":[""]}},{"listen":"test","script":{"id":"43d4c32d-2d06-4bd7-9312-1d287cf9923f","type":"text/javascript","packages":{},"requests":{},"exec":[""]}}],"_postman_id":"4f6f120d-d3aa-4d7a-b79f-b4c02b514c5d"},{"name":"groups","item":[{"name":"Create new group","id":"461137d9-bd72-45b0-bbf4-6e47da562cf2","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"name\": \"Group Name\",\n \"notes\": \"Notes about new group\"\n}","options":{"raw":{"language":"json"}}},"url":"http://{{pincher_instance}}/api/budgets/:budget_id/groups","urlObject":{"protocol":"http","path":["api","budgets",":budget_id","groups"],"host":["{{pincher_instance}}"],"query":[],"variable":[{"type":"any","value":"{{budget_id}}","key":"budget_id"}]}},"response":[{"id":"13ad69a3-1aee-43c7-8b1c-5dd5e0454c7c","name":"Success","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"name\": \"Spending Group\",\n \"notes\": \"A new group to organize my spending-related categories.\"\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"http://{{pincher_instance}}/api/budgets/:budget_id/groups","protocol":"http","host":["{{pincher_instance}}"],"path":["api","budgets",":budget_id","groups"],"variable":[{"key":"budget_id","value":"{{budget_id}}"}]}},"status":"Created","code":201,"_postman_previewlanguage":null,"header":[{"key":"Content-Type","value":"application/json"},{"key":"Date","value":"Fri, 23 Jan 2026 21:56:40 GMT"},{"key":"Content-Length","value":"270"}],"cookie":[],"responseTime":null,"body":"{\n \"id\": \"dc24229f-6d2c-4227-b609-f632988f5537\",\n \"created_at\": \"2026-01-23T21:56:40.17816Z\",\n \"updated_at\": \"2026-01-23T21:56:40.17816Z\",\n \"budget_id\": \"ec680816-ef63-4530-9496-169f113e5782\",\n \"name\": \"Spending Group\",\n \"notes\": \"A new group to organize my spending-related categories.\"\n}"}],"_postman_id":"461137d9-bd72-45b0-bbf4-6e47da562cf2"},{"name":"Delete group","id":"389db8a4-4220-4192-af27-b76d616fdaf0","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"DELETE","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":"http://{{pincher_instance}}/api/budgets/:budget_id/groups/:group_id","description":"Categories assigned to a group will be unaffected, beyond simply being unassigned to it.
\n","urlObject":{"protocol":"http","path":["api","budgets",":budget_id","groups",":group_id"],"host":["{{pincher_instance}}"],"query":[],"variable":[{"type":"any","value":"{{budget_id}}","key":"budget_id"},{"type":"any","value":"{{group_id}}","key":"group_id"}]}},"response":[],"_postman_id":"389db8a4-4220-4192-af27-b76d616fdaf0"},{"name":"Update group info","id":"ca78979f-64a1-4769-8934-4eaf96ef2215","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"PUT","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"name\": \"Updated name for group\",\n \"notes\": \"Updated notes about group\"\n}","options":{"raw":{"language":"json"}}},"url":"http://{{pincher_instance}}/api/budgets/:budget_id/groups/:group_id","urlObject":{"protocol":"http","path":["api","budgets",":budget_id","groups",":group_id"],"host":["{{pincher_instance}}"],"query":[],"variable":[{"type":"any","value":"{{budget_id}}","key":"budget_id"},{"type":"any","value":"{{group_id}}","key":"group_id"}]}},"response":[{"id":"9d711d0c-462c-41ac-989a-5eb56eb6f7d5","name":"Success","originalRequest":{"method":"PUT","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"name\": \"Savings Group\",\n \"notes\": \"My group for organizing savings-related categories!\"\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"http://{{pincher_instance}}/api/budgets/:budget_id/groups/:group_id","protocol":"http","host":["{{pincher_instance}}"],"path":["api","budgets",":budget_id","groups",":group_id"],"variable":[{"key":"budget_id","value":"{{budget_id}}"},{"key":"group_id","value":"{{group_id}}"}]}},"status":"No Content","code":204,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Wed, 21 Jan 2026 21:55:35 GMT"}],"cookie":[],"responseTime":null,"body":null}],"_postman_id":"ca78979f-64a1-4769-8934-4eaf96ef2215"},{"name":"Get all budget groups","id":"759371bb-ed33-423b-b62c-973f67f7f276","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":"http://{{pincher_instance}}/api/budgets/:budget_id/groups","urlObject":{"protocol":"http","path":["api","budgets",":budget_id","groups"],"host":["{{pincher_instance}}"],"query":[],"variable":[{"type":"any","value":"{{budget_id}}","key":"budget_id"}]}},"response":[{"id":"c2735115-f073-48b8-a846-a79005633435","name":"Success","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":{"raw":"http://{{pincher_instance}}/api/budgets/:budget_id/groups","protocol":"http","host":["{{pincher_instance}}"],"path":["api","budgets",":budget_id","groups"],"variable":[{"key":"budget_id","value":"{{budget_id}}"}]}},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"Content-Type","value":"application/json"},{"key":"Date","value":"Wed, 21 Jan 2026 21:54:13 GMT"},{"key":"Content-Length","value":"285"}],"cookie":[],"responseTime":null,"body":"{\n \"groups\": [\n {\n \"id\": \"5b019562-4f56-4a5e-85a4-304cc1c9ad3f\",\n \"created_at\": \"2026-01-21T21:52:50.349225Z\",\n \"updated_at\": \"2026-01-21T21:52:50.349225Z\",\n \"budget_id\": \"ec680816-ef63-4530-9496-169f113e5782\",\n \"name\": \"Spending Group\",\n \"notes\": \"A new group to organize my spending-related categories.\"\n }\n ]\n}"}],"_postman_id":"759371bb-ed33-423b-b62c-973f67f7f276"}],"id":"f6cc572e-586a-4cc0-829c-157fc970a887","description":"Groups, or \"Category Groups,\" are used to organize categories within the database.
\nGroups are not essential to any function, but they guarantee a consistent experience across clients. Rather than clients needing to store anything local regarding how users may want their categories grouped, they can simply use these endpoints to manage the orgization, instead.
\n","_postman_id":"f6cc572e-586a-4cc0-829c-157fc970a887"},{"name":"accounts","item":[{"name":"Create new account","id":"d6d42062-9e5f-452c-81a6-71aa047c6ffa","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"name\": \"Big Bank Checking\",\n \"notes\": \"A checking account I opened with Big Bank, Inc.\",\n \"account_type\": \"ON_BUDGET\"\n}","options":{"raw":{"language":"json"}}},"url":"http://{{pincher_instance}}/api/budgets/:budget_id/accounts","description":"Accounts require one of two types: ON_BUDGET or OFF_BUDGET.
\nOFF_BUDGET accounts are created only for tracking purposes; transactions applied to these accounts cannot be categorized.
\n","urlObject":{"protocol":"http","path":["api","budgets",":budget_id","accounts"],"host":["{{pincher_instance}}"],"query":[],"variable":[{"type":"any","value":"{{budget_id}}","key":"budget_id"}]}},"response":[{"id":"2d12c65b-7076-4bd5-b89d-f940bf1e9e77","name":"Success","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"name\": \"Big Bank Checking\",\n \"notes\": \"A checking account I opened with Big Bank, Inc.\",\n \"account_type\": \"ON_BUDGET\"\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"http://{{pincher_instance}}/api/budgets/:budget_id/accounts","protocol":"http","host":["{{pincher_instance}}"],"path":["api","budgets",":budget_id","accounts"],"variable":[{"key":"budget_id","value":"{{budget_id}}"}]}},"status":"Created","code":201,"_postman_previewlanguage":null,"header":[{"key":"Content-Type","value":"application/json"},{"key":"Date","value":"Wed, 21 Jan 2026 22:05:25 GMT"},{"key":"Content-Length","value":"313"}],"cookie":[],"responseTime":null,"body":"{\n \"id\": \"a811ab5c-3a20-4a4d-9a83-a16ab63511a2\",\n \"created_at\": \"2026-01-21T22:05:25.469634Z\",\n \"updated_at\": \"2026-01-21T22:05:25.469634Z\",\n \"budget_id\": \"00000000-0000-0000-0000-000000000000\",\n \"account_type\": \"ON_BUDGET\",\n \"is_deleted\": false,\n \"name\": \"Big Bank Checking\",\n \"notes\": \"A checking account I opened with Big Bank, Inc.\"\n}"}],"_postman_id":"d6d42062-9e5f-452c-81a6-71aa047c6ffa"},{"name":"Delete account","id":"7f271fd5-77be-4740-b7f2-6006f6362474","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"DELETE","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"delete_hard\": false\n}"},"url":"http://{{pincher_instance}}/api/budgets/:budget_id/accounts/:account_id","description":"Account deletion is a process unique from other resources.
\nSoft deletion is required before an account can be ultimately deleted. It can be performed by sending a JSON payload that includes the delete_hard field set to false. A client could, in theory, leverage this soft-deleted state as an indicator for account closure.
Otherwise, soft deletion does enable the full deletion of the account by repeating the request with delete_hard set to true.
While the PINCHER API is designed with a freedom or control-first philosophy to free clients from hassle, this unique safeguard for accounts is critical to verifying the intention of clients to truly delete a resource whose existence is critical to almost every other resource being in sync within a given budget. Regardless, this design is subject to change.
\n","urlObject":{"protocol":"http","path":["api","budgets",":budget_id","accounts",":account_id"],"host":["{{pincher_instance}}"],"query":[],"variable":[{"type":"any","value":"{{budget_id}}","key":"budget_id"},{"type":"any","value":"{{account_id}}","key":"account_id"}]}},"response":[{"id":"fa43b9b5-ccdc-4294-b9a6-9127d9675966","name":"Success","originalRequest":{"method":"DELETE","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"delete_hard\": false\n}"},"url":{"raw":"http://{{pincher_instance}}/api/budgets/:budget_id/accounts/:account_id","protocol":"http","host":["{{pincher_instance}}"],"path":["api","budgets",":budget_id","accounts",":account_id"],"variable":[{"key":"budget_id","value":"{{budget_id}}"},{"key":"account_id","value":"{{account_id}}"}]}},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"Content-Type","value":"text/plain; charset=utf-8"},{"key":"Date","value":"Sat, 24 Jan 2026 03:04:44 GMT"},{"key":"Content-Length","value":"40"}],"cookie":[],"responseTime":null,"body":"Account soft-deleted; it may be restored"}],"_postman_id":"7f271fd5-77be-4740-b7f2-6006f6362474"},{"name":"Update account info","id":"94112a89-8b39-442a-8de4-153d0c81175f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"PUT","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"name\": \"Big Bank Checking\",\n \"notes\": \"Represents my Big Bank Inc., checking account.\"\n}","options":{"raw":{"language":"json"}}},"url":"http://{{pincher_instance}}/api/budgets/:budget_id/accounts/:account_id","urlObject":{"protocol":"http","path":["api","budgets",":budget_id","accounts",":account_id"],"host":["{{pincher_instance}}"],"query":[],"variable":[{"type":"any","value":"{{budget_id}}","key":"budget_id"},{"type":"any","value":"{{account_id}}","key":"account_id"}]}},"response":[{"id":"3ed39497-b5af-4b68-aa19-4e5fb49d22e2","name":"Success","originalRequest":{"method":"PUT","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"name\": \"Big Bank Checking\",\n \"notes\": \"Represents my Big Bank Inc., checking account.\"\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"http://{{pincher_instance}}/api/budgets/:budget_id/accounts/:account_id","protocol":"http","host":["{{pincher_instance}}"],"path":["api","budgets",":budget_id","accounts",":account_id"],"variable":[{"key":"budget_id","value":"{{budget_id}}"},{"key":"account_id","value":"{{account_id}}"}]}},"status":"No Content","code":204,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Sat, 24 Jan 2026 02:53:28 GMT"}],"cookie":[],"responseTime":null,"body":null}],"_postman_id":"94112a89-8b39-442a-8de4-153d0c81175f"},{"name":"Get all budget accounts","id":"ea7286a5-9922-4a37-91bc-33605e1cd9c1","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":"http://{{pincher_instance}}/api/budgets/:budget_id/accounts","urlObject":{"protocol":"http","path":["api","budgets",":budget_id","accounts"],"host":["{{pincher_instance}}"],"query":[],"variable":[{"type":"any","value":"{{budget_id}}","key":"budget_id"}]}},"response":[{"id":"a954c8f3-4183-426e-8f1a-a12285231548","name":"Get all budget accounts","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":{"raw":"http://{{pincher_instance}}/api/budgets/:budget_id/accounts","protocol":"http","host":["{{pincher_instance}}"],"path":["api","budgets",":budget_id","accounts"],"variable":[{"key":"budget_id","value":"{{budget_id}}"}]}},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"Content-Type","value":"application/json"},{"key":"Date","value":"Sat, 24 Jan 2026 02:51:04 GMT"},{"key":"Content-Length","value":"639"}],"cookie":[],"responseTime":null,"body":"{\n \"accounts\": [\n {\n \"id\": \"a811ab5c-3a20-4a4d-9a83-a16ab63511a2\",\n \"created_at\": \"2026-01-21T22:05:25.469634Z\",\n \"updated_at\": \"2026-01-21T22:05:25.469634Z\",\n \"budget_id\": \"ec680816-ef63-4530-9496-169f113e5782\",\n \"account_type\": \"ON_BUDGET\",\n \"is_deleted\": false,\n \"name\": \"Big Bank Checking\",\n \"notes\": \"A checking account I opened with Big Bank, Inc.\"\n },\n {\n \"id\": \"4e36880d-5ff5-4c6a-b3f8-3fbc1d3241c9\",\n \"created_at\": \"2026-01-23T22:24:00.668207Z\",\n \"updated_at\": \"2026-01-23T22:24:00.668207Z\",\n \"budget_id\": \"ec680816-ef63-4530-9496-169f113e5782\",\n \"account_type\": \"ON_BUDGET\",\n \"is_deleted\": false,\n \"name\": \"Big Bank Savings\",\n \"notes\": \"A savings account I opened with Big Bank, Inc\"\n }\n ]\n}"}],"_postman_id":"ea7286a5-9922-4a37-91bc-33605e1cd9c1"},{"name":"Get budget account","id":"16af66bb-1113-4bf7-b80a-1b5c832b3382","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":"http://{{pincher_instance}}/api/budgets/:budget_id/accounts/:account_id","urlObject":{"protocol":"http","path":["api","budgets",":budget_id","accounts",":account_id"],"host":["{{pincher_instance}}"],"query":[],"variable":[{"type":"any","value":"{{budget_id}}","key":"budget_id"},{"type":"any","value":"{{account_id}}","key":"account_id"}]}},"response":[{"id":"3585d18c-8ae4-4134-9c05-778fc3a318e0","name":"Success","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":{"raw":"http://{{pincher_instance}}/api/budgets/:budget_id/accounts/:account_id","protocol":"http","host":["{{pincher_instance}}"],"path":["api","budgets",":budget_id","accounts",":account_id"],"variable":[{"key":"budget_id","value":"{{budget_id}}"},{"key":"account_id","value":"{{account_id}}"}]}},"status":"Created","code":201,"_postman_previewlanguage":null,"header":[{"key":"Content-Type","value":"application/json"},{"key":"Date","value":"Sat, 24 Jan 2026 02:52:20 GMT"},{"key":"Content-Length","value":"313"}],"cookie":[],"responseTime":null,"body":"{\n \"id\": \"a811ab5c-3a20-4a4d-9a83-a16ab63511a2\",\n \"created_at\": \"2026-01-21T22:05:25.469634Z\",\n \"updated_at\": \"2026-01-21T22:05:25.469634Z\",\n \"budget_id\": \"ec680816-ef63-4530-9496-169f113e5782\",\n \"account_type\": \"ON_BUDGET\",\n \"is_deleted\": false,\n \"name\": \"Big Bank Checking\",\n \"notes\": \"A checking account I opened with Big Bank, Inc.\"\n}"}],"_postman_id":"16af66bb-1113-4bf7-b80a-1b5c832b3382"},{"name":"Get account capital","id":"45b4ba02-03dd-478d-b183-dd6c7f4a1346","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":"http://{{pincher_instance}}/api/budgets/:budget_id/accounts/:account_id/capital","urlObject":{"protocol":"http","path":["api","budgets",":budget_id","accounts",":account_id","capital"],"host":["{{pincher_instance}}"],"query":[],"variable":[{"type":"any","value":"{{budget_id}}","key":"budget_id"},{"type":"any","value":"{{account_id}}","key":"account_id"}]}},"response":[{"id":"aae3f85a-c7bd-42f3-a518-9375271dcc74","name":"Success","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":{"raw":"http://{{pincher_instance}}/api/budgets/:budget_id/accounts/:account_id/capital","protocol":"http","host":["{{pincher_instance}}"],"path":["api","budgets",":budget_id","accounts",":account_id","capital"],"variable":[{"key":"budget_id","value":"{{budget_id}}"},{"key":"account_id","value":"{{account_id}}"}]}},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"Content-Type","value":"application/json"},{"key":"Date","value":"Sat, 24 Jan 2026 02:52:51 GMT"},{"key":"Content-Length","value":"18"}],"cookie":[],"responseTime":null,"body":"{\n \"capital\": 146500\n}"}],"_postman_id":"45b4ba02-03dd-478d-b183-dd6c7f4a1346"},{"name":"Restore account","id":"6c7d4428-7626-445e-a87e-fc281a2f7782","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"PATCH","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":"http://{{pincher_instance}}/api/budgets/:budget_id/accounts/:account_id","description":"Accounts which have been soft-deleted may be restored to a non-deleted state.
\n","urlObject":{"protocol":"http","path":["api","budgets",":budget_id","accounts",":account_id"],"host":["{{pincher_instance}}"],"query":[],"variable":[{"id":"e1249fe1-8e91-4134-b88e-8be29da96ec8","type":"any","value":"{{budget_id}}","key":"budget_id"},{"id":"6fa87edd-a975-41f3-90db-e78f02744148","type":"any","value":"{{account_id}}","key":"account_id"}]}},"response":[{"id":"3a369c7a-722b-4674-b83c-68ff2daf3f45","name":"Success","originalRequest":{"method":"PATCH","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":{"raw":"http://{{pincher_instance}}/api/budgets/:budget_id/accounts/:account_id","protocol":"http","host":["{{pincher_instance}}"],"path":["api","budgets",":budget_id","accounts",":account_id"],"variable":[{"key":"budget_id","value":"{{budget_id}}"},{"key":"account_id","value":"{{account_id}}"}]}},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"Content-Type","value":"text/plain; charset=utf-8"},{"key":"Date","value":"Sat, 24 Jan 2026 03:06:19 GMT"},{"key":"Content-Length","value":"16"}],"cookie":[],"responseTime":null,"body":"Account restored"}],"_postman_id":"6c7d4428-7626-445e-a87e-fc281a2f7782"}],"id":"c00f5a5f-5088-4688-b469-217fbdda6847","description":"Accounts are exactly what they sound like. For every existing bank account you hold that you want your budget to represent, you need an account stored in the database to mirror it.
\nFor example, suppose you opened a checking account with a bank called \"Big Banking, Inc.,\" and you use that account for your financial needs every day. You would want to add an account, perhaps called BB Checking, to represent its balances as it changes!
As you keep up to date on your transactions, the balance within the account will continue to match the balance as seen in your real bank account.
\n","_postman_id":"c00f5a5f-5088-4688-b469-217fbdda6847"},{"name":"categories","item":[{"name":"Create new category","id":"e0eac60a-ed98-4663-bd59-9b75f2b4ccd1","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"name\": \"Category name\",\n \"notes\": \"Notes about the category\",\n \"group_name\": \"Optional group assignment on creation\"\n}","options":{"raw":{"language":"json"}}},"url":"http://{{pincher_instance}}/api/budgets/:budget_id/categories","urlObject":{"protocol":"http","path":["api","budgets",":budget_id","categories"],"host":["{{pincher_instance}}"],"query":[],"variable":[{"type":"any","value":"{{budget_id}}","key":"budget_id"}]}},"response":[{"id":"8c4e9521-b031-408e-b2f5-edfdc83fff21","name":"Success","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"name\": \"Treats\",\n \"notes\": \"A category reflecting my expenses when purchasing treats.\",\n \"group_name\": \"Spending Group\"\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"http://{{pincher_instance}}/api/budgets/:budget_id/categories","protocol":"http","host":["{{pincher_instance}}"],"path":["api","budgets",":budget_id","categories"],"variable":[{"key":"budget_id","value":"{{budget_id}}"}]}},"status":"Created","code":201,"_postman_previewlanguage":null,"header":[{"key":"Content-Type","value":"application/json"},{"key":"Date","value":"Fri, 23 Jan 2026 21:57:00 GMT"},{"key":"Content-Length","value":"314"}],"cookie":[],"responseTime":null,"body":"{\n \"id\": \"ba48ebb2-618f-48d7-97cf-c4e7491b36c4\",\n \"created_at\": \"2026-01-23T21:57:00.35095Z\",\n \"updated_at\": \"2026-01-23T21:57:00.35095Z\",\n \"budget_id\": \"ec680816-ef63-4530-9496-169f113e5782\",\n \"group_id\": \"dc24229f-6d2c-4227-b609-f632988f5537\",\n \"name\": \"Treats\",\n \"notes\": \"A category reflecting my expenses when purchasing treats.\"\n}"}],"_postman_id":"e0eac60a-ed98-4663-bd59-9b75f2b4ccd1"},{"name":"Delete category","id":"9a17ae0f-d8b7-4d44-9b8f-c819df2e0a68","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"DELETE","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":"http://{{pincher_instance}}/api/budgets/:budget_id/categories/:category_id","urlObject":{"protocol":"http","path":["api","budgets",":budget_id","categories",":category_id"],"host":["{{pincher_instance}}"],"query":[],"variable":[{"type":"any","value":"{{budget_id}}","key":"budget_id"},{"type":"any","value":"","key":"category_id"}]}},"response":[],"_postman_id":"9a17ae0f-d8b7-4d44-9b8f-c819df2e0a68"},{"name":"Update category info","id":"31c79a0e-3c1f-499c-ba8c-444c45ce200d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"PUT","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"name\": \"Updated category name\",\n \"notes\": \"Updated notes about the category\"\n}","options":{"raw":{"language":"json"}}},"url":"http://{{pincher_instance}}/api/budgets/:budget_id/categories/:category_id","urlObject":{"protocol":"http","path":["api","budgets",":budget_id","categories",":category_id"],"host":["{{pincher_instance}}"],"query":[],"variable":[{"type":"any","value":"","key":"budget_id"},{"type":"any","value":"","key":"category_id"}]}},"response":[],"_postman_id":"31c79a0e-3c1f-499c-ba8c-444c45ce200d"},{"name":"Get all budget categories","id":"386dbc23-19b0-485c-8f6e-b0935060f46a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":"http://{{pincher_instance}}/api/budgets/:budget_id/categories","urlObject":{"protocol":"http","path":["api","budgets",":budget_id","categories"],"host":["{{pincher_instance}}"],"query":[],"variable":[{"type":"any","value":"{{budget_id}}","key":"budget_id"}]}},"response":[],"_postman_id":"386dbc23-19b0-485c-8f6e-b0935060f46a"}],"id":"58b5efdf-e5fd-49e4-8aa6-6e5e2c601601","description":"Categories are the envelopes themselves!
\nThat is, when you want to allocate money in your pool toward a fund, that fund is represented by a category. You're putting money inside the envelope!
\nFor example, if you drive a car, it's likely that you're paying for gas on a regular basis. You'll need a category to assign money to, perhaps simply called Gas, that you budget specifically for gas expenses!
Deletion of a payee that is referenced by one or more transactions will necessitate the name of an existing replacement payee be provided.
\n","urlObject":{"protocol":"http","path":["api","budgets",":budget_id","payees",":payee_id"],"host":["{{pincher_instance}}"],"query":[],"variable":[{"type":"any","value":"{{budget_id}}","key":"budget_id"},{"type":"any","value":"{{payee_id}}","key":"payee_id"}]}},"response":[{"id":"41934419-d305-48e6-926b-8b500778272f","name":"Success","originalRequest":{"method":"DELETE","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"new_payee_name\": \"\"\n}"},"url":{"raw":"http://{{pincher_instance}}/api/budgets/:budget_id/payees/:payee_id","protocol":"http","host":["{{pincher_instance}}"],"path":["api","budgets",":budget_id","payees",":payee_id"],"variable":[{"key":"budget_id","value":"{{budget_id}}"},{"key":"payee_id","value":"{{payee_id}}"}]}},"status":"No Content","code":204,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Fri, 23 Jan 2026 21:43:38 GMT"}],"cookie":[],"responseTime":null,"body":null}],"_postman_id":"6c5e39a4-8399-4f64-a107-f2d6ada1869a"},{"name":"Update payee","id":"49b56c2a-b318-4282-81ff-8bd8f6d287c7","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"PUT","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"name\": \"Sea Parks\",\n \"notes\": \"This particular location has twelve exits.\"\n}","options":{"raw":{"language":"json"}}},"url":"http://{{pincher_instance}}/api/budgets/:budget_id/payees/:payee_id","urlObject":{"protocol":"http","path":["api","budgets",":budget_id","payees",":payee_id"],"host":["{{pincher_instance}}"],"query":[],"variable":[{"type":"any","value":"{{budget_id}}","key":"budget_id"},{"type":"any","value":"{{payee_id}}","key":"payee_id"}]}},"response":[{"id":"eb632cd7-76f5-4e9d-bd43-8507f935bc56","name":"Success","originalRequest":{"method":"PUT","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"name\": \"Sea Parks\",\n \"notes\": \"This particular location has twelve exits.\"\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"http://{{pincher_instance}}/api/budgets/:budget_id/payees/:payee_id","protocol":"http","host":["{{pincher_instance}}"],"path":["api","budgets",":budget_id","payees",":payee_id"],"variable":[{"key":"budget_id","value":"{{budget_id}}"},{"key":"payee_id","value":"{{payee_id}}"}]}},"status":"No Content","code":204,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Fri, 23 Jan 2026 21:50:55 GMT"}],"cookie":[],"responseTime":null,"body":null}],"_postman_id":"49b56c2a-b318-4282-81ff-8bd8f6d287c7"},{"name":"Get all budget payees","id":"ca1c3bbb-1f17-43d5-99ef-5741ab4da5a4","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":"http://{{pincher_instance}}/api/budgets/:budget_id/payees","urlObject":{"protocol":"http","path":["api","budgets",":budget_id","payees"],"host":["{{pincher_instance}}"],"query":[],"variable":[{"type":"any","value":"{{budget_id}}","key":"budget_id"}]}},"response":[{"id":"09f0f6ae-4409-4002-9749-7912f5d082f0","name":"Success","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":{"raw":"http://{{pincher_instance}}/api/budgets/:budget_id/payees","protocol":"http","host":["{{pincher_instance}}"],"path":["api","budgets",":budget_id","payees"],"variable":[{"key":"budget_id","value":"{{budget_id}}"}]}},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"Content-Type","value":"application/json"},{"key":"Date","value":"Fri, 23 Jan 2026 21:53:12 GMT"},{"key":"Content-Length","value":"539"}],"cookie":[],"responseTime":null,"body":"{\n \"payees\": [\n {\n \"id\": \"d606c0fd-1a0b-4645-b286-5c9ee060df58\",\n \"created_at\": \"2026-01-21T22:08:58.540173Z\",\n \"updated_at\": \"2026-01-21T22:08:58.540173Z\",\n \"budget_id\": \"ec680816-ef63-4530-9496-169f113e5782\",\n \"name\": \"Messy Joe's\",\n \"notes\": \"Nice atmosphere. Food's great. It's got a bit of an edge.\"\n },\n {\n \"id\": \"8953d0ec-be86-478e-9b63-55c5de2dc988\",\n \"created_at\": \"2026-01-23T21:46:06.016558Z\",\n \"updated_at\": \"2026-01-23T15:52:38.105215Z\",\n \"budget_id\": \"ec680816-ef63-4530-9496-169f113e5782\",\n \"name\": \"Sea Parks\",\n \"notes\": \"This particular location has twelve exits.\"\n }\n ]\n}"}],"_postman_id":"ca1c3bbb-1f17-43d5-99ef-5741ab4da5a4"},{"name":"Get payee","id":"35ce0609-3e3f-479d-af25-e16c45d16d86","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":"http://{{pincher_instance}}/api/budgets/:budget_id/payees/:payee_id","urlObject":{"protocol":"http","path":["api","budgets",":budget_id","payees",":payee_id"],"host":["{{pincher_instance}}"],"query":[],"variable":[{"type":"any","value":"{{budget_id}}","key":"budget_id"},{"type":"any","value":"{{payee_id}}","key":"payee_id"}]}},"response":[{"id":"2ffca78c-d97f-46e7-b89f-51ada5a2b7e1","name":"Success","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":{"raw":"http://{{pincher_instance}}/api/budgets/:budget_id/payees/:payee_id","protocol":"http","host":["{{pincher_instance}}"],"path":["api","budgets",":budget_id","payees",":payee_id"],"variable":[{"key":"budget_id","value":"{{budget_id}}"},{"key":"payee_id","value":"{{payee_id}}"}]}},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"Content-Type","value":"application/json"},{"key":"Date","value":"Fri, 23 Jan 2026 21:52:47 GMT"},{"key":"Content-Length","value":"254"}],"cookie":[],"responseTime":null,"body":"{\n \"id\": \"8953d0ec-be86-478e-9b63-55c5de2dc988\",\n \"created_at\": \"2026-01-23T21:46:06.016558Z\",\n \"updated_at\": \"2026-01-23T15:52:38.105215Z\",\n \"budget_id\": \"ec680816-ef63-4530-9496-169f113e5782\",\n \"name\": \"Sea Parks\",\n \"notes\": \"This particular location has twelve exits.\"\n}"}],"_postman_id":"35ce0609-3e3f-479d-af25-e16c45d16d86"}],"id":"8c8bcc3d-0504-46cd-be88-fe7c48db5fd1","description":"Payees are the corresponding subject of transactions. For example, if you wish to log a purchase at a local store, you ought to record the name of that store.
\nLikewise, although the terminology doesn't perfectly line up, it's conventional for this resource to also describe someone paying you. For example, if you wish to log a transaction representing a direct deposit into your bank, you ought to record the name of your employer.
\n","_postman_id":"8c8bcc3d-0504-46cd-be88-fe7c48db5fd1"},{"name":"transactions","item":[{"name":"Create new transaction","id":"f696a395-edcd-4e90-9107-3b5aeb2eb10c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"account_name\": \"Account Affected\",\n \"transfer_account_name\": \"\",\n \"transaction_date\": \"2006-01-02\",\n \"payee_name\": \"Payee Involved\",\n \"notes\": \"Notes about this transaction\",\n \"cleared\": true,\n \"amounts\": {\n \"CATEGORY NAME\": -3500\n }\n}","options":{"raw":{"language":"json"}}},"url":"http://{{pincher_instance}}/api/budgets/:budget_id/transactions","description":"","urlObject":{"protocol":"http","path":["api","budgets",":budget_id","transactions"],"host":["{{pincher_instance}}"],"query":[],"variable":[{"type":"any","value":"{{budget_id}}","key":"budget_id"}]}},"response":[{"id":"f0850e74-c574-40a7-8b55-0e97c82f5fad","name":"Success - Split Withdrawal TXN","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"account_name\": \"Big Bank Checking\",\n \"transfer_account_name\": \"\",\n \"transaction_date\": \"2025-10-15\",\n \"payee_name\": \"Messy Joe's\",\n \"notes\": \"I was very busy having fun, fun, fun!\",\n \"cleared\": true,\n \"amounts\": {\n \"Dining Out\": -2500,\n \"Treats\": -1000\n }\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"http://{{pincher_instance}}/api/budgets/:budget_id/transactions","protocol":"http","host":["{{pincher_instance}}"],"path":["api","budgets",":budget_id","transactions"],"variable":[{"key":"budget_id","value":"{{budget_id}}"}]}},"status":"Created","code":201,"_postman_previewlanguage":null,"header":[{"key":"Content-Type","value":"application/json"},{"key":"Date","value":"Fri, 23 Jan 2026 22:00:31 GMT"},{"key":"Content-Length","value":"358"}],"cookie":[],"responseTime":null,"body":"{\n \"id\": \"7744c8ce-968f-4729-8237-618d81ad4acc\",\n \"transaction_date\": \"2025-10-15T00:00:00Z\",\n \"transaction_type\": \"WITHDRAWAL\",\n \"notes\": \"I was very busy having fun, fun, fun!\",\n \"payee_name\": \"Messy Joe's\",\n \"budget_name\": \"my-budget\",\n \"account_name\": \"Big Bank Checking\",\n \"logger_name\": \"moss\",\n \"total_amount\": -3500,\n \"splits\": {\n \"Dining Out\": -2500,\n \"Treats\": -1000\n },\n \"cleared\": false\n}"},{"id":"e4ec3262-5d8f-4a0c-a77c-29f83ce6c26c","name":"Success - Deposit TXN","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"account_name\": \"Big Bank Savings\",\n \"transfer_account_name\": \"\",\n \"transaction_date\": \"2025-09-20\",\n \"payee_name\": \"Reynholm Industries\",\n \"notes\": \"Income from work\",\n \"cleared\": true,\n \"amounts\": {\n \"Income Buffer\": 250000\n }\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"http://{{pincher_instance}}/api/budgets/:budget_id/transactions","protocol":"http","host":["{{pincher_instance}}"],"path":["api","budgets",":budget_id","transactions"],"variable":[{"key":"budget_id","value":"{{budget_id}}"}]}},"status":"Created","code":201,"_postman_previewlanguage":null,"header":[{"key":"Content-Type","value":"application/json"},{"key":"Date","value":"Fri, 23 Jan 2026 22:24:39 GMT"},{"key":"Content-Length","value":"331"}],"cookie":[],"responseTime":null,"body":"{\n \"id\": \"50b966c2-d185-4811-aa97-eb9c3131a145\",\n \"transaction_date\": \"2025-09-20T00:00:00Z\",\n \"transaction_type\": \"DEPOSIT\",\n \"notes\": \"Income from work\",\n \"payee_name\": \"Reynholm Industries\",\n \"budget_name\": \"my-budget\",\n \"account_name\": \"Big Bank Savings\",\n \"logger_name\": \"moss\",\n \"total_amount\": 250000,\n \"splits\": {\n \"Income Buffer\": 250000\n },\n \"cleared\": false\n}"},{"id":"116caa71-8689-49ab-828b-a31ccdfb8b1e","name":"Success - Transfer TXN","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"account_name\": \"Big Bank Savings\",\n \"transfer_account_name\": \"Big Bank Checking\",\n \"transaction_date\": \"2025-09-20\",\n \"payee_name\": \"\",\n \"notes\": \"Transfer to checking account\",\n \"cleared\": true,\n \"amounts\": {\n \"TRANSFER\": -150000\n }\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"http://{{pincher_instance}}/api/budgets/:budget_id/transactions","protocol":"http","host":["{{pincher_instance}}"],"path":["api","budgets",":budget_id","transactions"],"variable":[{"key":"budget_id","value":"{{budget_id}}"}]}},"status":"Created","code":201,"_postman_previewlanguage":null,"header":[{"key":"Content-Type","value":"application/json"},{"key":"Date","value":"Fri, 23 Jan 2026 22:26:44 GMT"},{"key":"Content-Length","value":"716"}],"cookie":[],"responseTime":null,"body":"{\n \"from_transaction\": {\n \"id\": \"4faa4393-3e10-4941-81d2-7e0655718097\",\n \"transaction_date\": \"2025-09-20T00:00:00Z\",\n \"transaction_type\": \"TRANSFER_FROM\",\n \"notes\": \"Transfer to checking account\",\n \"payee_name\": \"Transfer\",\n \"budget_name\": \"my-budget\",\n \"account_name\": \"Big Bank Savings\",\n \"logger_name\": \"moss\",\n \"total_amount\": -150000,\n \"splits\": {\n \"Uncategorized\": -150000\n },\n \"cleared\": false\n },\n \"to_transaction\": {\n \"id\": \"1ef8805f-a553-4c6a-872a-a0e080b11836\",\n \"transaction_date\": \"2025-09-20T00:00:00Z\",\n \"transaction_type\": \"TRANSFER_TO\",\n \"notes\": \"Transfer to checking account\",\n \"payee_name\": \"Transfer\",\n \"budget_name\": \"my-budget\",\n \"account_name\": \"Big Bank Checking\",\n \"logger_name\": \"moss\",\n \"total_amount\": 150000,\n \"splits\": {\n \"Uncategorized\": 150000\n },\n \"cleared\": false\n }\n}"}],"_postman_id":"f696a395-edcd-4e90-9107-3b5aeb2eb10c"},{"name":"Delete transaction","id":"b7c7cc47-8f07-4452-b926-5bb9fc0b5365","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"DELETE","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":"http://{{pincher_instance}}/api/budgets/:budget_id/transactions/:transaction_id","urlObject":{"protocol":"http","path":["api","budgets",":budget_id","transactions",":transaction_id"],"host":["{{pincher_instance}}"],"query":[],"variable":[{"description":{"content":"ID of budget holding the transaction to delete
\n","type":"text/plain"},"type":"any","value":"{{budget_id}}","key":"budget_id"},{"description":{"content":"ID of transaction to delete
\n","type":"text/plain"},"type":"any","value":"{{transaction_id}}","key":"transaction_id"}]}},"response":[{"id":"bab14ecb-4ef0-47de-a036-2dbc5344e2db","name":"Success","originalRequest":{"method":"DELETE","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":{"raw":"http://{{pincher_instance}}/api/budgets/:budget_id/transactions/:transaction_id","protocol":"http","host":["{{pincher_instance}}"],"path":["api","budgets",":budget_id","transactions",":transaction_id"],"variable":[{"key":"budget_id","value":"{{budget_id}}","description":"ID of budget holding the transaction to delete"},{"key":"transaction_id","value":"{{transaction_id}}","description":"ID of transaction to delete"}]}},"status":"No Content","code":204,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Fri, 23 Jan 2026 22:35:05 GMT"}],"cookie":[],"responseTime":null,"body":null}],"_postman_id":"b7c7cc47-8f07-4452-b926-5bb9fc0b5365"},{"name":"Update transaction","id":"c60092f1-0f67-4b7a-93ac-056c2bc38dd8","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"PUT","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"account_name\": \"Updated Account\",\n \"transfer_account_name\": \"Other Account involved, if already transfer\",\n \"transaction_date\": \"2006-01-02\",\n \"payee_name\": \"Payee involved, if already non-transfer\",\n \"notes\": \"Updated Notes about this transaction\",\n \"cleared\": true,\n \"amounts\": {\n \"CATEGORY NAME\": -3500\n }\n}\n","options":{"raw":{"language":"json"}}},"url":"http://{{pincher_instance}}/api/budgets/:budget_id/transactions/:transaction_id","description":"","urlObject":{"protocol":"http","path":["api","budgets",":budget_id","transactions",":transaction_id"],"host":["{{pincher_instance}}"],"query":[],"variable":[{"description":{"content":"ID of budget holding this transaction
\n","type":"text/plain"},"type":"any","value":"{{budget_id}}","key":"budget_id"},{"description":{"content":"ID of transaction to update
\n","type":"text/plain"},"type":"any","value":"{{transaction_id}}","key":"transaction_id"}]}},"response":[{"id":"223263f0-e297-4891-a379-e75bf6d74058","name":"Success","originalRequest":{"method":"PUT","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"account_name\": \"Big Bank Checking\",\n \"transfer_account_name\": \"\",\n \"transaction_date\": \"2025-10-15\",\n \"payee_name\": \"Messy Joe's\",\n \"notes\": \"NOTE TO SELF: I actually got a stomach-ache the following day...don't go back here!\",\n \"cleared\": true,\n \"amounts\": {\n \"Dining Out\": -2500,\n \"Treats\": -1000\n }\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"http://{{pincher_instance}}/api/budgets/:budget_id/transactions/:transaction_id","protocol":"http","host":["{{pincher_instance}}"],"path":["api","budgets",":budget_id","transactions",":transaction_id"],"variable":[{"key":"budget_id","value":"{{budget_id}}","description":"ID of budget holding this transaction"},{"key":"transaction_id","value":"{{transaction_id}}","description":"ID of transaction to update"}]}},"status":"No Content","code":204,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Fri, 23 Jan 2026 23:11:19 GMT"}],"cookie":[],"responseTime":null,"body":null}],"_postman_id":"c60092f1-0f67-4b7a-93ac-056c2bc38dd8"},{"name":"Get all budget transactions","id":"12835eb1-5983-4df4-beae-4a8dcc06700e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":"http://{{pincher_instance}}/api/budgets/:budget_id/transactions","urlObject":{"protocol":"http","path":["api","budgets",":budget_id","transactions"],"host":["{{pincher_instance}}"],"query":[],"variable":[{"type":"any","value":"{{budget_id}}","key":"budget_id"}]}},"response":[{"id":"111e69fc-132d-4281-814e-8ee8f355f092","name":"Success","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":{"raw":"http://{{pincher_instance}}/api/budgets/:budget_id/transactions","protocol":"http","host":["{{pincher_instance}}"],"path":["api","budgets",":budget_id","transactions"],"variable":[{"key":"budget_id","value":"{{budget_id}}"}]}},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"Content-Type","value":"application/json"},{"key":"Date","value":"Fri, 23 Jan 2026 23:42:59 GMT"},{"key":"Content-Length","value":"1934"}],"cookie":[],"responseTime":null,"body":"{\n \"transactions\": [\n {\n \"id\": \"7744c8ce-968f-4729-8237-618d81ad4acc\",\n \"created_at\": \"2026-01-23T22:00:31.695957Z\",\n \"updated_at\": \"2026-01-23T17:28:48.332333Z\",\n \"budget_id\": \"ec680816-ef63-4530-9496-169f113e5782\",\n \"logger_id\": \"9dbd0552-4c90-41e4-af49-240311f740ba\",\n \"account_id\": \"a811ab5c-3a20-4a4d-9a83-a16ab63511a2\",\n \"transaction_type\": \"WITHDRAWAL\",\n \"transaction_date\": \"2025-10-15T00:00:00Z\",\n \"payee_id\": \"d606c0fd-1a0b-4645-b286-5c9ee060df58\",\n \"notes\": \"NOTE TO SELF: I actually got a stomach-ache the following day...don't go back here!\",\n \"is_cleared\": false\n },\n {\n \"id\": \"50b966c2-d185-4811-aa97-eb9c3131a145\",\n \"created_at\": \"2026-01-23T22:24:39.355238Z\",\n \"updated_at\": \"2026-01-23T22:24:39.355238Z\",\n \"budget_id\": \"ec680816-ef63-4530-9496-169f113e5782\",\n \"logger_id\": \"9dbd0552-4c90-41e4-af49-240311f740ba\",\n \"account_id\": \"4e36880d-5ff5-4c6a-b3f8-3fbc1d3241c9\",\n \"transaction_type\": \"DEPOSIT\",\n \"transaction_date\": \"2025-09-20T00:00:00Z\",\n \"payee_id\": \"4c2fbac5-f1d7-4029-a32b-69f51985b3b6\",\n \"notes\": \"Income from work\",\n \"is_cleared\": false\n },\n {\n \"id\": \"4faa4393-3e10-4941-81d2-7e0655718097\",\n \"created_at\": \"2026-01-23T22:26:44.900379Z\",\n \"updated_at\": \"2026-01-23T22:26:44.900379Z\",\n \"budget_id\": \"ec680816-ef63-4530-9496-169f113e5782\",\n \"logger_id\": \"9dbd0552-4c90-41e4-af49-240311f740ba\",\n \"account_id\": \"4e36880d-5ff5-4c6a-b3f8-3fbc1d3241c9\",\n \"transaction_type\": \"TRANSFER_FROM\",\n \"transaction_date\": \"2025-09-20T00:00:00Z\",\n \"payee_id\": \"00000000-0000-0000-0000-000000000000\",\n \"notes\": \"Transfer to checking account\",\n \"is_cleared\": false\n },\n {\n \"id\": \"1ef8805f-a553-4c6a-872a-a0e080b11836\",\n \"created_at\": \"2026-01-23T22:26:44.900379Z\",\n \"updated_at\": \"2026-01-23T22:26:44.900379Z\",\n \"budget_id\": \"ec680816-ef63-4530-9496-169f113e5782\",\n \"logger_id\": \"9dbd0552-4c90-41e4-af49-240311f740ba\",\n \"account_id\": \"a811ab5c-3a20-4a4d-9a83-a16ab63511a2\",\n \"transaction_type\": \"TRANSFER_TO\",\n \"transaction_date\": \"2025-09-20T00:00:00Z\",\n \"payee_id\": \"00000000-0000-0000-0000-000000000000\",\n \"notes\": \"Transfer to checking account\",\n \"is_cleared\": false\n }\n ]\n}"}],"_postman_id":"12835eb1-5983-4df4-beae-4a8dcc06700e"},{"name":"Get all budget txns with details","id":"834e21d9-01be-4221-9d37-d34196d586bf","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":"http://{{pincher_instance}}/api/budgets/:budget_id/transactions/details","description":"Returns the transactions with more user-friendly details, abstracting away IDs.
\n","urlObject":{"protocol":"http","path":["api","budgets",":budget_id","transactions","details"],"host":["{{pincher_instance}}"],"query":[],"variable":[{"type":"any","value":"{{budget_id}}","key":"budget_id"}]}},"response":[{"id":"05e99761-5e9d-4a7e-9b95-a8fd4cdfe951","name":"Success","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":{"raw":"http://{{pincher_instance}}/api/budgets/:budget_id/transactions/details","protocol":"http","host":["{{pincher_instance}}"],"path":["api","budgets",":budget_id","transactions","details"],"variable":[{"key":"budget_id","value":"{{budget_id}}"}]}},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"Content-Type","value":"application/json"},{"key":"Date","value":"Fri, 23 Jan 2026 23:14:30 GMT"},{"key":"Content-Length","value":"1431"}],"cookie":[],"responseTime":null,"body":"{\n \"transactions\": [\n {\n \"id\": \"7744c8ce-968f-4729-8237-618d81ad4acc\",\n \"transaction_date\": \"2025-10-15T00:00:00Z\",\n \"transaction_type\": \"WITHDRAWAL\",\n \"notes\": \"NOTE TO SELF: I actually got a stomach-ache the following day...don't go back here!\",\n \"payee_name\": \"Transfer\",\n \"budget_name\": \"my-budget\",\n \"account_name\": \"Big Bank Checking\",\n \"logger_name\": \"moss\",\n \"total_amount\": -3500,\n \"splits\": {\n \"Dining Out\": -2500,\n \"Treats\": -1000\n },\n \"cleared\": false\n },\n {\n \"id\": \"50b966c2-d185-4811-aa97-eb9c3131a145\",\n \"transaction_date\": \"2025-09-20T00:00:00Z\",\n \"transaction_type\": \"DEPOSIT\",\n \"notes\": \"Income from work\",\n \"payee_name\": \"Reynholm Industries\",\n \"budget_name\": \"my-budget\",\n \"account_name\": \"Big Bank Savings\",\n \"logger_name\": \"moss\",\n \"total_amount\": 250000,\n \"splits\": {\n \"Income Buffer\": 250000\n },\n \"cleared\": false\n },\n {\n \"id\": \"4faa4393-3e10-4941-81d2-7e0655718097\",\n \"transaction_date\": \"2025-09-20T00:00:00Z\",\n \"transaction_type\": \"TRANSFER_FROM\",\n \"notes\": \"Transfer to checking account\",\n \"payee_name\": \"Transfer\",\n \"budget_name\": \"my-budget\",\n \"account_name\": \"Big Bank Savings\",\n \"logger_name\": \"moss\",\n \"total_amount\": -150000,\n \"splits\": {\n \"Uncategorized\": -150000\n },\n \"cleared\": false\n },\n {\n \"id\": \"1ef8805f-a553-4c6a-872a-a0e080b11836\",\n \"transaction_date\": \"2025-09-20T00:00:00Z\",\n \"transaction_type\": \"TRANSFER_TO\",\n \"notes\": \"Transfer to checking account\",\n \"payee_name\": \"Transfer\",\n \"budget_name\": \"my-budget\",\n \"account_name\": \"Big Bank Checking\",\n \"logger_name\": \"moss\",\n \"total_amount\": 150000,\n \"splits\": {\n \"Uncategorized\": 150000\n },\n \"cleared\": false\n }\n ]\n}"}],"_postman_id":"834e21d9-01be-4221-9d37-d34196d586bf"},{"name":"Get budget transaction","id":"322797c3-77f5-44ce-ae25-8c0c3db3a311","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":"http://{{pincher_instance}}/api/budgets/:budget_id/transactions/:transaction_id","urlObject":{"protocol":"http","path":["api","budgets",":budget_id","transactions",":transaction_id"],"host":["{{pincher_instance}}"],"query":[],"variable":[{"type":"any","value":"{{budget_id}}","key":"budget_id"},{"description":{"content":"ID of the transaction to retrieve
\n","type":"text/plain"},"type":"any","value":"{{transaction_id}}","key":"transaction_id"}]}},"response":[{"id":"fcf412e5-1960-435c-bc54-7f51a1dc13eb","name":"Success","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":{"raw":"http://{{pincher_instance}}/api/budgets/:budget_id/transactions/:transaction_id","protocol":"http","host":["{{pincher_instance}}"],"path":["api","budgets",":budget_id","transactions",":transaction_id"],"variable":[{"key":"budget_id","value":"{{budget_id}}"},{"key":"transaction_id","value":"{{transaction_id}}","description":"ID of the transaction to retrieve"}]}},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"Content-Type","value":"application/json"},{"key":"Date","value":"Fri, 23 Jan 2026 23:43:25 GMT"},{"key":"Content-Length","value":"512"}],"cookie":[],"responseTime":null,"body":"{\n \"id\": \"7744c8ce-968f-4729-8237-618d81ad4acc\",\n \"created_at\": \"2026-01-23T22:00:31.695957Z\",\n \"updated_at\": \"2026-01-23T17:28:48.332333Z\",\n \"budget_id\": \"ec680816-ef63-4530-9496-169f113e5782\",\n \"logger_id\": \"9dbd0552-4c90-41e4-af49-240311f740ba\",\n \"account_id\": \"a811ab5c-3a20-4a4d-9a83-a16ab63511a2\",\n \"transaction_type\": \"\",\n \"transaction_date\": \"2025-10-15T00:00:00Z\",\n \"payee_id\": \"d606c0fd-1a0b-4645-b286-5c9ee060df58\",\n \"notes\": \"NOTE TO SELF: I actually got a stomach-ache the following day...don't go back here!\",\n \"is_cleared\": false\n}"}],"_postman_id":"322797c3-77f5-44ce-ae25-8c0c3db3a311"},{"name":"Get budget txn with details","id":"6a0c40af-b8c6-45a0-8d59-924f268dd9b9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":"http://{{pincher_instance}}/api/budgets/:budget_id/transactions/:transaction_id/details","description":"Returns the transaction with more user-friendly details, abstracting away IDs.
\n","urlObject":{"protocol":"http","path":["api","budgets",":budget_id","transactions",":transaction_id","details"],"host":["{{pincher_instance}}"],"query":[],"variable":[{"type":"any","value":"{{budget_id}}","key":"budget_id"},{"description":{"content":"ID of the transaction whose details we want to retrieve
\n","type":"text/plain"},"type":"any","value":"{{transaction_id}}","key":"transaction_id"}]}},"response":[{"id":"c428ea17-62a4-4171-9cd3-123e5036a5fa","name":"Success","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":{"raw":"http://{{pincher_instance}}/api/budgets/:budget_id/transactions/:transaction_id/details","protocol":"http","host":["{{pincher_instance}}"],"path":["api","budgets",":budget_id","transactions",":transaction_id","details"],"variable":[{"key":"budget_id","value":"{{budget_id}}"},{"key":"transaction_id","value":"{{transaction_id}}","description":"ID of the transaction whose details we want to retrieve"}]}},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"Content-Type","value":"application/json"},{"key":"Date","value":"Fri, 23 Jan 2026 23:15:15 GMT"},{"key":"Content-Length","value":"401"}],"cookie":[],"responseTime":null,"body":"{\n \"id\": \"7744c8ce-968f-4729-8237-618d81ad4acc\",\n \"transaction_date\": \"2025-10-15T00:00:00Z\",\n \"transaction_type\": \"WITHDRAWAL\",\n \"notes\": \"NOTE TO SELF: I actually got a stomach-ache the following day...don't go back here!\",\n \"payee_name\": \"Transfer\",\n \"budget_name\": \"my-budget\",\n \"account_name\": \"Big Bank Checking\",\n \"logger_name\": \"moss\",\n \"total_amount\": -3500,\n \"splits\": {\n \"Dining Out\": -2500,\n \"Treats\": -1000\n },\n \"cleared\": false\n}"}],"_postman_id":"6a0c40af-b8c6-45a0-8d59-924f268dd9b9"}],"id":"1bd48e4d-0426-4254-a4db-3559b84c80b4","description":"If you found Pincher API, there's a good chance you know what a transaction is. In this section, we'll just go over how transactions work in Pincher.
\nPincher provides a feature that has become increasingly popular with envelope budgeting solutions: split transactions.
\nA transaction split allows you to split a single transaction's total amount between two or more categories. This is helpful because it:
\nEnsures your bank transaction totals match the totals within the database
\nReduces the overhead of creating two seperate transactions
\nMaintains the integrity of transactions within the database
\nFor example, suppose you ate at Messy Joe's today, eating a $25 entrée and a $10 milkshake. While you could log two seperate transactions to represent the total $35 cost of your meal, if you're looking at your budget in Pincher next week, you could become confused at seeing a $25 charge that doesn't show up in your bank account, until you realize that it's part of the $35 charge to that bank account. Your bank doesn't care what you think about how you spent your money; it just know what you spent. So, a transaction split is a better solution: it ensures that not only is your spending categorized, but you're saving yourself any unnecessary brainpower later that would want to fix something that isn't broken.
\nWhile transaction splits are common in web servers like Pincher, you should know that Pincher does handle them only slightly differently.
\nIn Pincher, the transaction resource does not have an amount field like most other APIs. Rather, whether or not your transaction is split between categories, a Pincher transaction always record its amounts underneath rows of a subresource called transaction_splits. The reason for this is to reduce data redundancy. Instead of a non-split transaction carrying its own category_id and amount columns, it simply operates the same way that split transactions do: categories and amounts associated with it are pulled from one or more transaction_splits rows associated with it. With the technical exception of non-split transactions storing their totals within a single transaction_splits row, no amount totals are stored. Instead, they are calculated.
Transfer transactions make use of the transfer_account_name field to signify that a logged transaction is a transfer. The payee_name field will be ignored when a transfer account name is provided, as payees are irrelevant within transfer transactions.
Just like withdrawals and deposits, when logging a transfer transaction to an account given its account_name, the amounts affect the account we are working on. So, with transfers, whether or not what we are logging is a TRANSFER_TO or TRANSFER_FROM transaction is deduced by the Pincher API upon receiving the request, and the corresponding transfer transaction is logged automatically. For example, logging a transfer transaction with a negative value means the the transaction logged to the account with the given account_name will be established as the TRANSFER_FROM transaction; the account lost money, so it must be assumed that the account with the transfer_account_name is the recipient of the money transferred, getting the TRANSFER_TO transasction type.
When dealing with transfers, category names play no role, so only the first amounts element is used to determine the transaction amount(s).
The balance of a single category is the sum of its assignment history plus its activity.
\nFor example, suppose that your employer, Reynholm Industries, paid you $2,500 USD on Tuesday. You would log a deposit to a budget account with an amount of 250000 to the Income Buffer category.
Then, suppose that the new month begins, and you're ready to assign your money to categories. You assign $100 (`10000`) to the Dining Out category. Great! Now you can eat. But that money will have to come from somewhere.
Like other envelope budgeting APIs, Pincher does not users from assigning money they do not have. It is a far better user experiene to assign to much, and for a client to display an \"overassigned\" amount to let users know of their error.
\nIn order to keep balances and assignment in sync, it is recommended that clients implement features that make use of the from_category field within the request payload.
Any date with the format: YYYY-MM-DD.
\n","type":"text/plain"},"type":"any","value":"2025-10-01","key":"month_id"}]}},"response":[{"id":"f9e3fd11-b7a5-4a99-821e-1650345f5d67","name":"Success","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"amount\": 2500,\n \"to_category\": \"Dining Out\",\n \"from_category\": \"Income Buffer\"\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"http://{{pincher_instance}}/api/budgets/:budget_id/months/:month_id/categories","protocol":"http","host":["{{pincher_instance}}"],"path":["api","budgets",":budget_id","months",":month_id","categories"],"variable":[{"key":"budget_id","value":"{{budget_id}}"},{"key":"month_id","value":"2025-10-01","description":"Any date with the format: YYYY-MM-DD."}]}},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"Content-Type","value":"application/json"},{"key":"Date","value":"Sat, 24 Jan 2026 01:59:19 GMT"},{"key":"Content-Length","value":"102"}],"cookie":[],"responseTime":null,"body":"{\n \"month_id\": \"2025-10-01T00:00:00Z\",\n \"category_id\": \"398499a1-da4b-4682-a76d-f646662fb3ef\",\n \"amount\": 2500\n}"}],"_postman_id":"12e68cd8-48d1-4239-a9d2-135922baadb3"},{"name":"Get budget month report","id":"a2163fab-00bc-4349-88ab-3463d1218ddd","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":"http://{{pincher_instance}}/api/budgets/:budget_id/months/:month_id","description":"Get a report on the budget totals as they are (or were) for the month specified.
\nNote that in the given example, the assignment is 0 because the respective 2025-10 assignments of 2500 and 1000 to the Dining Out and Treats categories from the Income Buffer category result in an equal inverse assignemt of -3500 from the Income Buffer. In short, a month assignment total of 0 indicates that no money has been overbudgeted nor underassigned.
Get a report on totals for each category in the budget as they are (or were) for the month specified.
\n","urlObject":{"protocol":"http","path":["api","budgets",":budget_id","months",":month_id","categories"],"host":["{{pincher_instance}}"],"query":[],"variable":[{"type":"any","value":"{{budget_id}}","key":"budget_id"},{"type":"any","value":"2025-10-01","key":"month_id"}]}},"response":[{"id":"8edafbb8-6e2d-41a0-8b2f-649357990999","name":"Success","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":{"raw":"http://{{pincher_instance}}/api/budgets/:budget_id/months/:month_id/categories","protocol":"http","host":["{{pincher_instance}}"],"path":["api","budgets",":budget_id","months",":month_id","categories"],"variable":[{"key":"budget_id","value":"{{budget_id}}"},{"key":"month_id","value":"2025-10-01"}]}},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"Content-Type","value":"application/json"},{"key":"Date","value":"Sat, 24 Jan 2026 02:01:20 GMT"},{"key":"Content-Length","value":"353"}],"cookie":[],"responseTime":null,"body":"{\n \"category_reports\": [\n {\n \"month_id\": \"2025-10-01T00:00:00Z\",\n \"category_name\": \"Dining Out\",\n \"assigned\": 2500,\n \"activity\": -2500,\n \"balance\": 0\n },\n {\n \"month_id\": \"2025-10-01T00:00:00Z\",\n \"category_name\": \"Income Buffer\",\n \"assigned\": -3500,\n \"activity\": 0,\n \"balance\": 246500\n },\n {\n \"month_id\": \"2025-10-01T00:00:00Z\",\n \"category_name\": \"Treats\",\n \"assigned\": 1000,\n \"activity\": -1000,\n \"balance\": 0\n }\n ]\n}"}],"_postman_id":"f3dee8f0-cf4a-4e2d-a8c8-4e3892799696"},{"name":"Get budget category report","id":"8d20920d-5244-43fa-a93c-f24ba6ca28dd","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":"http://{{pincher_instance}}/api/budgets/:budget_id/months/:month_id/categories/:category_id","description":"Get a report on totals for the specified budget category as it is (or was) for the month specified.
\n","urlObject":{"protocol":"http","path":["api","budgets",":budget_id","months",":month_id","categories",":category_id"],"host":["{{pincher_instance}}"],"query":[],"variable":[{"type":"any","value":"{{budget_id}}","key":"budget_id"},{"type":"any","value":"2025-10-01","key":"month_id"},{"type":"any","value":"{{category_id}}","key":"category_id"}]}},"response":[{"id":"d0a7fb18-4068-44a6-8c12-f97b7b4264d8","name":"Success","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{access_token}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":{"raw":"http://{{pincher_instance}}/api/budgets/:budget_id/months/:month_id/categories/:category_id","protocol":"http","host":["{{pincher_instance}}"],"path":["api","budgets",":budget_id","months",":month_id","categories",":category_id"],"variable":[{"key":"budget_id","value":"{{budget_id}}"},{"key":"month_id","value":"2025-10-01"},{"key":"category_id","value":"{{category_id}}"}]}},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"Content-Type","value":"application/json"},{"key":"Date","value":"Sat, 24 Jan 2026 02:02:12 GMT"},{"key":"Content-Length","value":"109"}],"cookie":[],"responseTime":null,"body":"{\n \"month_id\": \"2025-10-01T00:00:00Z\",\n \"category_name\": \"Dining Out\",\n \"assigned\": 2500,\n \"activity\": -2500,\n \"balance\": 0\n}"}],"_postman_id":"8d20920d-5244-43fa-a93c-f24ba6ca28dd"}],"id":"9a7023eb-0cd1-4d22-8ab2-a4630faac968","description":"A month represents the state of a budget within Pincher. No month table truly exists in the database, but an assignments table does. An assignment is just an allocation of some amount of money toward a category that exists in the database. It is through months that clients may create these assignments, and observe the effect that they have on the database.
The month GET endpoints are used to get information about category balances.
Conventionally, envelope budgeting APIs feature a special, reserved category called Income, but allow for deposits to be automatically attributed to a category nonetheless. Then, assignments amounts would automatically pull from this reserved category.
The Pincher API makes no such category nor reservation on its own. While it is recommended that users establish a single category to dedicate to income categorization for later assignment (perhaps titled Income Buffer), Pincher does not enforce this approach in any manner.
The month_id path parameters, unlike all other resource_id parameters expected by the API, is not of type UUID. These are dates, written in the form of YYYY-MM-DD. When one of these endpoints is called with a month_id of this format, the date will be truncated to the 1st of the month before business logic is run.
It is recommended that clients provide the form YYYY-MM-01, nonetheless.
\nRemember that the appended day has no bearing on what is reported. For example, a report on the budget that specifies the month 2025-10-01 will show the values as affected by transactions that happened throughout that month, such as on 2025-10-15, for example.