The Matrix state bot API is a service API for IXO Matrix rooms. Use it to read and manage application state events in a room, and to manage the ACL event content that sets who can read and write that state.
It is separate from the IXO Protocol gateway APIs. Do not use this page as a source for protocol transaction behaviour.
Event shapes
A state event:
{
"type": "ixo.room.state",
"state_key": "unique_identifier",
"content": {}
}An ACL event, which lists who can read and who can write:
{
"type": "ixo.room.state.acl",
"state_key": "state_event_key",
"content": {
"read": ["@user:domain.com"],
"write": ["@admin:domain.com"]
}
}Authentication and endpoints
| What you need | Where to find it |
|---|---|
| Required credentials and auth patterns | Authentication matrix |
| Bot base URL | Supplied by the service operator. There is no global default. See Networks and endpoints |
Troubleshooting
| Problem | Cause and fix |
|---|---|
403 or ACL denied | The bot token lacks power level or room membership. Verify the room ID, the bot user ID and the ACL event content. |
| State event rejected | Invalid state_key, oversized content, or conflicting types. Compare with working examples in IXO Matrix. |
| Wrong homeserver | Matrix is federation-aware. Confirm that baseUrl and user IDs match the deployment in Networks and endpoints. |
| Rate limits | Back off and batch state updates. See Errors for generic HTTP retry guidance. |