Events

This page documents the Events endpoints in the Event History API microservice.

The Event History service is used to store and retrieve historical activity for a client environment. During client creation in the main Autologyx system, a client-specific ClickHouse database is created for history data, and a corresponding tenant entry is created in the default ClickHouse database. The tenant entry is used to resolve the correct client database from the client_id.

WARNING

This section documents technical and service-level Event History APIs and is intended for internal platform use and controlled engineering workflows. It should not be treated as part of the main general-purpose external Catalyst integration surface. This area is outside general support coverage, so please contact your Customer Success team if you need guidance.

API overview

This page covers the following endpoints:

POST /api/event-bridge/create-event
GET /api/history/events
GET /api/history/events/event_id/file

POST /api/event-bridge/create-event

Creates a History Event record in ClickHouse through the AWS EventBridge → Lambda → Event History API flow.

Permissions

Requires authentication.

Request

Headers

text

Request Method: POST
Content-Type: application/json
X-API-Key: API_KEY

Body schema

json

{
  "version": "string",
  "id": "string",
  "detail-type": "string",
  "source": "string",
  "account": "string",
  "time": "2022-11-10T10:26:12.111Z",
  "region": "string",
  "resources": [],
  "detail": {
    "event_id": "string",
    "event_time": "2022-11-10T10:26:12.111Z",
    "event_type_id": 1,
    "record_id": 0,
    "source_id": 0,
    "source_type_id": 0,
    "event_data": [
      "string"
    ]
  }
}

Response

Success

Status: 201 Created

json

{
  "detail": "<string>"
}

Filtering

No filters are supported.

Errors

Error	Response code	Message
Tenant not found	`400 Bad Request`	`"detail": "'{tenant}' tenant not found in database."`
Wrong API key	`401 Unauthorized`	`"detail": "Unauthorized API Key."`
Missing authorization header	`401 Unauthorized`	`"detail": "Unauthorized API Key."`

GET /api/history/events

Returns a paginated list of History Events based on query parameters.

Permissions

Requires authentication and client_id in the request header.
client_id must be a UUID v4 value.

Request

Headers

text

Request Method: GET
Content-Type: application/json
X-API-Key: API_KEY
X-Client-Id: client_id

Response

Top-level response

Key	Type	Notes
limit	int	Page size
offset	int	Page offset
total_count	int	Total number of history events visible to the API client
filtered_count	int	Number of events returned after filters are applied
results	Array	Event records

`results` array fields

Key	Type	Notes
event_id	uuid	Event identifier
event_datetime	datetime	Event timestamp
event_type	enum	Values include `record_created`, `owner_initialized`, `owners_added`, `owners_removed`, `assignees_added`, `assignees_removed`, `field_values_changed`, `record_deleted`, `document_generated`, `status_initialized`
event_data	json	Schema depends on `event_type`
source_type	enum	Values: `user`, `sequence`, `system`, `mcp`
source_id	int	Source identifier
source_name	string	Source display name. For `source_type: mcp`, resolved from the users table by `source_id`. Returns `null` if the `source_id` does not exist in the users table.
source_info	string	Additional information about the event source. For MCP events, contains the AI model identifier (e.g. `"claude-code 2.1.158"`). Returns `""` for all other event types.

`results.event_data` by event type

The structure of event_data depends on the event_type.

`owner_initialized`, `owners_added`, `owners_removed`

Returns an array of owner objects.

Key	Type	Notes
id	int	User ID
type	enum	Value: `user`
name	string	User label

json

[
  {
    "id": 9768,
    "type": "user",
    "name": "John Smith"
  }
]

`assignees_added`, `assignees_removed`

Returns an array of assignee objects.

Key	Type	Notes
id	int	User ID
type	enum	Value: `user`
name	string	User label
permission_set	Object	Permission Set object

`permission_set`

Key	Type	Notes
id	int	Permission Set ID
name	string	Permission Set label

json

[
  {
    "id": 9768,
    "type": "user",
    "name": "John Smith",
    "permission_set": {
      "id": 35,
      "name": "PermSet"
    }
  }
]

`field_values_changed`, `record_created`

Returns an array of field-value objects.

Key	Type	Notes
field_id	int	Field ID
field_type	enum	Field type
field_value	Any	Any JSON-compatible field value
field_name	string	Field label

json

[
  {
    "field_id": 9768,
    "field_type": "string",
    "field_value": "Value",
    "field_name": "Car"
  }
]

`record_deleted`

Returns an empty array.

json

[]

`document_generated`

The source page indicates this event contains document-related payload data. A representative example is:

json

[
  {
    "document_template_id": 123,
    "field_id": 12,
    "file_id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p"
  }
]

Response examples

Example: `record_deleted`

Status: 200 OK

json

{
  "limit": 1,
  "offset": 0,
  "filtered_count": 2,
  "total_count": 4,
  "results": [
    {
      "event_id": "6e165f4b-8729-487c-93eb-7bf3445554e9",
      "event_datetime": "2021-10-27T12:27:43.462803+00:00",
      "event_type": "record_deleted",
      "source_type": "mcp",
      "source_id": 6,
      "source_name": null,
      "source_info": "claude-code 2.1.158",
      "event_data": []
    }
  ]
}

Example: `document_generated`

Status: 200 OK

json

{
  "limit": 1,
  "offset": 0,
  "filtered_count": 2,
  "total_count": 4,
  "results": [
    {
      "event_id": "6e165f4b-8729-487c-93eb-7bf3445554e9",
      "event_datetime": "2021-10-27T12:27:43.462803+00:00",
      "event_type": "document_generated",
      "event_data": [
        {
          "document_template_id": 123,
          "field_id": 12,
          "file_id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p"
        }
      ],
      "source_type": "user",
      "source_id": 1
    }
  ]
}

Sorting

Sorting cannot be controlled through the request.

Results are returned in descending order by event_datetime. No other sorting is supported.

Notes:

record_created is the first event in chronological order, so it is sorted at the end of the descending result set.
owner_initialized immediately follows record_created in chronological order.

Filtering

For the full description of standard predicates, see ALX API standards - Developers guide.

Parameter	Example
event_datetime	`/api/history/events?event_datetime=2022-01-01`
event_datetime!	`/api/history/events?event_datetime__exclude=2022-01-01`
event_datetime_gt	`/api/history/events?event_datetime__gt=2022-01-01`
event_datetime_gt!	`/api/history/events?event_datetime__gt__exclude=2022-01-01`
event_datetime_gte	`/api/history/events?event_datetime__gte=2022-01-01`
event_datetime_gte!	`/api/history/events?event_datetime__gte__exclude=2022-01-01`
event_datetime_range	`/api/history/events?event_datetime__range=2022-01-01,2022-02-01`
event_datetime_range!	`/api/history/events?event_datetime__range__exclude=2022-01-01,2022-02-01`
record_id	`/api/history/events?record_id=1`
source_type	`/api/history/events?source_type=user`
source_type!	`/api/history/events?source_type__exclude=sequence`
source_type__in	`/api/history/events?source_type__in=system,user`
source_type__in!	`/api/history/events?source_type__in__exclude=sequence`
source_id	`/api/history/events?source_id=user`
source_id!	`/api/history/events?source_id__exclude=sequence`
source_id__in	`/api/history/events?source_id__in=system,user`
source_id__in!	`/api/history/events?source_id__in__exclude=sequence`
source_info	`/api/history/events?source_info=claude-code+2.1.158`
source_info__exclude	`/api/history/events?source_info__exclude=claude-code+2.1.158`
source_info__in	`/api/history/events?source_info__in=claude-code+2.1.158,cursor+1.0.0`
source_info__in__exclude	`/api/history/events?source_info__in__exclude=claude-code+2.1.158`
field_id	`/api/history/events?field_id=1`

Notes on source_info filters

Filtering is case-sensitive (ClickHouse compares byte-by-byte).
source_info (exact match) accepts an empty string "" — filters for events without metadata (i.e. non-MCP events).
source_info__in ignores empty entries (e.g. a trailing comma value is treated as a value).

Errors

Error	Response code	Message
Tenant not found	`400 Bad Request`	`"detail": "'{tenant}' tenant not found in database."`
Source type invalid	`400 Bad Request`	`{'detail': [{'loc': ['query', 'source_type'], 'msg': "value is not a valid enumeration member; permitted: 'user', 'sequence', 'system', 'mcp'", 'type': 'type_error.enum', 'ctx': {'enum_values': ['user', 'sequence', 'system', 'mcp']}}]}`
Source ID invalid	`400 Bad Request`	`{"detail": [{"loc": ["query", "source_id"], "msg": "value is not a valid integer", "type": "type_error.integer"}]}`
Field ID invalid	`400 Bad Request`	`{"detail": [{"loc": ["query", "field_id"], "msg": "value is not a valid integer", "type": "type_error.integer"}]}`
Client ID header is missing	`400 Bad Request`	`"detail": "Unauthorized Client."`
Client from header does not match any tenant	`400 Bad Request`	`"detail": "Failed to connect to tenant db."`
Wrong API key	`401 Unauthorized`	`"detail": "Unauthorized API Key."`
Missing authorization header	`401 Unauthorized`	`"detail": "Unauthorized API Key."`
Any request method other than GET is used	`405 Method Not Allowed`
Event datetime range wrong format - too many items	`422 Unprocessable Entity`	`{'detail': [{'loc': ['range_value'], 'msg': 'ensure this value has at most 2 items', 'type': 'value_error.list.max_items', 'ctx': {'limit_value': 2}}]}`
Event datetime range wrong format - too few items	`422 Unprocessable Entity`	`{'detail': [{'loc': ['range_value'], 'msg': 'ensure this value has at least 2 items', 'type': 'value_error.list.min_items', 'ctx': {'limit_value': 2}}]}`
Event datetime range wrong format on range item	`422 Unprocessable Entity`	`{'detail': [{'loc': ['range_value', 0], 'msg': 'invalid datetime format', 'type': 'value_error.datetime'}, {'loc': ['range_value', 0], 'msg': 'invalid date format', 'type': 'value_error.date'}]}`

GET /api/history/events/`event_id`/file

Generates a presigned URL for downloading a file from S3.
The client instance is identified through the X-Client-Id header.

Permissions

Requires authentication.

Request

Headers

text

Request Method: GET
Content-Type: application/force-download
X-API-Key: API_KEY
X-Client-Id: client_id

Example path

text

GET /api/history/events/1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p/file

Errors

Error	Response code	Message
Tenant not found	`400 Bad Request`	`"detail": "'{tenant}' tenant not found in database."`
Client ID header is missing	`400 Bad Request`	`"detail": "Unauthorized Client."`
Client from header does not match any tenant	`400 Bad Request`	`"detail": "Failed to connect to tenant db."`
Wrong API key	`401 Unauthorized`	`"detail": "Unauthorized API Key."`
Missing authorization header	`401 Unauthorized`	`"detail": "Unauthorized API Key."`
Any request method other than GET is used	`405 Method Not Allowed`
Event not found	`404 Not Found`	`"detail": "Event not found."`

Events ​

API overview ​

POST /api/event-bridge/create-event ​

Permissions ​

Request ​

Headers ​

Body schema ​

Response ​

Success ​

Filtering ​

Errors ​

GET /api/history/events ​

Permissions ​

Request ​

Headers ​

Response ​

Top-level response ​

results array fields ​

results.event_data by event type ​

owner_initialized, owners_added, owners_removed ​

assignees_added, assignees_removed ​

permission_set ​

field_values_changed, record_created ​

record_deleted ​

document_generated ​

Response examples ​

Example: record_deleted ​

Example: document_generated ​

Sorting ​

Filtering ​

Errors ​

GET /api/history/events/event_id/file ​

Permissions ​

Request ​

Headers ​

Example path ​

Errors ​

Events

API overview

POST /api/event-bridge/create-event

Permissions

Request

Headers

Body schema

Response

Success

Filtering

Errors

GET /api/history/events

Permissions

Request

Headers

Response

Top-level response

`results` array fields

`results.event_data` by event type

`owner_initialized`, `owners_added`, `owners_removed`

`assignees_added`, `assignees_removed`

`permission_set`

`field_values_changed`, `record_created`

`record_deleted`

`document_generated`

Response examples

Example: `record_deleted`

Example: `document_generated`

Sorting

Filtering

Errors

GET /api/history/events/`event_id`/file

Permissions

Request

Headers

Example path

Errors