# Resolve a chat artifact ref by entity

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.

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 `ref_id` carries a `transient_` marker.

#### Path parameters

**`smoc_entity_id`** string required

Identifier of the underlying artifact entity (the item ID). The ref's type is resolved from the entity.

## Returns

A `ChatArtifactRefByEntityResponse` object with a single `ref` field:

| Field | Type | Description |
|  --- | --- | --- |
| `ref_id` | string | The chat artifact ref ID. Carries a `transient_` marker when no persisted ref exists yet. |
| `smoc_entity_type` | string | Entity type (`document`, `presentation`, `spreadsheet`, `dashboard`). |
| `smoc_entity_id` | string | The underlying entity ID (echoed). |
| `title` | string | Current title of the entity. |
| `created_at` | string | ISO-8601 creation timestamp. |
| `thread_id` | string | null | Thread the ref was first created in, if any. |
| `message_id` | string | null | Message the ref was first created in, if any. |


Request

```bash cURL
curl -X GET "https://api.aitronos.com/v1/chat-artifacts/refs/by-entity/itm_revenue_plan" \
  -H "X-API-Key: $FREDDY_API_KEY"
```


```python Python SDK
from aitronos import Aitronos

client = Aitronos(api_key="your-api-key")
result = client.chat_artifacts.refs.resolve_by_entity(
    smoc_entity_id="itm_revenue_plan",
)
print(result.ref.ref_id, result.ref.title)
```


```python Python
import os
import requests

response = requests.get(
    "https://api.aitronos.com/v1/chat-artifacts/refs/by-entity/itm_revenue_plan",
    headers={"X-API-Key": os.environ["FREDDY_API_KEY"]},
)
print(response.json())
```


```javascript JavaScript
const response = await fetch(
  "https://api.aitronos.com/v1/chat-artifacts/refs/by-entity/itm_revenue_plan",
  { headers: { "X-API-Key": process.env.FREDDY_API_KEY } },
);
console.log(await response.json());
```

Response

```json 200 OK
{
  "ref": {
    "ref_id": "carfref_aaaa1111bbbb2222cccc3333dddd4444",
    "smoc_entity_type": "document",
    "smoc_entity_id": "itm_revenue_plan",
    "title": "Q1 Revenue Plan",
    "created_at": "2026-04-19T14:00:00Z",
    "thread_id": "thread_qwerty",
    "message_id": "msg_abcd1234"
  }
}
```


```json 404 Not Found
{
  "success": false,
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource could not be found.",
    "system_message": "Chat artifacts feature is disabled for this caller",
    "type": "client_error",
    "status": 404,
    "details": {"smoc_entity_id": "itm_revenue_plan"},
    "trace_id": "req_abc123xyz",
    "timestamp": "2026-04-19T14:00:00Z"
  }
}
```

## Related Resources

- [Retrieve a chat artifact ref](/docs/api-reference/chat-artifacts/get-ref)
- [List chat artifact refs](/docs/api-reference/chat-artifacts/list-refs)
- [Delete a chat artifact ref](/docs/api-reference/chat-artifacts/delete-ref)