--- title: Get started with the REST API url: https://documentation.cluedin.net/api/get-started content_type: how-to section: Develop & APIs > API reference --- # Get started with the REST API > how-to: Steps to accomplish one task. This page explains how to connect to the CluedIn REST API: base URLs, authentication, and the conventions that requests and responses follow. For the full list of endpoints, see the [API reference](https://documentation.cluedin.net/api.md). ## Interactive API explorer CluedIn exposes its OpenAPI reference through an interactive Scalar-based API explorer. The explorer lets you inspect endpoint paths, parameters, request and response schemas, authentication requirements, and example payloads without having to read the raw OpenAPI document. The categorized [API reference](https://documentation.cluedin.net/api.md) embeds the interactive explorer for each area of the platform. When connected to your environment, you can also use **Try it out** to send requests and inspect live responses. Scalar replaces the previous Swagger UI experience; the underlying CluedIn REST API and OpenAPI contract remain the source of truth for available endpoints. ## How the API is organized The API has more than 700 endpoints, grouped into [categories](https://documentation.cluedin.net/api.md). Rather than listing them alphabetically, the tree below organizes those categories around the **problem each one solves**, following the path data takes through CluedIn—from modeling and mastering it to delivering it back out, plus the categories that operate, secure, and automate the platform around that flow. Use it to find the right starting point: identify the question you are trying to answer, then open the matching category in the [API reference](https://documentation.cluedin.net/api.md). ```mermaid graph LR API["CluedIn REST API"] API --> OP["Operate the platform
Keep CluedIn running"] API --> MODEL["Model the data
Give data shared meaning"] API --> MASTER["Build golden records
Turn raw data into trusted records"] API --> FIND["Find & explore
Make records discoverable"] API --> OUT["Deliver data out
Send trusted data downstream"] API --> GOV["Govern & secure
Control who does what"] API --> AUTO["Automate & augment
Reduce manual effort"] OP --> admin["Administration & configuration
How do I manage settings, logs, and billing?"] OP --> org["Organization
How do I manage the organization profile?"] MODEL --> vocab["Vocabularies
How is my data typed and described?"] MODEL --> gloss["Glossary
What do our business terms mean?"] MODEL --> hier["Hierarchies
How is data organized into hierarchies?"] MASTER --> ent["Entities
What are my golden records?"] MASTER --> dedup["Deduplication
How do I find and resolve duplicate records?"] MASTER --> rules["Rules & evaluation
How are records transformed and merged?"] MASTER --> prep["Data preparation & enrichment
How do I clean and enrich records?"] FIND --> search["Search
How do I find records across the graph?"] OUT --> streams["Streams, connectors & export
How do I push data to other systems?"] GOV --> acl["Access control & governance
Who can do what; ownership and audit?"] AUTO --> ai["AI
How do I use AI agents, skills, and Copilot?"] %% CluedIn brand styling: navy root, teal phases, white category cards classDef root fill:#0d2547,stroke:#19cca3,stroke-width:2px,color:#ffffff; classDef phase fill:#19cca3,stroke:#13a384,stroke-width:1px,color:#0d2547; classDef cat fill:#ffffff,stroke:#d1d6dc,stroke-width:1px,color:#0d2547; class API root; class OP,MODEL,MASTER,FIND,OUT,GOV,AUTO phase; class admin,org,vocab,gloss,hier,ent,dedup,rules,prep,search,streams,acl,ai cat; %% Links to each category's API reference page click API href "/rest-api/api-reference" "All API reference categories" _self click admin href "/rest-api/api-reference/administration-and-configuration" "Administration & configuration reference" _self click org href "/rest-api/api-reference/organization" "Organization reference" _self click vocab href "/rest-api/api-reference/vocabularies" "Vocabularies reference" _self click gloss href "/rest-api/api-reference/glossary" "Glossary reference" _self click hier href "/rest-api/api-reference/hierarchies" "Hierarchies reference" _self click ent href "/rest-api/api-reference/entities" "Entities reference" _self click dedup href "/rest-api/api-reference/deduplication" "Deduplication reference" _self click rules href "/rest-api/api-reference/rules-and-evaluation" "Rules & evaluation reference" _self click prep href "/rest-api/api-reference/data-preparation-and-enrichment" "Data preparation & enrichment reference" _self click search href "/rest-api/api-reference/search" "Search reference" _self click streams href "/rest-api/api-reference/streams-and-export" "Streams, connectors & export reference" _self click acl href "/rest-api/api-reference/access-control-and-governance" "Access control & governance reference" _self click ai href "/rest-api/api-reference/ai" "AI reference" _self ``` ### What each category answers The table maps every category to the question it answers and links to its reference page. The endpoint counts give a sense of how much surface each area covers. | Phase | Category | The problem it answers | Endpoints | |---|---|---|---| | Operate the platform | [Administration & configuration](https://documentation.cluedin.net/api/administration-and-configuration.md) | How do I manage settings, logs, and metered billing? | 8 | | Operate the platform | [Organization](https://documentation.cluedin.net/api/organization.md) | How do I manage the organization profile and usage statistics? | 31 | | Model the data | [Vocabularies](https://documentation.cluedin.net/api/vocabularies.md) | How is my data typed and described with vocabulary keys? | 110 | | Model the data | [Glossary](https://documentation.cluedin.net/api/glossary.md) | What do our shared business terms mean? | 57 | | Model the data | [Hierarchies](https://documentation.cluedin.net/api/hierarchies.md) | How is data organized into hierarchies and the global data model? | 30 | | Build golden records | [Entities](https://documentation.cluedin.net/api/entities.md) | What are my golden records—how do I read, modify, and merge them? | 115 | | Build golden records | [Deduplication](https://documentation.cluedin.net/api/deduplication.md) | How do I find, review, and resolve duplicate records? | 61 | | Build golden records | [Rules & evaluation](https://documentation.cluedin.net/api/rules-and-evaluation.md) | How are records transformed, merged, and survived; what did a rule do? | 66 | | Build golden records | [Data preparation & enrichment](https://documentation.cluedin.net/api/data-preparation-and-enrichment.md) | How do I clean and enrich records? | 40 | | Find & explore | [Search](https://documentation.cluedin.net/api/search.md) | How do I find records across the graph and manage saved searches? | 49 | | Deliver data out | [Streams, connectors & export](https://documentation.cluedin.net/api/streams-and-export.md) | How do I push trusted data to downstream systems? | 62 | | Govern & secure | [Access control & governance](https://documentation.cluedin.net/api/access-control-and-governance.md) | Who can do what; how do I handle ownership, audit, and tags? | 33 | | Automate & augment | [AI](https://documentation.cluedin.net/api/ai.md) | How do I use AI agents, jobs, skills, and Copilot? | 59 | ## Base URL The API is served from your CluedIn environment under the `/api` path: ``` https://./api ``` Replace `.` with the host of your own CluedIn environment—for example, `https://acme.cluedin.com/api`. All requests must use HTTPS. ## Versioning Most endpoints are available both unversioned and with an explicit version prefix: ``` https://./api/accesscontrolpolicies https://./api/v1/accesscontrolpolicies ``` A small number of endpoints offer additional versions (for example, `/api/v2/search/suggest` and `/api/v3/search/suggest`). > **Important:** For stability, prefer the explicit versioned path (`/api/v1/...`). Each endpoint's exact path and available versions are shown in the [API reference](https://documentation.cluedin.net/api.md). ## Authentication The API uses **bearer token** authentication. Every request must include an `Authorization` header with a valid CluedIn API token: ``` Authorization: Bearer ``` Include the word `Bearer`, followed by a single space, before the token value. You generate API tokens in the CluedIn UI under **Administration** > **API Tokens**. For step-by-step instructions, see [Generate an API token](https://documentation.cluedin.net/administer/api-token.md). > **Important:** Treat API tokens as secrets. Store them in a secure location such as a password vault, never commit them to version control, and revoke them when they are no longer needed. ### Permissions Many endpoints require specific permissions in addition to a valid token. The required policy is shown in each endpoint's summary in the API reference (for example, `Auth policies: RACI:management.accesscontrol`). Make sure the token has been granted the corresponding scope; otherwise the request is rejected with `403 Forbidden`. ## Request and response format - Send request bodies as JSON with the `Content-Type: application/json` header. - Set `Accept: application/json` to receive JSON responses. - Responses are returned as JSON. Some endpoints also support `text/json` and `text/plain`. | Header | Value | When to send | |---|---|---| | `Authorization` | `Bearer ` | Every request. | | `Content-Type` | `application/json` | Requests that include a body (`POST`, `PUT`, `PATCH`). | | `Accept` | `application/json` | Recommended on every request. | ## Collection parameters Endpoints that return collections commonly support the following query parameters for paging and sorting. The exact parameters and filters available for a given endpoint are listed in the [API reference](https://documentation.cluedin.net/api.md). | Parameter | Type | Description | |---|---|---| | `page` | integer | Zero-based page index. Defaults to `0`. | | `take` | integer | Number of items to return per page. Defaults to `20`. | | `orderBy` | string | Name of the field to sort by. | | `orderAsc` | boolean | Sort direction. Defaults to `true` (ascending). | ## Status codes The API uses standard HTTP status codes. | Code | Meaning | |---|---| | `200 OK` | The request succeeded. | | `201 Created` | The resource was created successfully. | | `400 Bad Request` | The request was malformed or failed validation. | | `401 Unauthorized` | The token is missing, invalid, or expired. | | `403 Forbidden` | The token is valid but lacks the required permission. | | `404 Not Found` | The requested resource does not exist. | | `409 Conflict` | The request conflicts with the current state of the resource. | | `500 Internal Server Error` | An unexpected error occurred on the server. | ## Examples The examples below use `/api/v1` paths. Set the `CLUEDIN_API_TOKEN` environment variable to your token before running them. ### Check connectivity `GET /api/v1/status` reports whether the environment is reachable. ```bash curl "https://./api/v1/status" \ -H "Accept: application/json" ``` ### Authenticated GET request The following request retrieves vocabulary keys. ```bash curl "https://./api/v1/vocabs/keys" \ -H "Authorization: Bearer $CLUEDIN_API_TOKEN" \ -H "Accept: application/json" ``` The same request in PowerShell: ```powershell $headers = @{ Authorization = "Bearer $env:CLUEDIN_API_TOKEN" Accept = "application/json" } Invoke-RestMethod -Uri "https://./api/v1/vocabs/keys" -Headers $headers ``` ### Request with a JSON body `POST`, `PUT`, and `PATCH` requests send a JSON body and must include the `Content-Type` header. ```bash curl -X POST "https://./api/v1/" \ -H "Authorization: Bearer $CLUEDIN_API_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "name": "Example" }' ``` Refer to the [API reference](https://documentation.cluedin.net/api.md) for the exact request body schema of each endpoint. Up: [API reference](https://documentation.cluedin.net/api.md)