{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"8601f817-735e-4ff1-ae0d-9cb7b36c6a6c","name":"Pincher API Documentation","description":"# 📄 Get started here\n\nThe 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.\n\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.\n\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.\n\n**NOTE: Full documentation is currently in progress. Some endpoints may exist that are not yet documented.**\n\n## **Getting started guide**\n\nTo start using the Pincher API, first follow the \"Get Started\" section listed on the [public repository on Github](https://github.com/YouWantToPinch/pincher-api).\n\nBe aware that:\n\n- The 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`.\n    \n- 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.\n    \n\n## Authentication\n\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.\n\nTo acquire an access token:\n\n- Create a user\n    \n- Log in with that user\n    \n\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.\n\nAll 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.\n\nTo 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.\n\n### Authentication error response\n\nIf a JWT is missing from the header you will receive an HTTP 400 response code.\n\nIf a JWT is invalid, you will receive an HTTP 401 Unauthorized response code.\n\n### **Need some help?**\n\nIf you're unfamiliar with envelope budgeting, you can read about it \\[here\\]([https://en.wikipedia.org/wiki/Envelope_system](https://en.wikipedia.org/wiki/Envelope_system)).","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"51711822","team":12969660,"collectionId":"8601f817-735e-4ff1-ae0d-9cb7b36c6a6c","publishedId":"2sBXVkAUL6","public":true,"publicUrl":"https://documenter-api.postman.tech/view/51711822/2sBXVkAUL6","privateUrl":"https://go.postman.co/documentation/51711822-8601f817-735e-4ff1-ae0d-9cb7b36c6a6c","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"F79269"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"dark","themes":[{"name":"dark","logo":"https://content.pstmn.io/4d0c9251-d583-4e24-9586-9b8208c3001a/cGluY2hlci1sb2dvLWxvbmdfdy1tYXJnaW4ucG5n","colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"F79269"}},{"name":"light","logo":"https://content.pstmn.io/d104b3be-2ae9-41fd-80d9-77f50e8f34f9/cGluY2hlci1sb2dvLWxvbmdfdy1tYXJnaW4ucG5n","colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"F79269"}}]}},"version":"8.11.4","publishDate":"2026-01-22T05:05:42.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":"https://content.pstmn.io/d104b3be-2ae9-41fd-80d9-77f50e8f34f9/cGluY2hlci1sb2dvLWxvbmdfdy1tYXJnaW4ucG5n","logoDark":"https://content.pstmn.io/4d0c9251-d583-4e24-9586-9b8208c3001a/cGluY2hlci1sb2dvLWxvbmdfdy1tYXJnaW4ucG5n"}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/01a34c4d87d7287689bec20e4c2ebde8cedbd06906268eeb1cd2401d3a3813f2","favicon":""},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://documenter.gw.postman.com/view/metadata/2sBXVkAUL6"}