---
title: "Run Conversational Search"
method: POST
path: "/search/conversational"
tags: ["Search"]
---

# Run Conversational Search

`POST /search/conversational`

## Request

- Base URL: `https://ironcladapp.com/public/api/v1`
- URL: `https://ironcladapp.com/public/api/v1/search/conversational`
- Auth: API key in header `Authorization` and OAuth 2
  - Authorization code: `https://ironcladapp.com/oauth/authorize`
  - Client credentials
  - Token URL: `https://ironcladapp.com/oauth/token` scopes: `public.search.conversational`, `public.records.readRecords`, `public.workflows.readWorkflows`

Ask a natural language question and get an AI-generated response grounded in your contracts and records.

**OAuth Scopes required:** `public.search.conversational`, `public.records.readRecords`, `public.workflows.readWorkflows`

**Prerequisites:** Conversational Search must be enabled for your company. If you receive a `403` error, please ask your company administrator to enable the Conversational Search feature in your company settings.

## Request body

- object
  - `query` string, required: The natural language question to ask
  - `modelTier` 'ultrafast' | 'fast' | 'standard' | 'powerful': Controls the model used. Defaults to 'fast'. Use 'ultrafast' for the lightest/quickest model, 'standard' or 'powerful' for more capable models on complex queries.
  - `userTimezone` string: The user's IANA timezone (e.g. "America/New_York", "Asia/Kolkata"). Used to correctly interpret relative time expressions like "last month" or "this week". If not provided, falls back to the timezone in the user's company profile, then UTC.

## Response `200`

200

- object
  - `result` string, required: The agent's prose response
  - `records` object, required: Map of record ID to record details for all records surfaced by the agent
  - `pagination` object: Present only when the search persisted a result set. When totalCount exceeds the number of records returned here, page the full set with GET /search/result-sets/{resultSetId}, following hasMore and nextPage until hasMore is false.
    - `resultSetId` string: Handle for the persisted result set.
    - `totalCount` integer: Total records the persisted set was saved with.

## Other responses

- `400`: 400
- `401`: 401
- `403`: 403

## Changes

- **2026-11-03** `435da5a4396e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ironcladapp/apis/ironclad-public-api/changes/search/conversational/post.md)

---

[API](https://skmtc.dev/ironcladapp/apis/ironclad-public-api.md) - [All operations](https://skmtc.dev/ironcladapp/apis/ironclad-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ironcladapp/apis/ironclad-public-api/revisions/435da5a4396e?raw)