Skip to content
/
Search shared thread mess...
Last updated

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, which is ownership-scoped and returns 404 for a share-link recipient. Each hit carries the stable message id from 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.

GEThttps://api.aitronos.com/v1/shared-threads/{slug}/messages/search

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

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

Python SDK

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)

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

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)

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

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

{
  "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": "..."
  }
}
Previous page
Next page