> For the complete documentation index, see [llms.txt](https://docs.contextual.io/documentation-and-resources/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/ai-search-api.md).

# AI Search API

Create and manage AI Search Profiles and check their indexing from code.

The AI Search API manages the Search Profiles that power [AI Search](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search.md) in your tenant. A Search Profile selects records of one Object Type and defines how they become searchable. Use this API from scripts and backend services that manage profiles as configuration. For example, a deployment script can create or update a profile in each tenant, then check its indexing status. In the Admin Console, you manage profiles under **Connect > AI Search**. The CLI's `ctxl aisearch profiles` commands also use this API to manage profiles and to check, repair, or rebuild their indexes. The `ctxl aisearch query` command sends its search to the Native Object API, which then calls the AI Search API.

## What you can do

* List Search Profiles and read a profile's configuration.
* Create, change, and delete Search Profiles.
* Check a profile's index status, build and repair progress, and stored projection columns.
* Request a repair or rebuild of a profile's index, and stop a repair that is still queuing records.

The reference also lists `POST /query`. To search indexed records from a solution, use the [Native Object API search endpoints](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/query-and-use-results.md#query-through-the-native-object-api). They check that each matching record still exists and can return current records.

Platform services use the operations listed under **Internal**, **Membership**, and **Organizations** in the reference. Do not call them from your solution.

## Base URL and reference

* **API base URL:** `https://ai-search.<tenant-id>.my.contextual.io/api/v1`
* **Swagger reference:** [AI Search API reference](https://ai-search.prod-001.prod.contextual.io/api-docs/)
* **Raw OpenAPI:** [openapi.json](https://ai-search.prod-001.prod.contextual.io/api-docs/openapi.json)

Replace `<tenant-id>` with the [tenant ID from your Tenant Workspace URL](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/authentication-and-permissions.md#identify-the-tenant). Profile and query requests also require the header `x-org-id: <tenant-id>`, including on the tenant hostname. Without it, they return `400` with the code `organization_required`.

The OpenAPI document uses the relative server `/api/v1`. When you import it into an API client or AI tool, set the server to the API base URL and add the `x-org-id` header.

## Authentication and permissions

Send an access token from a tenant API Key in the `Authorization: Bearer <access-token>` header. See [Get an access token](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/authentication-and-permissions.md#get-and-use-an-access-token).

Set the key's permissions on its [Permissions tab](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/authentication-and-permissions.md#assign-permissions).

| Task                                                                     | Required permission                                                                                                                   |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| List profiles, or read a profile, its index status, progress, or columns | **Service components → AI Search Profiles → Read**, or **Object data & action execution → Read** for the profile's source Object Type |
| Create a profile                                                         | **Service components → AI Search Profiles → Create**                                                                                  |
| Change a profile, request a repair or rebuild, or stop a repair          | **Service components → AI Search Profiles → Update**                                                                                  |
| Delete a profile                                                         | **Service components → AI Search Profiles → Delete**                                                                                  |

To create or change a profile, the key also needs read access to the source Object Type definition: **Service components → Object Types → Read**, or **Object data & action execution → Read** for that Object Type. The API reads the definition with your token.

If a key reads profiles only through Object data & action execution permissions, list results include only profiles whose source Object Type the key can read.

## Request and response details

* Request and response bodies are JSON. Each profile includes `_metaData` with its `id` and `hash`.
* List responses return profiles in `items`. To get the next page, send the returned `nextPageToken` as `pageToken`. Continue until a response has no `nextPageToken`, even if `items` is empty. Optional query parameters are `pageSize`, `includeTotal=true` for `totalCount` on the first page, and `includeIndexStatus=true` for each profile's `indexStatus` (`indexing`, `ready`, or `not-indexed`).
* `PUT /profiles/{profileId}` replaces the whole profile, and the profile's `id` must match the path. You cannot change a profile's source Object Type; the API returns `422`. To avoid overwriting someone else's change, set the optional `x-if-hash-match` header to the `_metaData.hash` you last read. If the profile has changed since then, the API returns `412`. Read it again before you retry.
* A profile update can start background indexing. The optional `rebuildMode` query parameter controls whether it rebuilds the index, so choose it deliberately. See [Change an Existing Profile](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/manage-search-profiles.md#change-an-existing-profile).
* In the reference, a repair is `POST /profiles/{profileId}/reconcile` and a rebuild is `POST /profiles/{profileId}/migrate`. Both run in the background. Check them with `GET /profiles/{profileId}/progress` and `GET /profiles/{profileId}/index-state`. See [Keep Search Up to Date](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/keep-search-up-to-date.md) for what each operation does.
* A new rebuild request restarts a rebuild that is still running. Check progress before you request another rebuild, for example after a timeout.
* When you form a request, replace `[\$]` in a reference path with a literal `$`. For example, `/[\$]page/profiles` becomes `/$page/profiles`. In a shell command, put a URL that contains `$page` in single quotes, or write `\$page`, so that the shell doesn't replace `$page` with a variable's value.

## Example request

This request lists up to 10 Search Profiles:

```bash
curl "https://ai-search.<tenant-id>.my.contextual.io/api/v1/profiles?pageSize=10" \
  --header "Authorization: Bearer <access-token>" \
  --header "x-org-id: <tenant-id>"
```

Replace `<access-token>` with your access token. A successful response has status `200` and up to 10 profiles in `items`.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/ai-search-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
