--- title: "Endpoints for Entity Objects" slug: "endpoints-for-entity-objects" updated: 2026-10-24T11:07:31Z published: 2026-10-24T11:07:31Z canonical: "documentation.decisions.com/endpoints-for-entity-objects" --- > ## Documentation Index > Fetch the complete documentation index at: https://documentation.decisions.com/llms.txt > Use this file to discover all available pages before exploring further. # Endpoints for Entity Objects Use these endpoints to get, create, update, or delete entity objects in your ProcessMaker IDP instance. Optionally, filter, sort, and/or paginate results when you receive results. ## Base URL for Entity Object Endpoints You can access the server via `https://{idp-server}/datastore/api/rest`. Each entity type has its own endpoint and is identified by its type: `/{type}`. ## Gets a collection of entity objects by their type. `GET` `https://{idp-server}/datastore/api/rest/{type}` See `200` status code response for cURL example. #### Path Parameters | Name | Type | Description | | --- | --- | --- | | type* | String | Entity type to get. | **200** **200: OK** Example of getting a collection of file entities: **cURL request:** ```plaintext curl --location --request GET "https://processmaker-idp.com/datastore/api/rest/file" ``` **400** **400: Bad Request Incorrect or incomplete.** **401** **401: Unauthorized.** **404** **404: Not Found Collection with the specified type does not exist.** **500** **500: Internal server error.** ## Gets one type's entity object by its unique ID. `GET` `https://{idp-server}/datastore/api/rest/{type}/{id}` See `200` status code response for cURL example and response example. #### Path Parameters | Name | Type | Description | | --- | --- | --- | | type* | String | Entity type related to the entity to get. | | id* | String | Unique ID of the entity to get in that type. | **200** **200: OK** Example of getting a file entity with ID `d72c9a40-8ef1-4c16-94c8-038cd9b80089`: **cURL request:** ```plaintext curl --location --request GET "https://processmaker-idp.com/datastore/api/rest/file/d72c9a40-8ef1-4c16-94c8-038cd9b80089" ``` **Example response:** The request was okay and the response body contains the representation requested. ```json {  "data": {    "type": "file",    "attributes": {      "createdAt": "2019-11-29T09:46:29.006+0000",      "createdBy": "User",      "documentType": "NONE",      "modifiedAt": "2019-12-03T07:41:33.445+0000",      "name": "Welcome to IDP.docx",      "modifiedBy": null,      "checkedOutBy": null,      "id": "d72c9a40-8ef1-4c16-94c8-038cd9b80089",      "content": 117350    },    "relations": {}  },  "status": "success",  "message": null } ``` **500** **500: Internal server error.** **400** **400: Bad Request Incorrect, incomplete, non-existing type or ID.** **404** **404: Not Found Entity with the specified ID in the specified type not found.** **401** **401: Unauthorized.** ## Gets the content (binary) of a type's entity object by its unique ID. `GET` `https://{idp-server}/datastore/api/rest/{attribute}/{type}/{id}` Unlike other GET method endpoints, this endpoint uses a `type` entity called `file`. The attribute that contains the binary, which is the file to download, is called `content`. See `200` status code response for cURL example. #### Path Parameters | Name | Type | Description | | --- | --- | --- | | attribute* | String | Attribute that contains the binary. | | type* | String | Entity type related to the entity to get. | | id | String | Unique ID of the entity to get in that type. | **200** **200: OK** Example of getting a file entity with ID `17478078-52cf-4472-ab98-1b27a10b71c9`: **cURL request:** ```plaintext curl --location --request GET "https://processmaker-idp.com/datastore/api/rest/content/file/17478078-52cf-4472-ab98-1b27a10b71c9" ``` **400** **400: Bad Request Incorrect, incomplete, non-existing type or ID.** **401** **401: Unauthorized** **404** **404: Not Found Entity with the specified ID in the specified type not found** **500** **500: Internal Server Error** ## Gets resources related to an entity object. `GET` `https://{idp-server}/datastore/api/rest/{type}/{id}/{relation}` See `200` status code response for cURL example. #### Path Parameters | Name | Type | Description | | --- | --- | --- | | type* | String | Entity type related to the entity to get. | | id* | String | Unique ID for the entity to get in that type. | | relation* | String | Relation name for the entity to get. | **200: OK OK.** Example of getting a folder with name `5f97858b-26e3-4180-80c4-25b176cbc35f`: **cURL request:** ```plaintext curl --location --request GET "https://processmaker-idp.com/api/rest/folder/5f97858b-26e3-4180-80c4-25b176cbc35f/files" ``` **400: Bad Request Incorrect, incomplete, non-existing type, ID, or relation.** **401: Unauthorized Unauthorized.** **404: Not Found Entity by the specified ID in the specified type for the specified relation not found.** **500: Internal Server Error Internal server error.** ## Filter by name of entity object result. `GET` `https://{idp-server}/datastore/api/rest/{type}?filter%5Bname%5D={name}` **Note:** Due to an issue in Spring Framework, URL parameters in `GET` requests do not properly url-encode. When filtering for an entity containing a `+` character in its name, there are two ways to process this (see examples). For example, for the file `Welcome + to + IDP.docx` the `+` symbol gets encoded. See `200` status code response for URL examples. See examples 3 and 4 how to address the `+` character issue. #### Path Parameters | Name | Type | Description | | --- | --- | --- | | type* | String | Entity type related to the entity to get. | | name | String | Name of the entity object from which to filter results. Use exact characters as the entity object is named, including spaces. Note exception above regarding the `+` character. | **200: OK OK.** **Example 1:** Example for an entity filtered on name `Welcome to IDP.docx`: ```plaintext GET https:///datastore/api/rest/{type}?filter%5Bname%5D=Welcome to IDP.docx ``` **Example 2:** Example that uses multiple filters: ```plaintext GET https:///datastore/api/rest/{type}?filter%5Bname%5D=Welcome to IDP.docx&filter%5BcreatedB y%5D=admin ``` **Example 3:** Option 1 to encode the `+` character in a `GET` request: ```plaintext GET https:///datastore/api/rest/{type}?filter%5Bname%5D=Welcome %2B to %B2 IDP.docx ``` **Example 4:** Option 2 as alternative to encoding the `+` character by using a `POST` request: ```plaintext POST https:///datastore/api/rest/{type}/readAllPost {  "filter[name]": "Welcome + to + IDP.docx" } ``` **400: Bad Request Incorrect, incomplete, or non-existing type.** **401: Unauthorized Unauthorized.** **404: Not Found Entity by the specified name in the specified type not found.** **500: Internal Server Error Internal server error.** ## Sort results by providing the attribute(s) from which to sort, followed by sorting direction. `GET` `https://{idp-server}/datastore/api/rest/file?sort=` By default, results are sorted in ascending order. To sort in the opposite direction, add a minus character (`-`) preceding the attribute name. See `200` status code response for cURL example. **200: OK OK.** Example of a request to read files sorted in descending order by creation date: ```plaintext curl --location --request GET "https://processmaker-idp.com/datastore/api/rest/file?sort=- createdAt" ``` **400: Bad Request Incorrect, incomplete, or non-existing attribute(s).** **401: Unauthorized Unauthorized.** **404: Not Found Entity not found.** **500: Internal Server Error Internal server error.** ## Paginate results. `GET` `https://{idp-server}/datastore/api/rest/file?count=` The ProcessMaker IDP REST API uses cursor-based pagination (also known as keyset pagination). When no parameters for pagination are provided, default values for pagination apply. The returned response contains links that refer to the next and previous pages. Default count per page is 20. See `200` status code response for cURL example. #### Path Parameters | Name | Type | Description | | --- | --- | --- | | after | Integer | Returns the first item immediately after the cursor in the results list. Typically use to get the next page. | | before | Integer | Returns the last item in the paginated data to be closest to, but still before, the cursor in the non-paginated results list. Typically use to get the prior page. | | count | Integer | Number of entities per page. | **200: OK OK.** Example of a request with pagination parameters: **cURL request:** ```plaintext curl --location --request GET "https://processmaker-idp.com/datastore/api/rest/file?count=2\&after=1" ``` **Example response:** ```json {  "data": [    {      "type": "file",      "attributes": {        "createdAt": "2019-12-03T07:35:31.344+0000",        "createdBy": "User",        "documentType": "NONE",        "modifiedAt": null,        "name": "Welcome to IDP.docx",        "modifiedBy": null,        "checkedOutBy": null,        "id": "0e21bb8f-b8fd-42f7-872f-319389b313e8",        "content": 117334      }    },    {      "type": "file",      "attributes": {        "createdAt": "2019-12-02T12:11:19.815+0000",        "createdBy": "User",        "documentType": "NONE",        "modifiedAt": null,        "name": "Welcome at IDP.docx",        "modifiedBy": null,        "checkedOutBy": null,        "id": "0e73b1e6-c125-40e5-b634-b709c4089299",        "content": null      }    }  ],  "status": "success",  "message": null,  "links": {    "next": "/api/rest/file?count=2&after=3",    "prev": "/api/rest/file?count=2&before=2"  } } ``` **400: Bad Request Incorrect or incomplete.** **401: Unauthorized Unauthorized.** **404: Not Found Entity not found.** **500: Internal Server Error Internal server error.** ## Creates an entity object by specifying its entity type. `POST` `https://{idp-server}/datastore/api/rest/{type}` See `200` status code response for examples and a response example. See below this endpoint description for example how to create a file entity with a file. #### Path Parameters | Name | Type | Description | | --- | --- | --- | | type* | String | Entity type to create. | #### Request Body | Name | Type | Description | | --- | --- | --- | | data* | JSON String | Attributes specified as key/value pairs. When creating files or subfolders in a dossier, `parentId` JSON object is required. | | file | Binary Data | File to upload with your entity. | **200: OK OK.** **Example to create a dossier:** `type` is an attribute of `FOLDER`. Specify the name of the new dossier in the `name` JSON object. ```json { "attributes": { "name": "datastoreCreateDossierName", "type": "DOSSIER" } } ``` **Example to create a folder:** `type` is an attribute of `FOLDER`. Specify the name of the new folder in the `name` JSON object. `parentId` is required only when creating a folder to specify in which folder or dossier to create the new folder. ```json { "attributes": { "name": "datastoreCreateFolderName", "type": "FOLDER", "parentId": "de6b5bef-eca7-41db-84c9-17e1c0376d71" } } ``` **Example to create a file:** Specify the name of the new file in the `name` JSON object. ```json { "attributes": { "name": "datastoreCreateFileNameJPG", "parentId": "de6b5bef-eca7-41db-84c9-17e1c0376d71" } } ``` **Example response after successfully creating an entity object:** The request was okay and the response body contains the representation requested. The response contains all attributes of the created entity. This includes auto-generated attributes. ```json {  "data": {    "type": "file",    "attributes": {      "createdAt": "2023-12-03T12:47:06.960+0000",      "createdBy": "User",      "documentType": "NONE",      "modifiedAt": null,      "name": "Welcome to IDP.docx",      "modifiedBy": null,      "checkedOutBy": null,      "id": "127a9e31-395a-483e-8415-9456f44199d8",      "content": 125398,      "parentId": null    }  },  "status": "success",  "message": null } ``` **400: Bad Request Incorrect, incomplete, non-existing type.** **401: Unauthorized Requires authentication.** **500: Internal Server Error Internal server error.** **Example how to create a file entity with a file.** ```plaintext curl --location --request POST "https://processmaker-idp.com/datastore/api/rest/file"; $oRet = pmRestRequest("POST", $url, $afile); \--form "data={ \\"attributes\\": { \\"name\\": \\"Welcome to IDP.docx\\", \\"createdBy\\": \\"User\\" } }" \\ \--form "file=@/filesystem/Documents/Welcome to IDP.docx" ``` ## Updates one type's entity object by its unique ID. `PUT` `https://{idp-server}/datastore/api/rest/{type}/{id}` See `200` status code response for cURL example and response example. See below this endpoint description for example how to update a file entity with another file, thereby replacing it. #### Path Parameters | Name | Type | Description | | --- | --- | --- | | type* | String | Entity type related to the entity to update. | | id* | String | Unique ID for the entity to update in that type. | #### Request Body | Name | Type | Description | | --- | --- | --- | | data | JSON String | Attributes specified as key-value pairs. | | file | Multipartfile | The file to update. | **200: OK OK.** Example of updating a file entity with ID `d72c9a40-8ef1-4c16-94c8-038cd9b80089`, where both the attributes and the binary will be updated: **cURL request:** ```plaintext curl --location --request PUT "https://processmaker-idp.com/datastore/api/rest/file/d72c9a40-8ef1-4c16-94c8-038cd9b80089" ``` **Example response:** The request was okay and the response body contains the representation requested. The response contains all attributes of the updated entity. ```plaintext {  "data": {    "type": "file",    "attributes": {      "createdAt": "2023-12-03T12:47:06.960+0000",      "createdBy": "User",      "documentType": "NONE",      "modifiedAt": "2023-12-05T12:47:06.960+0000",      "name": "Welcome back to IDP.docx",      "modifiedBy": "User2",      "checkedOutBy": "User",      "id": "d72c9a40-8ef1-4c16-94c8-038cd9b80089",      "content": 125398,      "parentId": null    }  },  "status": "success",  "message": null } ``` **400: Bad Request Incorrect, incomplete, non-existing type or ID.** **401: Unauthorized Unauthorized.** **404: Not Found Entity with the specified ID in the specified type not found.** **500: Internal Server Error Internal server error.** **Example how to update a file entity with another file.** ```plaintext curl --location --request PUT "https://processmaker-idp.com/datastore/api/rest/file"; $oRet = pmRestRequest("PUT", $url, $afile); \--form "data={ \\"attributes\\": { \\"name\\": \\"Welcome back to IDP.docx\\", \\"createdBy\\": \\"User\\" } }" \\ \--form "file=@/filesystem/Documents/Welcome back to IDP.docx" ``` ## Deletes one type's entity object by its unique ID. `DELETE` `https://{idp-server}/datastore/api/rest/{type}/{id}` See `200` status code response for cURL example. See below this endpoint description for example how to delete a file entity. #### Path Parameters | Name | Type | Description | | --- | --- | --- | | type* | String | Entity type related to the entity to delete. | | id* | String | Unique ID of the entity to delete in that type. | **200: OK OK.** Example of deleting a file entity with ID `d72c9a40-8ef1-4c16-94c8-038cd9b80089`: **cURL request:** ```plaintext curl --location --request DELETE "https://processmaker-idp.com/datastore/api/rest/file/d72c9a40-8ef1-4c16-94c8-038cd9b80089" ``` **400: Bad Request Incorrect, incomplete, non-existing type or ID.** **401: Unauthorized Unauthorized.** **404: Not Found Entity with the specified ID in the specified type not found.** **500: Internal Server Error Internal server error.** ## Errors ProcessMaker IDP uses conventional HTTP response codes to indicate the success or failure of an API request. In general: - Codes in the `2xx` range indicate success. - Codes in the `4xx` range indicate an error that failed given the information provided (such as a required parameter was omitted or the provided ID does not exist). - Codes in the `5xx` range indicate an error with ProcessMaker IDP’s servers. Most `4xx` errors will return a message that briefly explains the reported error. Example of an error message: Status `400` Bad Request: ```json {  "data": null,  "status": "error",  "message": "Please provide JSON data and/or a file." } ```