{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/api-reference/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["api-container","endpoint"]},"redocly_category":"API Reference","searchWeight":120,"type":"markdown"},"seo":{"title":"Search Shared Thread Messages","description":"Complete API reference and documentation for Freddy AI-powered backend system by Aitronos","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"search-shared-thread-messages","__idx":0},"children":["Search Shared Thread Messages"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Full-text search over the message bodies of the thread behind a share link — ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is the slug-scoped equivalent of ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/threads/search-messages"},"children":["Search messages"]},", which is ownership-scoped and returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}," for a share-link recipient. Each hit carries the stable message id from ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/shared-threads/get-shared-thread-messages"},"children":["Get Shared Thread Messages"]},", so a client can jump to a hit with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["around={message_id}"]}," on that endpoint."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Authorization is the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["same"]}," as reading the thread's messages: the slug must resolve for you, at any access level. An unknown or unauthorized link returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}," — never ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}," — so a client can latch the capability off once instead of firing a denied request per keystroke."]},{"$$mdtype":"Tag","name":"ApiContainer","attributes":{},"children":[{"$$mdtype":"Tag","name":"Endpoint","attributes":{"method":"GET","path":"https://api.aitronos.com/v1/shared-threads/{slug}/messages/search"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"authentication","__idx":1},"children":["Authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Requires ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["user"]}," authentication (Bearer token). An API key has no recipient identity and is rejected with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"path-parameters","__idx":2},"children":["Path Parameters"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["slug"]}]}," string ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#ef4444 !important","fontWeight":"600 !important","fontStyle":"normal !important"}},"children":["required"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The share-link slug, taken from the share URL."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"query-parameters","__idx":3},"children":["Query Parameters"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["q"]}]}," string ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#ef4444 !important","fontWeight":"600 !important","fontStyle":"normal !important"}},"children":["required"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Full-text query over message body text within this thread. 1 to 500 characters. A blank query returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["limit"]}]}," integer ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#9ca3af !important","fontWeight":"500 !important","fontStyle":"normal !important"}},"children":["optional"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Maximum results per page, between 1 and 50. Defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["20"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cursor"]}]}," string ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#9ca3af !important","fontWeight":"500 !important","fontStyle":"normal !important"}},"children":["optional"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Opaque continuation cursor from a previous response's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["next_cursor"]},". A malformed cursor returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["role"]}]}," string ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#9ca3af !important","fontWeight":"500 !important","fontStyle":"normal !important"}},"children":["optional"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Restrict results to messages with this role: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["assistant"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["system"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tool"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"returns","__idx":4},"children":["Returns"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["object"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}," — always ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["list"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["data"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["array"]}," — matching messages, newest first. Each hit has:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["message_id"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}," — stable message id (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["msg_…"]},"), usable as the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["around"]}," anchor."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["role"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["assistant"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["system"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tool"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["snippet"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["q"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["created_at"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}," — ISO-8601 UTC timestamp of the message."]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["has_more"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["boolean"]}," — whether more results exist."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["next_cursor"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string | null"]}," — cursor for the next page; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," when exhausted."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["coverage"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["object"]}," — honesty block stating what the search actually covered (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["indexed"]},", plus a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["note"]}," when there is a caveat)."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"code-examples","__idx":5},"children":["Code Examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"curl","__idx":6},"children":["cURL"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://api.aitronos.com/v1/shared-threads/abc123slug/messages/search?q=launch&limit=20\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"python-sdk","__idx":7},"children":["Python SDK"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"from aitronos import Aitronos  # pip install aitronos-sdk\n\nclient = Aitronos(api_key=\"\", token=\"YOUR_TOKEN\")\n\nresults = client.threads.shared.search_messages(slug=\"abc123slug\", q=\"launch\")\nfor hit in results.data:\n    print(hit.message_id, hit.snippet)\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"python-requests","__idx":8},"children":["Python (requests)"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"import requests\n\nresponse = requests.get(\n    \"https://api.aitronos.com/v1/shared-threads/abc123slug/messages/search\",\n    headers={\"Authorization\": \"Bearer YOUR_TOKEN\"},\n    params={\"q\": \"launch\", \"limit\": 20},\n)\nprint(response.json()[\"data\"])\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"javascript","__idx":9},"children":["JavaScript"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const response = await fetch(\n  \"https://api.aitronos.com/v1/shared-threads/abc123slug/messages/search?q=launch\",\n  { headers: { Authorization: \"Bearer YOUR_TOKEN\" } },\n);\nconst results = await response.json();\nconsole.log(results.data);\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"response-examples","__idx":10},"children":["Response Examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"success-200","__idx":11},"children":["Success (200)"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"object\": \"list\",\n  \"data\": [\n    {\n      \"message_id\": \"msg_7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d\",\n      \"role\": \"user\",\n      \"snippet\": \"…how should we sequence the launch?…\",\n      \"created_at\": \"2026-08-01T12:00:00Z\"\n    }\n  ],\n  \"has_more\": false,\n  \"next_cursor\": null,\n  \"coverage\": { \"indexed\": true, \"note\": null }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"error--blank-query-422","__idx":12},"children":["Error — blank query (422)"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"VALIDATION_ERROR\",\n    \"message\": \"The request could not be validated.\",\n    \"system_message\": \"Search query must not be blank\",\n    \"type\": \"client_error\",\n    \"status\": 422,\n    \"details\": { \"q\": \"  \" },\n    \"trace_id\": \"...\",\n    \"timestamp\": \"...\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"error--unknown--unauthorized-link-404","__idx":13},"children":["Error — unknown / unauthorized link (404)"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"RESOURCE_NOT_FOUND\",\n    \"message\": \"That share link could not be found.\",\n    \"system_message\": \"Share link unresolved for user\",\n    \"type\": \"client_error\",\n    \"status\": 404,\n    \"details\": {},\n    \"trace_id\": \"...\",\n    \"timestamp\": \"...\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-resources","__idx":14},"children":["Related Resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/shared-threads/get-shared-thread-messages"},"children":["Get Shared Thread Messages"]}," — Jump to a hit with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["around={message_id}"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/shared-threads/get-shared-thread-turns"},"children":["Get Shared Thread Turns"]}," — Every turn in the thread, for the turn rail"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/shared-threads/shared-thread-sources"},"children":["Shared Thread Sources"]}," — The files behind the conversation"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/shared-threads/get-shared-thread"},"children":["Get Shared Thread"]}," — Open the share link"]}]}]}]},"headings":[{"value":"Search Shared Thread Messages","id":"search-shared-thread-messages","depth":1},{"value":"Authentication","id":"authentication","depth":2},{"value":"Path Parameters","id":"path-parameters","depth":2},{"value":"Query Parameters","id":"query-parameters","depth":2},{"value":"Returns","id":"returns","depth":2},{"value":"Code Examples","id":"code-examples","depth":2},{"value":"cURL","id":"curl","depth":3},{"value":"Python SDK","id":"python-sdk","depth":3},{"value":"Python (requests)","id":"python-requests","depth":3},{"value":"JavaScript","id":"javascript","depth":3},{"value":"Response Examples","id":"response-examples","depth":2},{"value":"Success (200)","id":"success-200","depth":3},{"value":"Error — blank query (422)","id":"error--blank-query-422","depth":3},{"value":"Error — unknown / unauthorized link (404)","id":"error--unknown--unauthorized-link-404","depth":3},{"value":"Related Resources","id":"related-resources","depth":2}],"frontmatter":{"title":"Search Shared Thread Messages","seo":{"title":"Search Shared Thread Messages"}},"lastModified":"2026-10-26T18:32:31.653Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/api-reference/shared-threads/search-shared-thread-messages","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}