# Search Shared Thread Messages

Full-text search over the message bodies of the thread behind a share link — **including history the client has not paged in yet**. Matching is case-insensitive substring over message content, newest matches first, paginated with an opaque cursor.

This is the slug-scoped equivalent of [Search messages](/api-reference/threads/search-messages), which is ownership-scoped and returns `404` for a share-link recipient. Each hit carries the stable message id from [Get Shared Thread Messages](/api-reference/shared-threads/get-shared-thread-messages), so a client can jump to a hit with `around={message_id}` on that endpoint.

Authorization is the **same** as reading the thread's messages: the slug must resolve for you, at any access level. An unknown or unauthorized link returns `404` — never `403` — so a client can latch the capability off once instead of firing a denied request per keystroke.

## Authentication

Requires **user** authentication (Bearer token). An API key has no recipient identity and is rejected with `403`.

## Path Parameters

**`slug`** string required

The share-link slug, taken from the share URL.

## Query Parameters

**`q`** string required

Full-text query over message body text within this thread. 1 to 500 characters. A blank query returns `422`.

**`limit`** integer optional

Maximum results per page, between 1 and 50. Defaults to `20`.

**`cursor`** string optional

Opaque continuation cursor from a previous response's `next_cursor`. A malformed cursor returns `422`.

**`role`** string optional

Restrict results to messages with this role: `user`, `assistant`, `system`, or `tool`.

## Returns

- **object** `string` — always `list`.
- **data** `array` — matching messages, newest first. Each hit has:
  - **message_id** `string` — stable message id (`msg_…`), usable as the `around` anchor.
  - **role** `string` — `user`, `assistant`, `system`, or `tool`.
  - **snippet** `string` — short excerpt of the message body around the first match. Machine-facing skill directives appended by the composer are removed from the excerpt; they remain part of the stored message and are still matched by `q`.
  - **created_at** `string` — ISO-8601 UTC timestamp of the message.
- **has_more** `boolean` — whether more results exist.
- **next_cursor** `string | null` — cursor for the next page; `null` when exhausted.
- **coverage** `object` — honesty block stating what the search actually covered (`indexed`, plus a `note` when there is a caveat).


## Code Examples

### cURL


```bash
curl -X GET "https://api.aitronos.com/v1/shared-threads/abc123slug/messages/search?q=launch&limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Python SDK


```python
from aitronos import Aitronos  # pip install aitronos-sdk

client = Aitronos(api_key="", token="YOUR_TOKEN")

results = client.threads.shared.search_messages(slug="abc123slug", q="launch")
for hit in results.data:
    print(hit.message_id, hit.snippet)
```

### Python (requests)


```python
import requests

response = requests.get(
    "https://api.aitronos.com/v1/shared-threads/abc123slug/messages/search",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    params={"q": "launch", "limit": 20},
)
print(response.json()["data"])
```

### JavaScript


```javascript
const response = await fetch(
  "https://api.aitronos.com/v1/shared-threads/abc123slug/messages/search?q=launch",
  { headers: { Authorization: "Bearer YOUR_TOKEN" } },
);
const results = await response.json();
console.log(results.data);
```

## Response Examples

### Success (200)


```json
{
  "object": "list",
  "data": [
    {
      "message_id": "msg_7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d",
      "role": "user",
      "snippet": "…how should we sequence the launch?…",
      "created_at": "2026-08-01T12:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "coverage": { "indexed": true, "note": null }
}
```

### Error — blank query (422)


```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request could not be validated.",
    "system_message": "Search query must not be blank",
    "type": "client_error",
    "status": 422,
    "details": { "q": "  " },
    "trace_id": "...",
    "timestamp": "..."
  }
}
```

### Error — unknown / unauthorized link (404)


```json
{
  "success": false,
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "That share link could not be found.",
    "system_message": "Share link unresolved for user",
    "type": "client_error",
    "status": 404,
    "details": {},
    "trace_id": "...",
    "timestamp": "..."
  }
}
```

## Related Resources

- [Get Shared Thread Messages](/api-reference/shared-threads/get-shared-thread-messages) — Jump to a hit with `around={message_id}`
- [Get Shared Thread Turns](/api-reference/shared-threads/get-shared-thread-turns) — Every turn in the thread, for the turn rail
- [Shared Thread Sources](/api-reference/shared-threads/shared-thread-sources) — The files behind the conversation
- [Get Shared Thread](/api-reference/shared-threads/get-shared-thread) — Open the share link