> For the complete documentation index, see [llms.txt](https://interfacing.gitbook.io/interfacing-help-files/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://interfacing.gitbook.io/interfacing-help-files/solutions-developers/api-and-information-repository/rest-apis.md).

# REST APIs

IMS provides a complete set of REST APIs to integrate with other systems and build automated services. Anything you can do in IMS can also be done through its APIs.

## Getting Started

To start using IMS APIs, you'll need:

1. An active **IMS user account**
2. Your organization’s **IMS base URL**\
   e.g., `https://yourims.interfacing.com`
3. **Authenticate** to obtain a valid token

***

## Authentication & Token Management

### How Authentication Works

* IMS uses **JWT (JSON Web Tokens)** to identify users.
* API access is **user-based,** just like in IMS.
  * You only see what the user has permission to see.
* Tokens are linked to a **session**, which can expire or be terminated.
* Admin functions will **fail** if the token doesn't belong to an admin user.

<details>

<summary>Session &#x26; Token Expiry</summary>

* **Session Timeout:**\
  Set via `SESSION_TIMEOUT` (minutes) in *<mark style="color:red;">System Admin > Advanced tab</mark>*\
  Token becomes invalid if session ends.
* **Token Expiry:**\
  Set via `WEBTOKEN_EXPIRES_IN` (days) in *<mark style="color:red;">System Admin > Advanced tab</mark>*

{% hint style="info" %}
Only System Admin users can modify these settings.
{% endhint %}

</details>

<details>

<summary>How to Manually Terminate a Session</summary>

* Go to <mark style="color:red;">**System Admin > General tab**</mark>
* Locate <mark style="color:red;">**Manage IMS Sessions**</mark>
* Click 🗑️ next to the session to end it

</details>

### How to Get an Access Token

1. Send a **POST** request to `https://YOURIMS.interfacing.com/api/v1/login/local` \
   with a JSON body containing the username and password.
2. The response will include a Cookie named `access_token`. \
   You can either use this Cookie for subsequent API calls or extract the token and send it in the HTTP header as a Bearer token. \
   \
   **Example of this exchange:**

```json
15:35:15.889 request:
1 > POST https://localhost/login/local
1 > Content-Type: application/json; charset=UTF-8
1 > Content-Length: 45
1 > Host: localhost
1 > Connection: Keep-Alive
1 > User-Agent: Apache-HttpClient/4.5.13 (Java/11.0.15)
1 > Accept-Encoding: gzip,deflate
{
  "password": "Passw0rd",
  "username": "myimsuser"
}
15:35:16.011 response time in milliseconds: 122
1 < 302
1 < Date: Wed, 08 Jun 2022 19:35:16 GMT
1 < Content-Type: text/plain; charset=utf-8
1 < Content-Length: 23
1 < Connection: keep-alive
1 < Cache-Control: no-store
1 < Set-Cookie: [loginsuccess=true; Path=/, access_token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...; Expires=Thu, 01 Jan 1970 00:00:00 GMT]
1 < Location: /
1 < Vary: Accept
1 < Age: 0
1 < Via: 1.1 varnish (Varnish/7.1)
1 < X-Frame-Options: SAMEORIGIN
1 < X-XSS-Protection: 1; mode=block
1 < X-Content-Type-Options: nosniff
1 < Referrer-Policy: no-referrer-when-downgrade
1 < Content-Security-Policy: default-src 'self' http: https: data: blob: 'unsafe-inline' 'unsafe-eval'
1 < Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
1 < X_SRV: EPC
```

**CURL Example:**

```bash
curl --request POST --url 'https://myims.interfacing.com/login/local' --header 'Content-Type: application/json' --data '{"username": "myecpuser", "password": "Passw0rd"}' -c /tmp/cookie.tmp
```

**JAVA sample code using Spring Boot:**

```java
package com.interfacing.ims.sync.bpc.client;
import java.util.Optional;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.ApplicationContextException;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseCookie;
import org.springframework.web.reactive.function.BodyInserters;
import org.springframework.web.reactive.function.client.WebClient;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import reactor.core.publisher.Mono;
import com.interfacing.epc.sync.util.WebClientUtils;
@Configuration
@RequiredArgsConstructor
@Slf4j
public class BpcWebClient {
    private final WebClient.Builder webClientBuilder;
    @Value("${bpc.baseUrl}")
    private String baseUrl;
    @Value("${bpc.username}")
    private String username;
    @Value("${bpc.password}")
    private String password;
    @Value("${bpc.wiretap}")
    private boolean wiretap;
    @Bean
    public WebClient bpcClient() {
        WebClient.Builder clientBuilder = webClientBuilder.baseUrl(baseUrl + "/api/v1").defaultHeader(HttpHeaders.AUTHORIZATION, authorization());
        log.debug("BPC client created");
        return WebClientUtils.build(clientBuilder, this.getClass().getPackageName() + ".bpcClient", wiretap);
    }
    private String authorization() {
        WebClient.Builder clientBuilder = webClientBuilder.clone().baseUrl(baseUrl + "/login/local");
        Optional<ResponseCookie> s = WebClientUtils.build(clientBuilder, this.getClass().getPackageName() + ".authorization", wiretap)
                .post()
                .contentType(MediaType.APPLICATION_JSON)
                .body(BodyInserters.fromValue(new LoginRequest(username, password)))
                .exchangeToMono(r -> Mono.justOrEmpty(r.cookies().getFirst("access_token")))
                .blockOptional();
        if (s.isPresent())
        {
            return "Bearer " + s.get().getValue();
        }
        else
        {
            throw new ApplicationContextException("Invalid username/password for BPC");
        }
    }
}
```

***

## Basic API Workflow Example

These examples walk through the full lifecycle of an IMS object. You'll learn how to **create, retrieve, update, and delete** a first-level document folder using the APIs.

{% stepper %}
{% step %}

### Create a first-level document folder

In the API, a first-level document folder is a **set**. To create one, you need to include three required fields:

* **Parent node ID**: This is the environment where the folder will be created.
  * *(For deeper folders, second level and beyond, the parent would be the ID of the folder above it.)*
* **Node type**: Use `"DOCUMENT_SET"` for a first-level folder.
* **Name**: Choose a name for your new folder.

**Endpoint:** `POST http://myims.interfacing.com/api/v1/items`&#x20;

**Request & Response Examples:**

```json
15:35:11.219 request:
1 > POST http://myims.interfacing.com/api/v1/items?draft=true
1 > Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
1 > Content-Type: application/json; charset=UTF-8
1 > Content-Length: 139
1 > Host: myims.interfacing.com
1 > Connection: Keep-Alive
1 > User-Agent: Apache-HttpClient/4.5.13 (Java/11.0.15)
1 > Accept-Encoding: gzip,deflate
{
  "parent": {
    "nodeId": "A9CCB5F4-9A79-8AE7-8C4C-289A025D0D88"
  },
  "@type": "NodeElement",
  "name": "my first document set",
  "nodeType": "DOCUMENT_SET"
}
```

```json
15:35:11.276 response time in milliseconds: 57
1 < 200
1 < Server: nginx/1.21.6
1 < Date: Wed, 08 Jun 2022 19:35:11 GMT
1 < Content-Type: application/json
1 < Content-Length: 526
1 < X-Varnish: 198276
1 < Age: 0
1 < Via: 1.1 varnish (Varnish/7.1)
1 < Connection: keep-alive
{
  "nodeSubTypeName": null,
  "userNodeSubType": null,
  "@type": "BaseElement",
  "nodeVersionId": "413426F8-66D4-49F6-843C-2F7AFEB298F5",
  "nodeType": "DOCUMENT_SET",
  "creationDate": "2022-06-08T15:35:11.253-04:00",
  "nodeStatus": "IN_PROGRESS",
  "publishedNodeVersionId": null,
  "version": "0.0001",
  "nodeSubType": null,
  "modificationDate": "2022-06-08T15:35:11.253-04:00",
  "extensions": null,
  "deleted": false,
  "system": false,
  "referenceNumber": null,
  "name": "my first document set",
  "locked": false,
  "nodeId": "1450CEF9-89A3-4B48-98F7-09735BECD54B",
  "favorite": false
}
```

**CURL Example:**

```bash
curl --request POST --url 'http://myims.interfacing.com/api/v1/items?draft=true' --header 'Content-Type: application/json' -b /tmp/cookie.tmp \
--data '{
"parent": {
"nodeId": "A9CCB5F4-9A79-8AE7-8C4C-289A025D0D88"
},
"@type": "NodeElement",
"name": "my first document set",
"nodeType": "DOCUMENT_SET"
}'
```

After you send the request, the response will include metadata such as the `nodeId` and `nodeVersionId`, which you'll need later for updates or deletion.<br>
{% endstep %}

{% step %}

### Retrieve a first-level document folder

To retrieve an existing first-level folder, simply make a GET request with its `nodeId`.

**Endpoint:** `GET http://myims.interfacing.com/api/v1/items/{nodeId}?draft=true`&#x20;

**Request & Response Examples:**

```json
15:35:11.279 request:
2 > GET http://myims.interfacing.com/api/v1/items/1450CEF9-89A3-4B48-98F7-09735BECD54B?draft=true
2 > Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
2 > Host: myims.interfacing.com
2 > Connection: Keep-Alive
2 > User-Agent: Apache-HttpClient/4.5.13 (Java/11.0.15)
2 > Accept-Encoding: gzip,deflate
```

```json
15:35:11.351 response time in milliseconds: 71
2 < 200
2 < Server: nginx/1.21.6
2 < Date: Wed, 08 Jun 2022 19:35:11 GMT
2 < Content-Type: application/json
2 < Content-Length: 526
2 < ETag: W/"06DE9CB7-1E56-49D1-A373-00DFAA8C1C1A|2022-06-08 19:35:11.26"
2 < Cache-Control: no-cache, no-transform, private
2 < X-Varnish: 819211
2 < Age: 0
2 < Via: 1.1 varnish (Varnish/7.1)
2 < Connection: keep-alive
{
  "nodeSubTypeName": null,
  "userNodeSubType": null,
  "@type": "BaseElement",
  "nodeVersionId": "413426F8-66D4-49F6-843C-2F7AFEB298F5",
  "nodeType": "DOCUMENT_SET",
  "creationDate": "2022-06-08T15:35:11.253-04:00",
  "nodeStatus": "IN_PROGRESS",
  "publishedNodeVersionId": null,
  "version": "0.0001",
  "nodeSubType": null,
  "modificationDate": "2022-06-08T15:35:11.253-04:00",
  "extensions": null,
  "deleted": false,
  "system": false,
  "referenceNumber": null,
  "name": "my first document set",
  "locked": false,
  "nodeId": "1450CEF9-89A3-4B48-98F7-09735BECD54B",
  "favorite": false
}
```

**CURL Example:**

```bash
curl --request GET --url 'http://myims.interfacing.com/api/v1/items/1450CEF9-89A3-4B48-98F7-09735BECD54B?draft=true' -b /tmp/cookie.tmp
```

The response will return the full details of the document set, just like when it was first created.

{% endstep %}

{% step %}

### Update a first-level document set

To update, you must send the full structure of the updated object, including:

* The `nodeId`
* The current `nodeVersionId`
* Any desired updates (e.g., a new name)

**Endpoint:**`PUT http://myims.interfacing.com/api/v1/items/[nodeId]`&#x20;

**Request & Response Examples:**

```json
15:35:11.354 request:
3 > PUT http://myims.interfacing.com/api/v1/items/1450CEF9-89A3-4B48-98F7-09735BECD54B?draft=true
3 > Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
3 > Content-Type: application/json; charset=UTF-8
3 > Content-Length: 229
3 > Host: myims.interfacing.com
3 > Connection: Keep-Alive
3 > User-Agent: Apache-HttpClient/4.5.13 (Java/11.0.15)
3 > Accept-Encoding: gzip,deflate
{
  "parent": {
    "nodeId": "A9CCB5F4-9A79-8AE7-8C4C-289A025D0D88"
  },
  "@type": "NodeElement",
  "nodeVersionId": "413426F8-66D4-49F6-843C-2F7AFEB298F5",
  "name": "new name",
  "nodeType": "DOCUMENT_SET",
  "nodeId": "1450CEF9-89A3-4B48-98F7-09735BECD54B"
}
```

```json
15:35:11.440 response time in milliseconds: 86
3 < 200
3 < Server: nginx/1.21.6
3 < Date: Wed, 08 Jun 2022 19:35:11 GMT
3 < Content-Type: application/json
3 < Content-Length: 513
3 < X-Varnish: 198279
3 < Age: 0
3 < Via: 1.1 varnish (Varnish/7.1)
3 < Connection: keep-alive
{
  "nodeSubTypeName": null,
  "userNodeSubType": null,
  "@type": "BaseElement",
  "nodeVersionId": "BFA4C9F0-89C6-46C1-BD93-7CE15988BF5C",
  "nodeType": "DOCUMENT_SET",
  "creationDate": "2022-06-08T15:35:11.253-04:00",
  "nodeStatus": "IN_PROGRESS",
  "publishedNodeVersionId": null,
  "version": "0.0002",
  "nodeSubType": null,
  "modificationDate": "2022-06-08T15:35:11.367-04:00",
  "extensions": null,
  "deleted": false,
  "system": false,
  "referenceNumber": null,
  "name": "new name",
  "locked": false,
  "nodeId": "1450CEF9-89A3-4B48-98F7-09735BECD54B",
  "favorite": false
}
```

**CURL Example:**

```bash
curl --request PUT --url 'http://myims.interfacing.com/api/v1/items/1450CEF9-89A3-4B48-98F7-09735BECD54B?draft=true' --header 'Content-Type: application/json' -b /tmp/cookie.tmp \
--data '{
"parent": {
"nodeId": "A9CCB5F4-9A79-8AE7-8C4C-289A025D0D88"
},
"@type": "NodeElement",
"nodeVersionId": "413426F8-66D4-49F6-843C-2F7AFEB298F5",
"name": "new name",
"nodeType": "DOCUMENT_SET",
"nodeId": "1450CEF9-89A3-4B48-98F7-09735BECD54B"
}'
```

The response will include the updated metadata, such as the new `nodeVersionId` and version number.

{% endstep %}

{% step %}

### Delete a first-level document folder

To delete a document set, send a DELETE request with the object’s `nodeId` in the URL. The request body should be empty (`{}`).

**Endpoint:** `DELETE http://myims.interfacing.com/api/v1/items/[nodeId]`&#x20;

**Request & Response Examples:**

```json
15:35:11.441 request:
4 > DELETE http://myims.interfacing.com/api/v1/items/1450CEF9-89A3-4B48-98F7-09735BECD54B?draft=true
4 > Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
4 > Content-Type: application/json; charset=UTF-8
4 > Content-Length: 2
4 > Host: myims.interfacing.com
4 > Connection: Keep-Alive
4 > User-Agent: Apache-HttpClient/4.5.13 (Java/11.0.15)
4 > Accept-Encoding: gzip,deflate
{
}
```

```json
15:35:11.617 response time in milliseconds: 176
4 < 200
4 < Server: nginx/1.21.6
4 < Date: Wed, 08 Jun 2022 19:35:11 GMT
4 < Content-Type: application/json
4 < Content-Length: 514
4 < X-Varnish: 819214
4 < Age: 0
4 < Via: 1.1 varnish (Varnish/7.1)
4 < Connection: keep-alive
[
  {
    "nodeSubTypeName": null,
    "userNodeSubType": null,
    "@type": "BaseElement",
    "nodeVersionId": "BFA4C9F0-89C6-46C1-BD93-7CE15988BF5C",
    "nodeType": "DOCUMENT_SET",
    "creationDate": "2022-06-08T15:35:11.253-04:00",
    "nodeStatus": "IN_PROGRESS",
    "publishedNodeVersionId": null,
    "version": "0.0002",
    "nodeSubType": null,
    "modificationDate": "2022-06-08T15:35:11.500-04:00",
    "extensions": null,
    "deleted": true,
    "system": false,
    "referenceNumber": null,
    "name": "new name",
    "locked": false,
    "nodeId": "1450CEF9-89A3-4B48-98F7-09735BECD54B",
    "favorite": false
  }
```

**CURL Example:**

```bash
curl --request DELETE --url 'http://myims.interfacing.com/api/v1/items/1450CEF9-89A3-4B48-98F7-09735BECD54B?draft=true' --header 'Content-Type: application/json' -b /tmp/cookie.tmp \
--data '{}'
```

The response confirms the deletion and includes the object's information.
{% endstep %}
{% endstepper %}

## See Also

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-cover data-type="files"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td>Use Cases &#x26; Examples</td><td><a href="https://1488562728-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTx7AmE0d2Q4ja20EYjF5%2Fuploads%2FjheFC4gpfJlXheXmkBbO%2FIMS-V16-NAV-Library-Icons-13.png?alt=media&amp;token=4c677fff-fe2e-4d31-987b-8f97ffe586dc">IMS-V16-NAV-Library-Icons-13.png</a></td><td><a href="/interfacing-help-files/solutions-developers/api-and-information-repository/rest-apis/use-cases-and-examples.md">Use Cases &amp; Examples</a></td></tr><tr><td>API Reference (Swagger)</td><td><a href="https://1488562728-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTx7AmE0d2Q4ja20EYjF5%2Fuploads%2FuIm0jP36LBJWUKIgHGxl%2FIMS-V16-NAV-Library-Icons-41.png?alt=media&amp;token=a91c1498-c99a-4013-b6bd-5877df0a71bb">IMS-V16-NAV-Library-Icons-41.png</a></td><td><a href="/interfacing-help-files/solutions-developers/api-and-information-repository/rest-apis/api-reference-swagger.md">API Reference (Swagger)</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://interfacing.gitbook.io/interfacing-help-files/solutions-developers/api-and-information-repository/rest-apis.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.