> ## Documentation Index
> Fetch the complete documentation index at: https://ixoworld-mintlify-9a7944b6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Matrix state bot API

> Service API for state and ACL operations in IXO Matrix rooms.

This is a service API for IXO Matrix workflows. It is separate from IXO Protocol gateway APIs.

## Overview

* Use this API to read and manage application state events in Matrix rooms.
* Use this API to manage ACL event content for room-level permissions.
* Do not use this page as a source for protocol transaction behavior.

## Event shapes

```json theme={null}
{
  "type": "ixo.room.state",
  "state_key": "unique_identifier",
  "content": {}
}
```

```json theme={null}
{
  "type": "ixo.room.state.acl",
  "state_key": "state_event_key",
  "content": {
    "read": ["@user:domain.com"],
    "write": ["@admin:domain.com"]
  }
}
```

## Authentication and endpoints

<CardGroup cols={2}>
  <Card title="Authentication matrix" href="/reference/authentication-matrix">
    Confirm required credentials and auth patterns by interface.
  </Card>

  <Card title="Networks and endpoints" href="/reference/networks-and-endpoints">
    Confirm endpoint mappings by network and environment.
  </Card>
</CardGroup>

## Troubleshooting

* **`403` / ACL denied** — Bot token lacks power level or room membership; verify room ID, bot user ID, and ACL event content.
* **State event rejected** — Invalid `state_key`, oversized `content`, or conflicting types; compare with working examples in [IXO Matrix](/articles/ixo-matrix).
* **Wrong homeserver** — Matrix is federation-aware; confirm `baseUrl` and user IDs match the deployment in [Networks and endpoints](/reference/networks-and-endpoints).
* **Rate limits** — Back off and batch state updates; see [Error handling](/api-reference/errors) for generic HTTP retry guidance.

## Related references

<CardGroup cols={2}>
  <Card title="API authentication" href="/api-reference/authentication">
    Review authentication patterns used across IXO API interfaces.
  </Card>

  <Card title="Product and SDK map" href="/reference/product-and-sdk-map">
    Navigate IXO products, APIs, and SDK references.
  </Card>
</CardGroup>