{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"b6e10dc3-3c97-408e-a302-1102ebdecd3d","name":"Patchworks Core API","description":"Contents\n\n[Introduction](#intro)  \n[Getting Started](#getting-started)  \n[Using the API](#using-the-api)  \n[Authentication](#authentication)  \n[Usage Limits](#usage-limits)  \n[Common Fields](#common-fields)  \n[Errors](#errors)\n\n## Introduction\n\nThe API for this PATCHWORKS iPaaS (integration platform as a service) is designed under [MACH Alliance](https://machalliance.org/) principles, ensuridsffsng that every function available through the dashboard can be accessed programmatically.\n\nWith secure, real-time connectivity and access to any system or data source, the Patchworks API provides dashboard functionality, on your terms.\n\n## Getting Started\n\nIf you haven't done so already, [register for a Patchworks account](https://app.wearepatchworks.com/register) and create an API key - you'll need this to [authenticate API requests](https://postman.wearepatchworks.com/#authentication). See below for more information on how to authenticate and the usage limits that apply.\n\n## Using the API\n\nThe Patchworks Core API is a RESTful JSON API. This is the same API that powers the dashboard. All requests, unless stated otherwise, should include the `Content-Type` and `Accept` headers, both set to `application/json`. Failure to include these may result in incorrectly formatted responses.\n\n## Authentication\n\nThe Core API offers two authentication mechanisms: API Keys and OAuth 2. API Key authentication is the preferred method as it doesn't require any extra authentication calls. API keys do not expire, unlike the token gained via OAuth 2. Whichever method you use, the same usage limits apply.\n\n### API Keys\n\nThese provide great security whilst minimising the authentication complexity. The API key should be passed in the `Authorization` header in every request. Follow [this guide](https://doc.wearepatchworks.com/product-documentation/developer-hub/patchworks-api/core-api-authentication/api-keys) to generate an API key. We recommend using a different API key for each system connected to patchworks. You can create as many as you need. Once you no longer use a key, please revoke it. Request using invalid API keys will return a 401 response.\n\n### OAuth 2 (Client Credentials)\n\nYour account username and password can be used to gain a token to be put in the `Authorization` header to authenticate requests. This follows a simplified client credentials flow. The first request should be:\n\n``` http\nPOST /fabric/api/login HTTP/1.1\nHost: app.wearepatchworks.com\nContent-Type: application/json\nAccept: application/json\n{\n    \"username\": \"me@patchworks.com\",\n    \"password\": \"a1b2c3d4e5f6\"\n}\n\n ```\n\nA successful response will return the following content with a 200 status code:\n\n``` json\n{\n\"message\": \"You have successfully logged in.\",\n\"token\": \"eyJ0eXAiOiJKV......\",\n\"expires_in\": 86400\n}\n\n ```\n\nThe content in the `token` field should be used as your access token inside the `Authorization` header (along with the term `Bearer` to illustrate the token type):\n\n`Authorization: Bearer eyJ0eXAiOiJKV......`\n\nAuthentication tokens expire after the length of time indicated in the response (in seconds). An invalid or expired token will result in a 401 status code being returned. You should reauthenticate to get a new token.\n\n## Authorization\n\nAPI Keys and OAuth tokens behave slightly differently when it comes to authorization. A request authenticated with an OAuth token will inherit the permissions attached to the user credentials that created the token. You should bear this in mind when using your own credentials or those of another high-level user.\n\nAPI keys work by creating a new user on your company account that has manager-level access to the company account. A new user is created per API key created. The user will have the role `api-user`. This access level ensures the API key can be used for almost all needs except those only an account administrator should have, like blueprint management.\n\n## Usage Limits\n\nThe Patchworks API has rate and usage limits depending on your tier. All accounts are limited to 240 requests per minute by default. If you need more, please contact Patchworks support. Other usage limits apply based on your account tier. Please see the [tier allowances documentation](https://doc.wearepatchworks.com/product-documentation/getting-started/core-subscription-tiers) for more information.\n\n## Common Fields\n\nMany of the GET requests in the Patchworks Core collection use common functionality to control the data returned. This includes the following:\n\n- [Filters](#filters) - control which models are returned\n    \n- [Fields](#fields) - control the fields returned within each model\n    \n- [Includes](#includes) - control the related models returned\n    \n- [Sorting](#sorting) - control the order of the models returned\n    \n- [Pagination](#pagination) - control the number of models returned on each page\n    \n\nThese are not available on every endpoint, so please check the documentation for the particular endpoint needed.\n\n### Filters\n\nFilters are used to limit the models returned to those meeting specific criteria. Filters consist of two parts: key and value, and are used in the url as query parameters. Here is an example:\n\n```\n// get models where key=value AND key2=value2\n/my/endpoint?filter[key]=value&filter[key2]=value2\n\n ```\n\nIn some cases, multiple values may be passed to a filter (for an `or` comparison) like so:\n\n```\n// get models where key IN (value, value1)\n/my/endpoint?filter[key]=value,value1\n\n ```\n\nPlease see the individual endpoint for the list of filters supported.\n\n### Fields\n\nSome endpoints allow the user to take a more declarative approach by specifying what fields should be included in the models returned. The format is similar to that used for fields:\n\n`/my/endpoint?fields[users]=field1,field2`\n\nMost endpoints do not allow this functionality, but it is becoming more widely available over time.\n\n### Includes\n\nCore is a highly relational system, and so it makes sense for the API to reflect this in the data returned. By default, no related models are returned. But they can be requested using the `includes` query parameter:\n\n```\n// request the related 'versions' and 'webhook' models\n/my/endpoint?includes=versions,webhooks\n\n ```\n\nEach endpoint has a list of includes you can request. It is important to only request what you need, as the included data can dramatically increase the size of the API response. In some cases, nested relationships or even related model counts can be requested for some endpoints.\n\n### Sorting\n\nCore offers sorting functionality on some endpoints to make the results easier to work with. The sort can be specified using a query parameter as follows:\n\n```\n// sort the models by name in descending order\n/my/endpoint?sort=-name\n// sort the models by name in ascending order\n/my/endpoint?sort=name\n\n ```\n\nIn some cases, multiple sorts can be applied within the same request:\n\n```\n// sort by name descending and age ascending\n/my/endpoint?sort=-name,age\n\n ```\n\nCheck each endpoint for the list of sorts available.\n\n### Pagination\n\nCore offers pagination functionality on some endpoints to make the results easier to work with. The pagination can be specified using a query parameter as follows:\n\n`/my/endpoint?page=1&per_page=100`\n\nThe `per_page` parameter is optional and will default to a reasonable value for each endpoint. The `page` parameter is required and must be an integer, starting at 1.\n\n## Errors\n\nError responses may be returned for several reasons. It is recommended to first check the HTTP status code to indicate if the request was successful:\n\n| Code | Description | Reason |\n| --- | --- | --- |\n| 200/201 | Successful | \\- |\n| 204 | Successful, but no content returned | \\- |\n| 400 | Bad request | The request had some other issue not covered by a 422 response |\n| 401 | Unauthenticated | The API key or token is invalid, expired or revoked |\n| 403 | Unauthorized | The user associated with the API key or token does not have sufficient permission to perform the action |\n| 404 | Endpoint Not Found | \\- |\n| 405 | Method Not Allowed | Using the wrong HTTP verb in the request |\n| 409 | Conflict | This usually occurs when attempt to create something that already exists |\n| 413 | Content too large | This may be encountered when initialising a flow with a payload |\n| 415 | Unsupported Media Type | The content-type header value is incorrect, please ensure it is `application/json` |\n| 422 | Unprocessible Request | The content in the request has failed validation. Please see the response for a description of errors |\n| 429 | Too Many Requests | You have hit a rate limit |\n| 500 | Server Error | Something went wrong on the receiving server |\n\nThe most common error is a 422 Unprocessible Request. This means that the request was valid but the server could not process it. The response will contain a JSON object with a description of the error, usually in this format:\n\n``` json\n{\n  \"message\": \"...\",\n  \"errors\": {\n    \"field1\": [\n      {\"rule\":  \"failure reason\"}\n    ]\n  }\n}\n\n ```\n\nWhere `field1` is the name of the field that failed validation, `rule` is the name of the validation rule that failed, and `failure reason` is the reason why validation failed.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"27117242","team":6143955,"collectionId":"b6e10dc3-3c97-408e-a302-1102ebdecd3d","publishedId":"2sB3HjLfyM","public":true,"publicUrl":"https://postman.wearepatchworks.com","privateUrl":"https://go.postman.co/documentation/27117242-b6e10dc3-3c97-408e-a302-1102ebdecd3d","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FFC309"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":"https://content.pstmn.io/f5a51385-d924-4389-8540-ff388ef49696/My1Ib3Jpem9udGFsIGxvZ28gLSBZZWxsb3cucG5n","colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"FFC309"}},{"name":"light","logo":"https://content.pstmn.io/f5a51385-d924-4389-8540-ff388ef49696/My1Ib3Jpem9udGFsIGxvZ28gLSBZZWxsb3cucG5n","colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FFC309"}}]}},"version":"8.10.1","publishDate":"2025-09-02T14:26:33.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":"https://content.pstmn.io/f5a51385-d924-4389-8540-ff388ef49696/My1Ib3Jpem9udGFsIGxvZ28gLSBZZWxsb3cucG5n","logoDark":"https://content.pstmn.io/f5a51385-d924-4389-8540-ff388ef49696/My1Ib3Jpem9udGFsIGxvZ28gLSBZZWxsb3cucG5n"}},"statusCode":200},"environments":[{"name":"Production","id":"36d95d76-b181-4808-8cca-89e92712d4a2","owner":"18910483","values":[{"key":"username","value":"","enabled":true,"type":"default"},{"key":"password","value":"","enabled":true,"type":"secret"}],"published":true}],"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/34163c75692ac9e6b996e9b3f3cc33f8fc3390b26eeccde7d1d598a8e38bd1da","favicon":"https://wearepatchworks.com/favicon.ico"},"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"},{"label":"Production","value":"18910483-36d95d76-b181-4808-8cca-89e92712d4a2"}],"canonicalUrl":"https://postman.wearepatchworks.com/view/metadata/2sB3HjLfyM"}