{"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":"Shared Thread Compose State","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":"shared-thread-compose-state","__idx":0},"children":["Shared Thread Compose State"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Read and edit an email ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["compose card"]},"'s state — and manage its outgoing attachments — on a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["live-shared"]}," thread you ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["joined"]},". These are the slug-scoped twins of the owner compose-state endpoints, for a joiner co-working on someone else's thread."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A compose card is the interactive email-draft surface an assistant produces (tone options, editable body, subject, From-identity, recipients, attachments). A joiner co-working live can rehydrate the card after a reload, edit it, and manage attachments before it is sent."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every operation is authorized by the joiner's ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["live"]},"-share grant on the slug. 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"]}," (before any card lookup); an unknown or unauthorized link, or a missing card, returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]},". Edits are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["version-guarded"]}," (optimistic concurrency): pass the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["version"]}," you last saw; a stale version returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409"]}," unless the edit is already applied."]},{"$$mdtype":"Tag","name":"ApiContainer","attributes":{},"children":[{"$$mdtype":"Tag","name":"Endpoint","attributes":{"method":"GET","path":"https://api.aitronos.com/v1/shared-threads/{slug}/compose-state/{tool_call_id}"},"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)."]},{"$$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, from the share URL. The link must be a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["live"]}," link."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tool_call_id"]}]}," 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 compose card's tool-call id (the join key to the card)."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"returns","__idx":3},"children":["Returns"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The compose card's current edit/approval state: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tool_call_id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["selected_option_id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["edited_body"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subject_override"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["body_is_html"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["attachments"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["to"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cc"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bcc"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["from_identity_id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["draft"]}," | ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending_send"]}," | ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sent"]}," | ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failed"]}," | ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["denied"]}," | ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expired"]},"), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["version"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sent_message_id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["updated_at"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"other-operations","__idx":4},"children":["Other Operations"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"update-the-compose-card","__idx":5},"children":["Update the compose card"]},{"$$mdtype":"Tag","name":"Endpoint","attributes":{"method":"PATCH","path":"https://api.aitronos.com/v1/shared-threads/{slug}/compose-state/{tool_call_id}"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Persist the joiner's inline edits. Version-guarded — send ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["version"]}," (the value you last saw) plus only the changed fields (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["selected_option_id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["edited_option_id"]}," + ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["edited_body"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subject_override"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["body_is_html"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["from_identity_id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["to"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cc"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bcc"]},"). A terminal card (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sent"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["denied"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expired"]},") is immutable and returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409"]},". Returns the updated compose-state object."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"add-an-attachment","__idx":6},"children":["Add an attachment"]},{"$$mdtype":"Tag","name":"Endpoint","attributes":{"method":"POST","path":"https://api.aitronos.com/v1/shared-threads/{slug}/compose-state/{tool_call_id}/attachments"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Upload a file (multipart ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["file"]},") and attach it to the card. Pass the current ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["version"]}," as a query parameter. Limits: 10 attachments per email, 25 MB per file and per email total. Returns the added attachment, the card's full attachment list, and the new ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["version"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"remove-an-attachment","__idx":7},"children":["Remove an attachment"]},{"$$mdtype":"Tag","name":"Endpoint","attributes":{"method":"DELETE","path":"https://api.aitronos.com/v1/shared-threads/{slug}/compose-state/{tool_call_id}/attachments/{file_id}"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Remove one pending attachment by its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["file_id"]},". Pass the current ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["version"]}," as a query parameter. Returns the card's full attachment list and the new ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["version"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"code-examples","__idx":8},"children":["Code Examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"curl","__idx":9},"children":["cURL"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Read\ncurl \"https://api.aitronos.com/v1/shared-threads/abc123slug/compose-state/tc_1\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n\n# Patch (select a tone option)\ncurl -X PATCH \"https://api.aitronos.com/v1/shared-threads/abc123slug/compose-state/tc_1\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"version\": 3, \"selected_option_id\": \"opt_friendly\"}'\n\n# Attach a file\ncurl -X POST \"https://api.aitronos.com/v1/shared-threads/abc123slug/compose-state/tc_1/attachments?version=4\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -F \"file=@report.pdf\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"python-sdk","__idx":10},"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\")\ncard = client.threads.shared.compose_state.get(slug=\"abc123slug\", tool_call_id=\"tc_1\")\ncard = client.threads.shared.compose_state.patch(\n    slug=\"abc123slug\",\n    tool_call_id=\"tc_1\",\n    version=card.version,\n    selected_option_id=\"opt_friendly\",\n)\nprint(card.status, card.version)\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"python-requests","__idx":11},"children":["Python (requests)"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"import requests\n\nresponse = requests.patch(\n    \"https://api.aitronos.com/v1/shared-threads/abc123slug/compose-state/tc_1\",\n    headers={\"Authorization\": \"Bearer YOUR_TOKEN\"},\n    json={\"version\": 3, \"selected_option_id\": \"opt_friendly\"},\n)\nprint(response.json()[\"version\"])\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"javascript","__idx":12},"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/compose-state/tc_1\",\n  {\n    method: \"PATCH\",\n    headers: {\n      Authorization: \"Bearer YOUR_TOKEN\",\n      \"Content-Type\": \"application/json\",\n    },\n    body: JSON.stringify({ version: 3, selected_option_id: \"opt_friendly\" }),\n  },\n);\nconst card = await response.json();\nconsole.log(card.status, card.version);\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"response-examples","__idx":13},"children":["Response Examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"success-200","__idx":14},"children":["Success (200)"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"tool_call_id\": \"tc_1\",\n  \"selected_option_id\": \"opt_friendly\",\n  \"edited_body\": { \"opt_friendly\": null },\n  \"subject_override\": null,\n  \"body_is_html\": null,\n  \"attachments\": [],\n  \"to\": null,\n  \"cc\": null,\n  \"bcc\": null,\n  \"from_identity_id\": null,\n  \"status\": \"draft\",\n  \"version\": 4,\n  \"sent_message_id\": null,\n  \"error\": null,\n  \"updated_at\": \"2026-07-06T11:26:38Z\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"error--stale-version-409","__idx":15},"children":["Error — Stale version (409)"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"VERSION_CONFLICT\",\n    \"message\": \"There was a conflict with the current state of the resource.\",\n    \"system_message\": \"compose-state version is stale; refetch and retry\",\n    \"type\": \"client_error\",\n    \"status\": 409,\n    \"details\": { \"tool_call_id\": \"tc_1\", \"expected_version\": 3, \"current_version\": 4 },\n    \"trace_id\": \"...\",\n    \"timestamp\": \"...\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"error--not-a-live-link-403","__idx":16},"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\": { \"link_id\": \"tslnk_...\", \"access_level\": \"view\" },\n    \"trace_id\": \"...\",\n    \"timestamp\": \"...\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-resources","__idx":17},"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/join-shared-thread"},"children":["Join Shared Thread"]}," — Join the live-shared thread first"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/shared-threads/shared-thread-tool-approval"},"children":["Shared Thread Tool Approval"]}," — Approve/deny the compose card's Send"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/shared-threads/shared-thread-reactions"},"children":["Shared Thread Reactions"]}," — React to messages as a joiner"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/shared-threads/live-shared-thread"},"children":["Live Shared Thread"]}," — The real-time co-working stream"]}]}]}]},"headings":[{"value":"Shared Thread Compose State","id":"shared-thread-compose-state","depth":1},{"value":"Authentication","id":"authentication","depth":2},{"value":"Path Parameters","id":"path-parameters","depth":2},{"value":"Returns","id":"returns","depth":2},{"value":"Other Operations","id":"other-operations","depth":2},{"value":"Update the compose card","id":"update-the-compose-card","depth":3},{"value":"Add an attachment","id":"add-an-attachment","depth":3},{"value":"Remove an attachment","id":"remove-an-attachment","depth":3},{"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 — Stale version (409)","id":"error--stale-version-409","depth":3},{"value":"Error — Not a live link (403)","id":"error--not-a-live-link-403","depth":3},{"value":"Related Resources","id":"related-resources","depth":2}],"frontmatter":{"title":"Shared Thread Compose State","seo":{"title":"Shared Thread Compose State"}},"lastModified":"2026-10-26T18:32:31.653Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/api-reference/shared-threads/shared-thread-compose-state","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}