{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/api-reference/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["api-container","api-content","endpoint","api-examples","tabs","tab","code-group"]},"redocly_category":"API Reference","searchWeight":120,"type":"markdown"},"seo":{"title":"Resolve a chat artifact ref by entity","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":"resolve-a-chat-artifact-ref-by-entity","__idx":0},"children":["Resolve a chat artifact ref by entity"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Resolve the chat artifact ref for an underlying artifact entity (document, presentation, spreadsheet, dashboard). Clients use this to mount the side pane for an artifact opened from a chip or deep-link, after verifying the caller can read the underlying entity."]},{"$$mdtype":"Tag","name":"ApiContainer","attributes":{},"children":[{"$$mdtype":"Tag","name":"ApiContent","attributes":{},"children":[{"$$mdtype":"Tag","name":"Endpoint","attributes":{"method":"GET","path":"https://api.aitronos.com/v1/chat-artifacts/refs/by-entity/{smoc_entity_id}"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Looks up the chat artifact ref by the underlying entity ID. When no ref row exists yet — for example, the artifact was created outside the chat-artifacts flow or fetched directly by the agent — a transient ref descriptor is returned whose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ref_id"]}," carries a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transient_"]}," marker."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"path-parameters","__idx":1},"children":["Path parameters"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["smoc_entity_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":["Identifier of the underlying artifact entity (the item ID). The ref's type is resolved from the entity."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"returns","__idx":2},"children":["Returns"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ChatArtifactRefByEntityResponse"]}," object with a single ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ref"]}," field:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ref_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The chat artifact ref ID. Carries a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transient_"]}," marker when no persisted ref exists yet."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["smoc_entity_type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Entity type (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["document"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["presentation"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["spreadsheet"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dashboard"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["smoc_entity_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The underlying entity ID (echoed)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["title"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Current title of the entity."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created_at"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ISO-8601 creation timestamp."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["thread_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string | null"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Thread the ref was first created in, if any."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string | null"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Message the ref was first created in, if any."]}]}]}]}]}]},{"$$mdtype":"Tag","name":"ApiExamples","attributes":{},"children":[{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"label":"Request","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeGroup","attributes":{"mode":"dropdown"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","data-title":"cURL","header":{"title":"cURL","controls":{"copy":{}}},"source":"curl -X GET \"https://api.aitronos.com/v1/chat-artifacts/refs/by-entity/itm_revenue_plan\" \\\n  -H \"X-API-Key: $FREDDY_API_KEY\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","data-title":"Python SDK","header":{"title":"Python SDK","controls":{"copy":{}}},"source":"from aitronos import Aitronos\n\nclient = Aitronos(api_key=\"your-api-key\")\nresult = client.chat_artifacts.refs.resolve_by_entity(\n    smoc_entity_id=\"itm_revenue_plan\",\n)\nprint(result.ref.ref_id, result.ref.title)\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","data-title":"Python","header":{"title":"Python","controls":{"copy":{}}},"source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.aitronos.com/v1/chat-artifacts/refs/by-entity/itm_revenue_plan\",\n    headers={\"X-API-Key\": os.environ[\"FREDDY_API_KEY\"]},\n)\nprint(response.json())\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","data-title":"JavaScript","header":{"title":"JavaScript","controls":{"copy":{}}},"source":"const response = await fetch(\n  \"https://api.aitronos.com/v1/chat-artifacts/refs/by-entity/itm_revenue_plan\",\n  { headers: { \"X-API-Key\": process.env.FREDDY_API_KEY } },\n);\nconsole.log(await response.json());\n","lang":"javascript"},"children":[]}]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"Response","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"200 OK","header":{"title":"200 OK","controls":{"copy":{}}},"source":"{\n  \"ref\": {\n    \"ref_id\": \"carfref_aaaa1111bbbb2222cccc3333dddd4444\",\n    \"smoc_entity_type\": \"document\",\n    \"smoc_entity_id\": \"itm_revenue_plan\",\n    \"title\": \"Q1 Revenue Plan\",\n    \"created_at\": \"2026-04-19T14:00:00Z\",\n    \"thread_id\": \"thread_qwerty\",\n    \"message_id\": \"msg_abcd1234\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"404 Not Found","header":{"title":"404 Not Found","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\": \"Chat artifacts feature is disabled for this caller\",\n    \"type\": \"client_error\",\n    \"status\": 404,\n    \"details\": {\"smoc_entity_id\": \"itm_revenue_plan\"},\n    \"trace_id\": \"req_abc123xyz\",\n    \"timestamp\": \"2026-04-19T14:00:00Z\"\n  }\n}\n","lang":"json"},"children":[]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-resources","__idx":3},"children":["Related Resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/api-reference/chat-artifacts/get-ref"},"children":["Retrieve a chat artifact ref"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/api-reference/chat-artifacts/list-refs"},"children":["List chat artifact refs"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/api-reference/chat-artifacts/delete-ref"},"children":["Delete a chat artifact ref"]}]}]}]},"headings":[{"value":"Resolve a chat artifact ref by entity","id":"resolve-a-chat-artifact-ref-by-entity","depth":1},{"value":"Path parameters","id":"path-parameters","depth":4},{"value":"Returns","id":"returns","depth":2},{"value":"Related Resources","id":"related-resources","depth":2}],"frontmatter":{"title":"Resolve ref by entity","seo":{"title":"Resolve a chat artifact ref by entity"}},"lastModified":"2026-10-26T18:32:31.521Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/api-reference/chat-artifacts/get-ref-by-entity","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}