# Content State

The [Content State API](https://iiif.io/api/content-state/) encodes a shareable
reference to a IIIF resource or region — as a plain URI, inline JSON, or a
base64url-encoded annotation. iiisight decodes any of these into a
{class}`~iiisight.ContentState`, and encodes new ones.

## Decoding

```python
state = iiisight.content_state.decode(token)

state.target_id     # the referenced resource (a canvas, manifest, …)
state.part_of       # the containing manifest id, if the target is within one
state.region        # a selector/fragment like "xywh=0,0,50,50", if any
```

`ContentState.reference` gives you a {class}`~iiisight.Reference` you can hand
straight to the client — it points at the fetchable document (the containing
manifest when known, since a canvas URI is often not directly dereferenceable):

::::{tab-set}
:::{tab-item} Async
```python
state = iiisight.content_state.decode(token)
async with iiisight.AsyncClient() as client:
    doc = await client.resolve(state.reference)
```
:::
:::{tab-item} Sync
```python
state = iiisight.content_state.decode(token)
with iiisight.Client() as client:
    doc = client.resolve(state.reference)
```
:::
::::

Invalid tokens raise {class}`~iiisight.ContentStateError`.

## Encoding

```python
token = iiisight.content_state.encode(
    "https://example.org/canvas/1",
    part_of="https://example.org/manifest",
    region="xywh=0,0,50,50",
)
```

This produces the compact base64url form (padding stripped), ready to put in a URL
or share.