# Endpoints for Entity Objects

## 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.

<mark style="color:blue;">`GET`</mark> `https://{idp-server}/datastore/api/rest/{type}`

See `200` status code response for cURL example.

#### Path Parameters

| Name                                   | Type   | Description         |
| -------------------------------------- | ------ | ------------------- |
| type<mark style="color:red;">\*</mark> | String | Entity type to get. |

{% tabs %}
{% tab title="200: OK OK." %}
Example of getting a collection of file entities:

**cURL request:**

```
curl --location --request GET "https://processmaker-idp.com/datastore/api/rest/file"
```

{% endtab %}

{% tab title="400: Bad Request Incorrect or incomplete." %}

{% endtab %}

{% tab title="401: Unauthorized Unauthorized." %}

{% endtab %}

{% tab title="404: Not Found Collection with the specified type does not exist." %}

{% endtab %}

{% tab title="500: Internal Server Error Internal server error." %}

{% endtab %}
{% endtabs %}

## Gets one type's entity object by its unique ID.

<mark style="color:blue;">`GET`</mark> `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<mark style="color:red;">\*</mark> | String | Entity type related to the entity to get.    |
| id<mark style="color:red;">\*</mark>   | String | Unique ID of the entity to get in that type. |

{% tabs %}
{% tab title="200: OK OK." %}
Example of getting a file entity with ID `d72c9a40-8ef1-4c16-94c8-038cd9b80089`:

**cURL request:**

```
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
}
```

{% endtab %}

{% tab title="500: Internal Server Error Internal server error." %}

{% endtab %}

{% tab title="400: Bad Request Incorrect, incomplete, non-existing type or ID." %}

{% endtab %}

{% tab title="404: Not Found Entity with the specified ID in the specified type not found." %}

{% endtab %}

{% tab title="401: Unauthorized Unauthorized." %}

{% endtab %}
{% endtabs %}

## Gets the content (binary) of a type's entity object by its unique ID.

<mark style="color:blue;">`GET`</mark> `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<mark style="color:red;">\*</mark> | String | Attribute that contains the binary.          |
| type<mark style="color:red;">\*</mark>      | String | Entity type related to the entity to get.    |
| id                                          | String | Unique ID of the entity to get in that type. |

{% tabs %}
{% tab title="200: OK OK." %}
Example of getting a file entity with ID `17478078-52cf-4472-ab98-1b27a10b71c9`:

**cURL request:**

```
curl --location --request GET "https://processmaker-idp.com/datastore/api/rest/content/file/17478078-52cf-4472-ab98-1b27a10b71c9"
```

{% endtab %}

{% tab title="400: Bad Request Incorrect, incomplete, non-existing type or ID." %}

{% endtab %}

{% tab title="401: Unauthorized Unauthorized." %}

{% endtab %}

{% tab title="404: Not Found Entity with the specified ID in the specified type not found." %}

{% endtab %}

{% tab title="500: Internal Server Error Internal server error." %}

{% endtab %}
{% endtabs %}

## Gets resources related to an entity object.

<mark style="color:blue;">`GET`</mark> `https://{idp-server}/datastore/api/rest/{type}/{id}/{relation}`

See `200` status code response for cURL example.

#### Path Parameters

| Name                                       | Type   | Description                                   |
| ------------------------------------------ | ------ | --------------------------------------------- |
| type<mark style="color:red;">\*</mark>     | String | Entity type related to the entity to get.     |
| id<mark style="color:red;">\*</mark>       | String | Unique ID for the entity to get in that type. |
| relation<mark style="color:red;">\*</mark> | String | Relation name for the entity to get.          |

{% tabs %}
{% tab title="200: OK OK." %}
Example of getting a folder with name `5f97858b-26e3-4180-80c4-25b176cbc35f`:

**cURL request:**

```
curl --location --request GET
"https://processmaker-idp.com/api/rest/folder/5f97858b-26e3-4180-80c4-25b176cbc35f/files"
```

{% endtab %}

{% tab title="400: Bad Request Incorrect, incomplete, non-existing type, ID, or relation." %}

{% endtab %}

{% tab title="401: Unauthorized Unauthorized." %}

{% endtab %}

{% tab title="404: Not Found Entity by the specified ID in the specified type for the specified relation not found." %}

{% endtab %}

{% tab title="500: Internal Server Error Internal server error." %}

{% endtab %}
{% endtabs %}

## Filter by name of entity object result.

<mark style="color:blue;">`GET`</mark> `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<mark style="color:red;">\*</mark> | 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. |

{% tabs %}
{% tab title="200: OK OK." %}
**Example 1:** Example for an entity filtered on name `Welcome to IDP.docx`:

```
GET https://<idp-server-url>/datastore/api/rest/{type}?filter%5Bname%5D=Welcome to IDP.docx
```

**Example 2:** Example that uses multiple filters:

```
GET https://<idp-server-url>/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:

```
GET https://<idp-server-url>/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:

```
POST https://<idp-server-url>/datastore/api/rest/{type}/readAllPost
{
  "filter[name]": "Welcome + to + IDP.docx"
}
```

{% endtab %}

{% tab title="400: Bad Request Incorrect, incomplete, or non-existing type." %}

{% endtab %}

{% tab title="401: Unauthorized Unauthorized." %}

{% endtab %}

{% tab title="404: Not Found Entity by the specified name in the specified type not found." %}

{% endtab %}

{% tab title="500: Internal Server Error Internal server error." %}

{% endtab %}
{% endtabs %}

## Sort results by providing the attribute(s) from which to sort, followed by sorting direction.

<mark style="color:blue;">`GET`</mark> `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.

{% tabs %}
{% tab title="200: OK OK." %}
Example of a request to read files sorted in descending order by creation date:

```
curl --location --request GET "https://processmaker-idp.com/datastore/api/rest/file?sort=-
createdAt"
```

{% endtab %}

{% tab title="400: Bad Request Incorrect, incomplete, or non-existing attribute(s)." %}

{% endtab %}

{% tab title="401: Unauthorized Unauthorized." %}

{% endtab %}

{% tab title="404: Not Found Entity not found." %}

{% endtab %}

{% tab title="500: Internal Server Error Internal server error." %}

{% endtab %}
{% endtabs %}

## Paginate results.

<mark style="color:blue;">`GET`</mark> `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.                                                                                                                                       |

{% tabs %}
{% tab title="200: OK OK." %}
Example of a request with pagination parameters:

**cURL request:**

```
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"
  }
}
```

{% endtab %}

{% tab title="400: Bad Request Incorrect or incomplete." %}

{% endtab %}

{% tab title="401: Unauthorized Unauthorized." %}

{% endtab %}

{% tab title="404: Not Found Entity not found." %}

{% endtab %}

{% tab title="500: Internal Server Error Internal server error." %}

{% endtab %}
{% endtabs %}

## Creates an entity object by specifying its entity type.

<mark style="color:green;">`POST`</mark> `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.&#x20;

#### Path Parameters

| Name                                   | Type   | Description            |
| -------------------------------------- | ------ | ---------------------- |
| type<mark style="color:red;">\*</mark> | String | Entity type to create. |

#### Request Body

| Name                                   | Type        | Description                                                                                                                  |
| -------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------- |
| data<mark style="color:red;">\*</mark> | 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.                                                                                             |

{% tabs %}
{% tab title="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
}
```

{% endtab %}

{% tab title="400: Bad Request Incorrect, incomplete, non-existing type." %}

{% endtab %}

{% tab title="401: Unauthorized Requires authentication." %}

{% endtab %}

{% tab title="500: Internal Server Error Internal server error." %}

{% endtab %}
{% endtabs %}

<details>

<summary>Example how to create a file entity with a file.</summary>

```
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"
```

</details>

## Updates one type's entity object by its unique ID.

<mark style="color:orange;">`PUT`</mark> `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<mark style="color:red;">\*</mark> | String | Entity type related to the entity to update.     |
| id<mark style="color:red;">\*</mark>   | 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.                      |

{% tabs %}
{% tab title="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:**

{% code fullWidth="false" %}

```
curl --location --request PUT "https://processmaker-idp.com/datastore/api/rest/file/d72c9a40-8ef1-4c16-94c8-038cd9b80089"
```

{% endcode %}

**Example response:**

The request was okay and the response body contains the representation requested. The response contains all attributes of the updated entity.

```
{
  "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
}
```

{% endtab %}

{% tab title="400: Bad Request Incorrect, incomplete, non-existing type or ID." %}

{% endtab %}

{% tab title="401: Unauthorized Unauthorized." %}

{% endtab %}

{% tab title="404: Not Found Entity with the specified ID in the specified type not found." %}

{% endtab %}

{% tab title="500: Internal Server Error Internal server error." %}

{% endtab %}
{% endtabs %}

<details>

<summary>Example how to update a file entity with another file.</summary>

```
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"
```

</details>

## Deletes one type's entity object by its unique ID.

<mark style="color:red;">`DELETE`</mark> `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<mark style="color:red;">\*</mark> | String | Entity type related to the entity to delete.    |
| id<mark style="color:red;">\*</mark>   | String | Unique ID of the entity to delete in that type. |

{% tabs %}
{% tab title="200: OK OK." %}
Example of deleting a file entity with ID `d72c9a40-8ef1-4c16-94c8-038cd9b80089`:

**cURL request:**

```
curl --location --request DELETE "https://processmaker-idp.com/datastore/api/rest/file/d72c9a40-8ef1-4c16-94c8-038cd9b80089"
```

{% endtab %}

{% tab title="400: Bad Request Incorrect, incomplete, non-existing type or ID." %}

{% endtab %}

{% tab title="401: Unauthorized Unauthorized." %}

{% endtab %}

{% tab title="404: Not Found Entity with the specified ID  in the specified type not found." %}

{% endtab %}

{% tab title="500: Internal Server Error Internal server error." %}

{% endtab %}
{% endtabs %}

## 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."
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://processmaker.gitbook.io/idp/idp-developer/endpoints-for-entity-objects.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.