Skip to content

API reference

Events

An event is a notice that something happened in the organisation: a run finished, a review was decided, billing was paused. The same events are sent to your webhook endpoints; these calls list them, so you can catch up after downtime.

The Event object

An event is a notice that something happened in the organisation. It carries ids, links and counts, never the content of your files.

Attributes

  • idstringRequired
  • objectstringRequired

    Possible valuesevent

  • typestringRequired
  • createdstring (date-time)Required
  • dataobjectRequired

    What happened. object points at the thing it happened to: fetch it for its current state.

    Show child attributesHide child attributes
    • objectobjectOptional
      Show child attributesHide child attributes
      • idstringOptional
      • typestringOptional
      • urlstringOptional

List all events

PermissionAny

Returns the organisation’s recent events, newest first: the same notices a webhook endpoint is sent. Only events in areas your key can read are listed, and billing events only to owners. Page with before set to the previous page’s next, an opaque value.

Query parameters

  • typestringOptional

    Only this type; repeat for several.

  • beforestringOptional

    The previous page’s next: an opaque cursor.

  • limitintegerOptional

    1 to 100, default 50.

Returns

A page of events.

Returns a list of Event objects.

Errors

StatusCodeMeaning
400

limit or before is refused.

401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_key

403 for a role below the route’s minimum (“Your role (<role>) can’t <action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code wrong_key with “This key needs the <Area> · <Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can’t do that.” for a call only the Mestra apps make.

404not_found

not_found: “Not found.” An unknown id, or webhooks are off.

409api_off

409 with code api_off (“Turn on the API in Developer → API and MCP first.”): an owner hasn’t turned the API on for this organisation, so no API key works yet. An owner turns it on in Settings, then API.

Retrieve an event

PermissionAny

Returns one event. An event in an area your key can’t read answers 404, as an unknown id does.

Path parameters

  • idstringRequired

Returns

The event.

Returns the Event object.

Errors

StatusCodeMeaning
401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_key

403 for a role below the route’s minimum (“Your role (<role>) can’t <action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code wrong_key with “This key needs the <Area> · <Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can’t do that.” for a call only the Mestra apps make.

404not_found

not_found: “Not found.” An unknown id, or webhooks are off.

409api_off

409 with code api_off (“Turn on the API in Developer → API and MCP first.”): an owner hasn’t turned the API on for this organisation, so no API key works yet. An owner turns it on in Settings, then API.