{"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":"Join Shared Thread","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":"join-shared-thread","__idx":0},"children":["Join Shared Thread"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Records that the caller has ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["joined"]}," the live-shared conversation behind a share link, so it becomes a first-class, ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["persistent entry in their thread list"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/threads"]},") that they can return to across reloads and keep co-working in — without owning it."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Unlike ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/shared-threads/import-shared-thread"},"children":["Import Shared Thread"]},", which makes a separate copy, joining keeps the caller on the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["same underlying thread"]}," so everyone co-works together in real time."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The operation is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["idempotent"]},": re-joining returns the same join (no duplicate). It is allowed ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["only when the link's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["access_level"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["live"]}]}," — a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["view"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fork"]}," slug returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]},". The caller must also pass the same resolution gates as opening the link (active member of the thread's organization; explicit grant for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["explicit"]}," links; not revoked or expired); an unknown or unauthorized link returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A joined thread ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["auto-drops"]}," from the caller's list once the underlying live link is revoked or expired — no explicit cleanup is needed."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["owner"]}," of the shared thread is an exception: joining their own link returns the thread as normal, but records nothing. The thread is already theirs, so it stays an owned entry in their list and is never reported as joined."]},{"$$mdtype":"Tag","name":"ApiContainer","attributes":{},"children":[{"$$mdtype":"Tag","name":"Endpoint","attributes":{"method":"POST","path":"https://api.aitronos.com/v1/shared-threads/{slug}/join"},"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). API-key authentication 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. The link must be a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["live"]}," link."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"body-parameters","__idx":3},"children":["Body Parameters"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["None. The request takes no body."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"returns","__idx":4},"children":["Returns"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Returns the underlying thread as a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ThreadResponse"]}," object (read-only metadata) with two fields set for the joiner:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["is_joined"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["boolean"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," (the caller joined this thread via a live link; they do not own it)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["joined_via_slug"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}," — the slug to use for this thread's slug-scoped loads: ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/shared-threads/get-shared-thread-messages"},"children":["Get Shared Thread Messages"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/shared-threads/live-shared-thread"},"children":["Live Shared Thread"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The same row appears in subsequent ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/threads"]}," responses with these fields set, so the client routes its message and live loads through the slug-scoped recipient endpoints."]},{"$$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 POST https://api.aitronos.com/v1/shared-threads/abc123slug/join \\\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\n\nclient = Aitronos(api_key=\"\", token=\"YOUR_TOKEN\")\nthread = client.threads.shared.join(slug=\"abc123slug\")\nprint(thread.is_joined, thread.joined_via_slug)\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.post(\n    \"https://api.aitronos.com/v1/shared-threads/abc123slug/join\",\n    headers={\"Authorization\": \"Bearer YOUR_TOKEN\"},\n)\nprint(response.json()[\"joined_via_slug\"])\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/join\",\n  {\n    method: \"POST\",\n    headers: { Authorization: \"Bearer YOUR_TOKEN\" },\n  },\n);\nconst thread = await response.json();\nconsole.log(thread.is_joined, thread.joined_via_slug);\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-201","__idx":11},"children":["Success (201)"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"thread_9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a\",\n  \"object\": \"thread\",\n  \"title\": \"Q3 launch plan\",\n  \"status\": \"inactive\",\n  \"organization_id\": \"org_9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d\",\n  \"message_count\": 12,\n  \"is_shared\": true,\n  \"share_count\": 1,\n  \"live_share_count\": 1,\n  \"is_joined\": true,\n  \"joined_via_slug\": \"abc123slug\",\n  \"created_at\": \"2026-06-28T09:40:00Z\",\n  \"updated_at\": \"2026-06-28T09:40:00Z\",\n  \"last_message_at\": \"2026-06-28T09:39:00Z\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"error--not-a-live-link-403","__idx":12},"children":["Error — Not a live link (403)"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INSUFFICIENT_PERMISSIONS\",\n    \"message\": \"You do not have permission to perform this action.\",\n    \"system_message\": \"This share link does not grant live co-working access\",\n    \"type\": \"authorization_error\",\n    \"status\": 403,\n    \"details\": {\n      \"link_id\": \"tslnk_2b1c3d4e5f6a7b8c9d0e1f2a3b4c5d6e\",\n      \"access_level\": \"view\"\n    },\n    \"trace_id\": \"...\",\n    \"timestamp\": \"...\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"error--link-not-found-or-not-authorized-404","__idx":13},"children":["Error — Link not found or not authorized (404)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A caller the link was given to is told why instead: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["details.unavailable_reason"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["thread_deleted"]}," (404), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["share_revoked"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["share_expired"]}," (422), or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["org_access_lost"]}," (404), with the owner and sharer. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/shared-threads/get-shared-thread#when-a-link-stops-working"},"children":["When a link stops working"]},". Everyone else gets this uniform body."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"RESOURCE_NOT_FOUND\",\n    \"message\": \"The requested resource could not be found.\",\n    \"system_message\": \"Share link not found\",\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/leave-shared-thread"},"children":["Leave Shared Thread"]}," — Remove the persistent joined entry"]},{"$$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"]},{"$$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"]}," — Read the joined thread's messages (slug-scoped)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/shared-threads/live-shared-thread"},"children":["Live Shared Thread"]}," — Join the real-time co-working stream"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/shared-threads/send-shared-thread"},"children":["Send to Shared Thread"]}," — Post a message to the live-shared thread"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/shared-threads/shared-thread-presence"},"children":["Shared Thread Presence"]}," — Heartbeat presence as a joiner"]}]}]}]},"headings":[{"value":"Join Shared Thread","id":"join-shared-thread","depth":1},{"value":"Authentication","id":"authentication","depth":2},{"value":"Path Parameters","id":"path-parameters","depth":2},{"value":"Body Parameters","id":"body-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 (201)","id":"success-201","depth":3},{"value":"Error — Not a live link (403)","id":"error--not-a-live-link-403","depth":3},{"value":"Error — Link not found or not authorized (404)","id":"error--link-not-found-or-not-authorized-404","depth":3},{"value":"Related Resources","id":"related-resources","depth":2}],"frontmatter":{"title":"Join Shared Thread","seo":{"title":"Join Shared Thread"}},"lastModified":"2026-10-26T18:32:31.653Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/api-reference/shared-threads/join-shared-thread","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}