Using Postman to interact with the CluedIn API

CluedIn provides REST and GraphQL APIs. You can use them to ingest data, export data, migrate configuration, and more. Because the web interface is a client of the API, you can automate anything you can do through the interface.

You can follow this article with any programming language, command-line tools such as curl and wget, or apps such as Insomnia and Nightingale. I'll use Postman, a popular tool for working with APIs.

Let's spin up a CluedIn instance, open Postman, and begin.

Environment setup

My CluedIn instance is available at https://foobar.172.167.52.102.sslip.io/.

In this URL, the foobar subdomain is the organization name. You need it because a CluedIn instance can host several organizations, each with its own users, settings, and data.

The 172.167.52.102.sslip.io part is the main domain assigned when you install CluedIn from Azure Marketplace. You can also configure a custom domain such as mdm.contoso.com.

In Postman, create your own collection or import the collection I use.

Next, create an environment to store the domain and credentials. With this template, you only need to change a few values:

• domain: 172.167.52.102.sslip.io in my case.
• org_name: the organization name, which is foobar in my case.
• protocol: use https unless you run CluedIn locally in Docker.
• user_email and password: the credentials for your user account. Some APIs require a user's access token, while others accept an API token created in the web interface. You can omit these credentials when using an API token.

The environment also contains several predefined URLs:

• org_url: {{protocol}}://{{org_name}}.{{domain}} resolves to https://foobar.172.167.52.102.sslip.io. The other CluedIn API URLs build on this value.
• auth_url: {{org_url}}/auth resolves to https://foobar.172.167.52.102.sslip.io/auth. Use it to sign in with an email and password, create users, and perform other authentication tasks.
• api_url: {{org_url}}/api/api resolves to https://foobar.172.167.52.102.sslip.io/api/api. Most APIs live under this URL.
• graphql_api_url: {{api_url}}/graphql resolves to https://foobar.172.167.52.102.sslip.io/api/api/graphql. This is the GraphQL endpoint for exporting data, and it accepts an API token created in the CluedIn interface.
• graphql_url: {{org_url}}/graphql resolves to https://foobar.172.167.52.102.sslip.io/graphql. The web interface uses this GraphQL endpoint for its own operations. It requires a user's access token and does not accept API tokens.

Get a token

Now use Postman to call the sign-in API and get a user's access token.

Call the "Get a Token" endpoint:

After a successful request, the collection automatically adds a few variables to the environment:

• access_token: the JWT used to access the CluedIn API.
• refresh_token: the token used to refresh the access token.
• org_id: the organization identifier required by some calls. Saving it here means you don't need to fetch it separately.

Call CluedIn APIs

Now you can call CluedIn APIs. For example, try calling "Get Schema" to get the full list of CluedIn Vocabulary keys and their mappings:

Conclusion

A few useful reminders:

• Anything you can do through the CluedIn interface can be automated through its APIs.
• To inspect requests from the interface, use the browser's Network tab or an extension such as GraphQL Network Inspector.
• The CluedIn Documentation Portal is updated regularly and contains many more examples.