Global Search

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:

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

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"
  }'

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())

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

{
  "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
`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, and a sor_contract ID is a document ID for 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.

{
  "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.

{
  "detail": "Invalid access token"
}

403 Forbidden

Returned when the token carries none of the searchable scopes:

{
  "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:

{
  "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.

{
  "detail": "Rate limit exceeded"
}

500 Internal Server Error

Returned when the search could not be completed due to a server error.

{
  "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 instead.

Global search is available only with OAuth access tokens. There is no API-key equivalent.

Overview

API Key Access

OAuth App Access

MCP (beta)

Webhooks

Endpoint

Authentication

Request Body

Request Example

Response

Success Response

Response Fields

Search Result Object

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

422 Validation Error

429 Too Many Requests

500 Internal Server Error

Notes

​Endpoint

​Authentication

​Request Body

​Request Example

​Response

​Success Response

​Response Fields

​Search Result Object

​Error Responses

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​422 Validation Error

​429 Too Many Requests

​500 Internal Server Error

​Notes

Endpoint

Authentication

Request Body

Request Example

Response

Success Response

Response Fields

Search Result Object

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

422 Validation Error

429 Too Many Requests

500 Internal Server Error

Notes