API Reference

This reference covers the endpoints available to robots for interacting with servers.

Authentication

All endpoints require a robot API key:

Authorization: Robot lag_robot_<prefix>_<secret>

The API key is issued when a robot is created and can be regenerated from the management portal.

Base URL

https://api.trylag.com/robots/@me

Endpoints

Send Message

POST /robots/@me/servers/:serverId/rooms/:roomId/messages

Sends a message to a room as the robot. Requires send_messages permission.

Request body:

{
  "content": "Hello from the robot!"
}

Field	Type	Required	Description
content	string	Yes	Message text (1-2000 characters)

Response (201):

{
  "id": "msg_abc123",
  "roomId": "room_xyz",
  "userId": null,
  "username": "My Bot",
  "displayName": "My Bot",
  "avatarUrl": null,
  "content": "Hello from the robot!",
  "createdAt": "2024-01-15T12:30:00.000Z",
  "editedAt": null,
  "robotId": "robot_abc123"
}

Edit Message

PATCH /robots/@me/servers/:serverId/rooms/:roomId/messages/:messageId

Edits a message previously sent by the robot. Robots can only edit their own messages. Requires send_messages permission.

Request body:

{
  "content": "Updated message content"
}

Response (200):

{
  "id": "msg_abc123",
  "roomId": "room_xyz",
  "content": "Updated message content",
  "editedAt": "2024-01-15T12:35:00.000Z"
}

Delete Message

DELETE /robots/@me/servers/:serverId/rooms/:roomId/messages/:messageId

Deletes a message previously sent by the robot. Robots can only delete their own messages. Requires send_messages permission.

Response (204): No content.

SSE Event Stream

GET /robots/@me/events/sse

Opens a persistent Server-Sent Events connection for receiving events in real time. The server sends a keepalive ping every 30 seconds.

Headers:

Header	Description
Last-Event-ID	Optional. Resume from a specific event ID to replay missed events.

Events are delivered as standard SSE with id, event (the event type), and data (JSON payload) fields.

See Transport Types for connection details.

Poll Events

GET /robots/@me/events/poll

Retrieves pending events via long-polling. The server holds the connection for up to 30 seconds waiting for new events. Returns immediately if events are already queued.

Response (200):

[
  {
    "id": "evt_abc123",
    "eventType": "room.message",
    "payload": { ... },
    "createdAt": "2024-01-15T12:30:00.000Z"
  }
]

Returns an empty array if no events arrive within the timeout window. Up to 50 events are returned per request.

See Transport Types for polling details.

Rate Limits

Scope	Limit
Global (all endpoints)	100 requests per minute
Send/edit/delete message	10 requests per 10 seconds

When rate limited, the API returns a 429 Too Many Requests status with a Retry-After header indicating how many seconds to wait.

Error Responses

All errors follow a consistent format:

{
  "error": "Bad Request",
  "message": "A description of what went wrong",
  "statusCode": 400
}

Status Code	Meaning
400	Invalid request body or parameters
401	Missing or invalid authentication
403	Insufficient permissions or robot does not belong to this server
404	Resource not found
429	Rate limit exceeded
500	Internal server error