Object Records History Events

This technical design describes API for access Object Record History Events.

Implementation details can be found in external document: Event History - Object Records - Technical Design. History Events API Implementation details can be found: Event History API - Microservice implementation.

Object Records History Events API

GET /api/object-records/`record_id`/history/

Endpoint to receive list of Object Records History Events stored in external application.

Permissions

Perm to check: object_class.view (for individual Object Class). Permission can be checked, for example, by retrieving details of Object Classes (GET /api/object-classes/{class_id}/): _meta.permissions Users of an external type are not allowed to access this endpoint.

URL parameters

Key	Notes
record_id	Object Record ID

Request schema

Headers

Request Method: GET
Authorization: JWT access_token

Response

Key	Type	Notes
limit	int
offset	int
total_count	int	Total number of permission sets for specific object class.
filtered_count	int	Number of permission sets for specific object class if some filters are applied.
next	URL / null	Next page URL (null if there is no next page)
previous	URL / null	Previous page URL (null if there is no previous page)
results	Array	Described in the next table.

Response `results` array

Key	Type	Notes
event_id	uuid
event_datetime	datetime
event_type	enum	Values: record_created, owner_initialized, owners_added, owners_removed, assignees_added, assignees_removed, field_values_changed, record_deleted, document_generated, status_initialized
source_type	enum	Values: user, sequence, system, mcp.
source_name	string
source_id	int
source_info	string	AI model identifier for `mcp` events (e.g. `"claude-code 2.1.158"`). Empty string `""` for all other source types.
event_data	json

Response `results.event_data` json

Depends on event_type returned event_data schema is different.

Response results.event_data for event_type in owner_initialized, owners_added, owners_removed is an Array with Object.

Key	Type	Notes
id	int	User id
type	enum	Value 'user'
name	string	User label

json

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

Response results.event_data for event_type in assignees_added, assignees_removed is an Object.

Key	Type	Notes
assignees	Array	List with User or User Groups objects
permission_set	Object	Permission Set Object

where assignees is

Key	Type	Notes
id	int	User or Users Group id
type	enum	Value 'user' or 'user_group'
name	string	User First and Last name or User Group name

and permission_set is

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

json

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

or in case of User Group assignees

json

{ 
 "assignees":  [
   {
    "id": 22,
    "type": "user_group",
    "name": "Acme group"
   }
 ],
 "permission_set": {
    "id": 3,
    "name": "PermSet"  
  } 
}

Response results.event_data for event_type as field_values_changed is an Array with Object.

Key	Type	Notes
id	int	Field id
type	enum	Field type
value	Any	Any JSON compatible field value
name	string	Field label

json

[
 {
  "id": 9768,
  "type": "string",
  "value": "Ford",
  "name": "Car Name"
 }
]

Data for specific field types can include additional attributes.

Field's data of document type contains additional value_labels attribute - list of files' names in the same order as for value attribute.

json

{
  "id": 36,
  "type": "document",
  "name": "Passport",
  "value": [
    160
  ],
  "value_labels": [
    "passport_scan.pdf"
  ]
}

Field's data of user type contains additional value_labels

value_labels.users contains the list of user first and last names corresponding to the user ids in value.users in the same ordering
value_labels.user_groups contains the list of group names corresponding to the user_group ids in value.user_groups in the same ordering
value_labels are sorted alphabetically by ascending.
value_labels represent the values in the moment of event occurrence.

Sample response:

json

{
  "id": 16,
  "type": "user",
  "name": "Reporters",
  "value": {
   "users": [
     1,
     20,
     100
   ],
   "user_groups": [
     1
   ]
  },
  "value_labels": {
   "users": [
     "Adam Lee",
     "Anthony Pawn",
     "Chuck Norris"
   ],
   "user_groups": [
     "Reporters"
   ]
  }
}

In case the empty list is saved in either user or user_groups the response format is:

json

{
  "id": 16,
  "type": "user",
  "name": "Reporters",
  "value": {"user_groups": [], "users": []},
  "value_labels": {"user_groups": [], "users": []}
}

Response results.event_data for event_type as record_created is an empty Array.

json

[]

Response schema

Status 200 OK
Body:

json

{
  "limit": <int>,  
  "offset": <int>,  
  "filtered_count": <int>,  
  "total_count": <int>,  
  "next": <str | null>,  
  "previous": <str | null>,  
  "results": [
    {
      "event_id": <uuid>,
      "event_datetime": <datetime>,
      "event_type": <str>,
      "source_type": <str>,
      "source_id": <int>,
      "source_name": <str | null>,
      "source_info": <str>,
      "record_id": <int>,
      "created_at": <datetime>,
      "event_data": <json> 
    }
  ]
}

Response results.event_data for event_type as document_generated is an Array with Object.

Key	Type	Notes
document_template_id	int	Document template id
file_id	uuid	A unique file identifier in history database
file_name	string	A string name of the generated file

json

[
   {
      "document_template_id": 565, 
      "file_id": "df00cf1b-8582-451d-a3b9-238ecfb07a8b", 
      "file_name": "test_2023-09-05.docx"
   }
]

Response results.event_data for event_type as status_initialized is an Array.

json

[{"status": "initiated"}]

Response example

json

{
  "limit": 10,
  "offset": 0,
  "filtered_count": 1,
  "total_count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "event_id": "6e165f4b-8729-487c-93eb-7bf3445554e9",
      "event_datetime": "2021-10-27T12:27:43.462803+00:00",
      "event_type": "owner_initialized",
      "source_type": "user",
      "source_id": 1,
      "source_name": "John Smith",
      "source_info": "",
      "record_id": 56,
      "created_at": "2021-10-27T12:27:43.462803+00:00",
      "event_data": [
        {
          "id": 1,
          "type": "user",
          "name": "John Smith"
        }
      ]
    }
  ]
}

Example result object for an MCP event (source_type: mcp):

json

{
  "event_datetime": "2024-04-20T09:15:00.462803+00:00",
  "event_type": "record_created",
  "source_type": "mcp",
  "source_id": 6,
  "source_name": null,
  "source_info": "claude-code 2.1.158",
  "event_data": []
}

Sorting

Not available. The results are sorted ( descending ) by event_datetime. No other sorting is supported.

record_created is the first event (in chronological order), hence it is sorted at the end.
owner_initialized immediately follows record_created (in chronological order).

Filtering

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

Filtering by History Event fields

Parameter	Type	Example
event_datetime	datetime	{build}/api/object-classes/{record_id}/history/?event_datetime__range=2022-01-01,2023-01-01
source_type	enum	{build}/api/object-classes/{record_id}/history/?source_type=user
source_type__in	enum	{build}/api/object-classes/{record_id}/history/?source_type__in=user,sequence,system,mcp
source_id	int	{build}/api/object-classes/{record_id}/history/?source_id=0
source_id__in	int	{build}/api/object-classes/{record_id}/history/?source_id__in=0,1,2,3
field_id	int	{build}/api/object-classes/{record_id}/history/?field_id=1
event_type	enum	{build}/api/object-classes/{record_id}/history/?source_type=record_created
event_type__in	enum	{build}/api/object-classes/{record_id}/history/?source_type__in=record_created,owner_initialized
source_info	string	{build}/api/object-classes/{record_id}/history/?source_info=claude-code+2.1.158
source_info__in	string	{build}/api/object-classes/{record_id}/history/?source_info__in=claude-code+2.1.158,cursor+1.0.0

Both parameters also accept an exclusion variant via the ! suffix: source_info!, source_info__in!.

Errors

Error	Response code	Message
Invalid value used with event_datetime.	400 Bad Request	"event_datetime": [ "Enter a valid date/time." ]
Invalid range filter value used with event_datetime.	400 Bad Request	"event_datetime__range": [ "Range query expects two values." ]
Invalid value used with source_type.	400 Bad Request	"source_type": [ "Select a valid choice. "<source_type>" is not one of the available choices." ]
Invalid value used with source_type!	400 Bad Request	"source_type!": [ "Select a valid choice. "<source_type>" is not one of the available choices." ]
Invalid value used with source_type__in.	400 Bad Request	"source_type__in": [ "Select a valid choice. "<source_type>" is not one of the available choices." ]
Invalid value used with source_type__in!.	400 Bad Request	"source_type__in!": [ "Select a valid choice. "<source_type>" is not one of the available choices." ]
Invalid value used with source_id.	400 Bad Request	"source_id": [ "Enter a number." ]
Invalid value used with source_id!	400 Bad Request	"source_id!": [ "Enter a number." ]
Invalid value used with source_id__in.	400 Bad Request	"source_id__in": [ "Enter a number." ]
Invalid value used with source_id__in!.	400 Bad Request	"source_id__in!": [ "Enter a number." ]
Invalid value used with field_id.	400 Bad Request	"field_id": [ "Select a valid choice. That choice is not one of the available choices." ]
Invalid value used with event_type.	400 Bad Request	"event_type": [ "Select a valid choice. "<event_type>" is not one of the available choices." ]
Invalid value used with event_type!	400 Bad Request	"event_type!": [ "Select a valid choice. "<event_type>" is not one of the available choices." ]
Invalid value used with event_type__in.	400 Bad Request	"event_type__in": [ "Select a valid choice. "<event_type>" is not one of the available choices." ]
Invalid value used with event_type__in!.	400 Bad Request	"event_type__in!": [ "Select a valid choice. "<event_type>" is not one of the available choices." ]
Invalid value used with source_info.	400 Bad Request	"source_info": [ "Enter a valid value." ]
Invalid value used with source_info!	400 Bad Request	"source_info!": [ "Enter a valid value." ]
Invalid value used with source_info__in.	400 Bad Request	"source_info__in": [ "Enter a valid value." ]
Invalid value used with source_info__in!.	400 Bad Request	"source_info__in!": [ "Enter a valid value." ]
Insufficient permissions	403 Forbidden	"detail": "You do not have permission to perform this action."
Object Record for `record_id` not found.	404 Not Found

OPTIONS /api/object-records/`record_id`/history/

Permissions

Requires authentication only.

Request

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

OPTIONS /api/object-records/`record_id`/history/

Response

Successful status 200 OK
Response body:

json

{
    "list": {
        "columns": [
            {
                "alias": "event_id",
                "type": "uuid",
                "predicates": [],
                "sort_ok": false
            },
            {
                "alias": "event_datetime",
                "type": "datetime",
                "predicates": [
                  "exact",
                  "gt",
                  "gte",
                  "lt",
                  "lte",
                  "range"
                ],
                "sort_ok": false
            },
            {
                "alias": "event_type",
                "type": "enum",
                "predicates": [],
                "sort_ok": false,
                "values": [
                    {
                        "value": "record_created",
                        "text": "Record created"
                    },
                    {
                        "value": "field_values_changed",
                        "text": "Field values changed"
                    },
                    {
                        "value": "owner_initialized",
                        "text": "Owner initialized"
                    },
                    {
                        "value": "owners_added",
                        "text": "Owners added"
                    },
                    {
                        "value": "owners_removed",
                        "text": "Owners removed"
                    },
                    {
                        "value": "assignees_added",
                        "text": "Assignees added"
                    },
                    {
                        "value": "assignees_removed",
                        "text": "Assignees removed"
                    },
                    {
                        "value": "document_generated",
                        "text": "Document generated" 
                    },
                    {
                        "value": "status_initialized",
                        "text": "Status initialized" 
                    }
                ]
            },
            {
                "alias": "source_type",
                "type": "enum",
                "predicates": [],
                "sort_ok": false,
                "values": [
                    {
                        "value": "user",
                        "text": "User"
                    },
                    {
                        "value": "sequence",
                        "text": "Sequence"
                    },
                    {
                        "value": "system",
                        "text": "System"
                    },
                    {
                        "value": "mcp",
                        "text": "MCP"
                    }
                ]
            },
            {
                "alias": "source_name",
                "type": "string",
                "predicates": [],
                "sort_ok": false
            },
            {
                "alias": "source_id",
                "type": "int",
                "predicates": [
                    "exact",
                    "in"
                ],
                "sort_ok": false
            },
            {
                "alias": "source_info",
                "type": "string",
                "predicates": [
                    "exact",
                    "in"
                ],
                "sort_ok": false
            },
            {
                "alias": "record_id",
                "type": "int",
                "predicates": [],
                "sort_ok": false
            },
            {
                "alias": "created_at",
                "type": "datetime",
                "predicates": [],
                "sort_ok": false
            },
            {
                "alias": "event_data",
                "type": "json",
                "predicates": [],
                "sort_ok": false
            }
        ]
    }
}

Object Records History Events ​

Object Records History Events API ​

GET /api/object-records/record_id/history/ ​

Permissions ​

URL parameters ​

Request schema ​

Response ​

Response results array ​

Response results.event_data json ​

Response schema ​

Response example ​

Sorting ​

Filtering ​

Filtering by History Event fields ​

Errors ​

OPTIONS /api/object-records/record_id/history/ ​

Permissions ​

Request ​

Response ​

Object Records History Events

Object Records History Events API

GET /api/object-records/`record_id`/history/

Permissions

URL parameters

Request schema

Response

Response `results` array

Response `results.event_data` json

Response schema

Response example

Sorting

Filtering

Filtering by History Event fields

Errors

OPTIONS /api/object-records/`record_id`/history/

Permissions

Request

Response