> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chamelio.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Global Search
> Find workflows, tasks, contracts, archived contracts, or vault files by name with a free-text query.
## Endpoint
```
POST /v2/search/global
```
Search one resource family at a time by free text. Use it when you know an item's name but not its
ID.
## Authentication
This endpoint requires an OAuth access token. Send it as a bearer token:
```bash theme={null}
Authorization: Bearer your_access_token
```
**Required scopes:** the token needs the scopes that read the category you search:
| `category` | Required scopes |
| ------------- | --------------------------------------------------------------------------------------------- |
| `workflows` | `workflows:read` **and** `tasks:read` (results include tasks as well as workflow definitions) |
| `sor` | `sor:read` |
| `sor_archive` | `sor:read` |
| `vault` | `files:read` |
A token with none of `files:read`, `sor:read`, `tasks:read`, or `workflows:read` is rejected before
the category is checked.
Results are limited to what the access token's user may see. Two users authorizing the same
application can get different results for the same query.
## Request Body
| Field | Type | Required | Description |
| ---------- | -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `category` | string | Yes | Which resource family to search. `workflows` covers workflow definitions and their tasks, `sor` covers contracts in the system of record, `sor_archive` covers archived contracts, and `vault` covers files and folders |
| `query` | string or null | No | Free text to match. Omit it to get the most recent items in the category instead |
## Request Example
```bash cURL theme={null}
curl -X POST "https://platform.chamelio.ai/v2/search/global" \
-H "Authorization: Bearer your_access_token" \
-H "Content-Type: application/json" \
-d '{
"category": "sor",
"query": "Acme"
}'
```
```python Python theme={null}
import requests
url = "https://platform.chamelio.ai/v2/search/global"
headers = {
"Authorization": "Bearer your_access_token",
"Content-Type": "application/json"
}
payload = {
"category": "sor",
"query": "Acme"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
```
```javascript JavaScript theme={null}
const response = await fetch('https://platform.chamelio.ai/v2/search/global', {
method: 'POST',
headers: {
'Authorization': 'Bearer your_access_token',
'Content-Type': 'application/json'
},
body: JSON.stringify({
category: 'sor',
query: 'Acme'
})
});
const data = await response.json();
console.log(data);
```
## Response
### Success Response
**Status Code:** `200 OK`
```json theme={null}
{
"items": [
{
"item_type": "sor_contract",
"item_id": "90210",
"title": "Acme Master Services Agreement",
"subtitle": "Master Services Agreement",
"created_at": "2026-05-14T09:30:00Z",
"updated_at": "2026-08-02T16:12:44Z",
"resource_url": "https://app.chamelio.ai/..."
}
],
"total": 1,
"category": "sor"
}
```
### Response Fields
| Field | Type | Description |
| ---------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
| `items` | array | Up to 50 matches, most relevant and most recent first. Each entry is a [Search Result Object](#search-result-object) |
| `total` | integer | How many matches the category holds in total |
| `category` | string | The category that was searched, echoed from the request |
### Search Result Object
| Field | Type | Description |
| -------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `item_type` | string | What kind of item this is. Known values: `vault_file`, `vault_folder`, `flow_task_active`, `flow_task_inactive`, `flow_definition`, `sor_contract`, `sor_archived_contract` |
| `item_id` | string | Identifier within the item's own resource family, as a string |
| `title` | string | Display title of the item |
| `subtitle` | string or null | Secondary display text, when available |
| `created_at` | string | Timestamp the item was created |
| `updated_at` | string | Timestamp the item was last updated |
| `resource_url` | string | Where the item lives in the Chamelio web app |
Use `item_id` with the matching detail endpoint. A `flow_task_active` or `flow_task_inactive` ID is a
task ID for [Get Task](/api-reference/endpoint/v2/tasks/get), and a `sor_contract` ID is a document
ID for [Get Contract Data](/api-reference/endpoint/v2/core/get-contract-data). IDs arrive as strings,
so convert them to integers where the detail endpoint expects one.
## Error Responses
### 400 Bad Request
Returned when the access token has no user behind it.
`client_credentials` tokens act as the admin who created the application, so this applies only to
tokens issued before application creators were recorded.
```json theme={null}
{
"detail": "client_credentials tokens are not associated with a user"
}
```
### 401 Unauthorized
Returned when the access token is missing, unknown, revoked, or expired, or when an `X-API-Key` was
sent instead of a bearer token. See [OAuth error responses](/api-reference/oauth-apps#error-responses).
```json theme={null}
{
"detail": "Invalid access token"
}
```
### 403 Forbidden
Returned when the token carries none of the searchable scopes:
```json theme={null}
{
"detail": "Insufficient scope; this endpoint requires at least one of: files:read sor:read tasks:read workflows:read"
}
```
Or when it lacks a scope the requested category needs. Only the missing scopes are listed:
```json theme={null}
{
"detail": "Insufficient scope; searching 'workflows' requires: tasks:read"
}
```
### 422 Validation Error
Returned when `category` is missing or is not one of `workflows`, `sor`, `sor_archive`, or `vault`.
### 429 Too Many Requests
Returned when your organization exceeds its per-minute request limit.
```json theme={null}
{
"detail": "Rate limit exceeded"
}
```
### 500 Internal Server Error
Returned when the search could not be completed due to a server error.
```json theme={null}
{
"detail": "Failed to search"
}
```
## Notes
Global search has no pagination or filters and returns at most 50 items. To page through documents
or filter on field values, use [Search Documents](/api-reference/endpoint/v2/core/search) instead.
Global search is available only with OAuth access tokens. There is no API-key equivalent.