> For the complete documentation index, see [llms.txt](https://docs.cortex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortex.io/api/readme/custom-events.md). # Custom Events Use these operations to interact with custom events in Cortex. ### Required permissions Edit entities: Your API key must have the `Edit entities` permission. ## Operations ## GET /api/v1/catalog/{tagOrId}/custom-events > List custom events for entity ```json {"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Custom Events"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","description":"All requests to the Cortex API need to provide an `Authorization: Bearer ` header, where `` is an API key created in the Settings page of your workspace.","scheme":"bearer","type":"http"}},"schemas":{"CustomEventListResponse":{"required":["events","page","total","totalPages"],"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/CustomEventResponse"}},"page":{"type":"integer","description":"Current page number, 0-indexed","format":"int32"},"total":{"type":"integer","description":"Total number of results","format":"int32"},"totalPages":{"type":"integer","description":"Total number of pages","format":"int32"}}},"CustomEventResponse":{"required":["timestamp","title","type","uuid"],"type":"object","properties":{"customData":{"type":"object","additionalProperties":{"type":"object","description":"Optional property to store additional data"},"description":"Optional property to store additional data"},"description":{"type":"string","description":"Optional description of custom event"},"timestamp":{"type":"string","description":"Time when event occurred","format":"date-time"},"title":{"type":"string","description":"Name for custom event"},"type":{"type":"string","description":"Type of custom event"},"url":{"type":"string","description":"Optional URL associated with custom event"},"uuid":{"type":"string","description":"Automatically generated identifier","format":"uuid"}}},"TooManyRequestsProblemDetail":{"required":["type","title","status"],"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"retryAfter":{"minimum":0,"type":"integer","description":"The number of seconds until the rate limiting resets.","format":"int32"},"status":{"maximum":599,"minimum":100,"type":"integer","format":"int32","enum":[429]},"title":{"type":"string"},"type":{"type":"string","format":"uri-reference"}}}},"responses":{"TooManyRequests":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsProblemDetail"}}},"description":"The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.","headers":{"Retry-After":{"description":"The number of seconds until the rate limiting resets.","schema":{"minimum":0,"type":"integer","format":"int32"}}}}}},"paths":{"/api/v1/catalog/{tagOrId}/custom-events":{"get":{"operationId":"listCustomEventsForEntity","parameters":[{"description":"The tag (`x-cortex-tag`) or unique, auto-generated identifier (CID) for the entity. If the tag contains forward slashes, URL-encode each `/` as `%2F`. The tag is matched exactly as encoded, including leading, trailing, and consecutive slashes, which are preserved and not collapsed (for example, the tag `/services/payments-api` is referenced as `%2Fservices%2Fpayments-api`). Tags containing slashes are supported via the API but not in the Cortex UI; this difference is expected.","in":"path","name":"tagOrId","required":true,"schema":{"type":"string","description":"Entity identifier - can be a tag or CID"}},{"in":"query","name":"type","required":false,"schema":{"type":"string"}},{"deprecated":true,"description":"Use 'startTime' instead","in":"query","name":"timestamp","required":false,"schema":{"type":"string","format":"date-time"}},{"description":"If provided, events with greater than or equal to timestamp will be returned (a date-time without a time-zone in the ISO-8601 calendar system)","in":"query","name":"startTime","required":false,"schema":{"type":"string","format":"date-time"}},{"description":"If provided, events with less than or equal to timestamp will be returned (a date-time without a time-zone in the ISO-8601 calendar system)","in":"query","name":"endTime","required":false,"schema":{"type":"string","format":"date-time"}},{"description":"Number of results to return per page, between 1 and 1000. Default 250.","in":"query","name":"pageSize","required":true,"schema":{"type":"integer","format":"int32","default":250}},{"description":"Page number to return, 0-indexed. Default 0.","in":"query","name":"page","required":true,"schema":{"type":"integer","format":"int32","default":0}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomEventListResponse"}}},"description":"Successfully retrieved custom events"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomEventListResponse"}}},"description":"Bad Request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomEventListResponse"}}},"description":"Entity not found"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"List custom events for entity","tags":["Custom Events"]}}}} ``` ## GET /api/v1/catalog/{tagOrId}/custom-events/{uuid} > Retrieve custom event by UUID ```json {"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Custom Events"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","description":"All requests to the Cortex API need to provide an `Authorization: Bearer ` header, where `` is an API key created in the Settings page of your workspace.","scheme":"bearer","type":"http"}},"schemas":{"CustomEventResponse":{"required":["timestamp","title","type","uuid"],"type":"object","properties":{"customData":{"type":"object","additionalProperties":{"type":"object","description":"Optional property to store additional data"},"description":"Optional property to store additional data"},"description":{"type":"string","description":"Optional description of custom event"},"timestamp":{"type":"string","description":"Time when event occurred","format":"date-time"},"title":{"type":"string","description":"Name for custom event"},"type":{"type":"string","description":"Type of custom event"},"url":{"type":"string","description":"Optional URL associated with custom event"},"uuid":{"type":"string","description":"Automatically generated identifier","format":"uuid"}}},"TooManyRequestsProblemDetail":{"required":["type","title","status"],"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"retryAfter":{"minimum":0,"type":"integer","description":"The number of seconds until the rate limiting resets.","format":"int32"},"status":{"maximum":599,"minimum":100,"type":"integer","format":"int32","enum":[429]},"title":{"type":"string"},"type":{"type":"string","format":"uri-reference"}}}},"responses":{"TooManyRequests":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsProblemDetail"}}},"description":"The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.","headers":{"Retry-After":{"description":"The number of seconds until the rate limiting resets.","schema":{"minimum":0,"type":"integer","format":"int32"}}}}}},"paths":{"/api/v1/catalog/{tagOrId}/custom-events/{uuid}":{"get":{"operationId":"getCustomEventForEntityByUuid","parameters":[{"description":"The tag (`x-cortex-tag`) or unique, auto-generated identifier (CID) for the entity. If the tag contains forward slashes, URL-encode each `/` as `%2F`. The tag is matched exactly as encoded, including leading, trailing, and consecutive slashes, which are preserved and not collapsed (for example, the tag `/services/payments-api` is referenced as `%2Fservices%2Fpayments-api`). Tags containing slashes are supported via the API but not in the Cortex UI; this difference is expected.","in":"path","name":"tagOrId","required":true,"schema":{"type":"string","description":"Entity identifier - can be a tag or CID"}},{"in":"path","name":"uuid","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomEventResponse"}}},"description":"Successfully retrieved custom event"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomEventResponse"}}},"description":"Bad Request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomEventResponse"}}},"description":"Entity or custom event not found"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Retrieve custom event by UUID","tags":["Custom Events"]}}}} ``` ## POST /api/v1/catalog/{tagOrId}/custom-events > Create custom event for entity ```json {"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Custom Events"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","description":"All requests to the Cortex API need to provide an `Authorization: Bearer ` header, where `` is an API key created in the Settings page of your workspace.","scheme":"bearer","type":"http"}},"schemas":{"SaveCustomEventRequest":{"required":["timestamp","title","type"],"type":"object","properties":{"customData":{"type":"object","additionalProperties":{"type":"object","description":"Optional property to store additional data"},"description":"Optional property to store additional data"},"description":{"type":"string","description":"Optional description of custom event"},"timestamp":{"type":"string","description":"Time when event occurred","format":"date-time"},"title":{"type":"string","description":"Name for custom event"},"type":{"type":"string","description":"Type of custom event"},"url":{"type":"string","description":"Optional URL associated with custom event"}}},"CustomEventResponse":{"required":["timestamp","title","type","uuid"],"type":"object","properties":{"customData":{"type":"object","additionalProperties":{"type":"object","description":"Optional property to store additional data"},"description":"Optional property to store additional data"},"description":{"type":"string","description":"Optional description of custom event"},"timestamp":{"type":"string","description":"Time when event occurred","format":"date-time"},"title":{"type":"string","description":"Name for custom event"},"type":{"type":"string","description":"Type of custom event"},"url":{"type":"string","description":"Optional URL associated with custom event"},"uuid":{"type":"string","description":"Automatically generated identifier","format":"uuid"}}},"TooManyRequestsProblemDetail":{"required":["type","title","status"],"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"retryAfter":{"minimum":0,"type":"integer","description":"The number of seconds until the rate limiting resets.","format":"int32"},"status":{"maximum":599,"minimum":100,"type":"integer","format":"int32","enum":[429]},"title":{"type":"string"},"type":{"type":"string","format":"uri-reference"}}}},"responses":{"TooManyRequests":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsProblemDetail"}}},"description":"The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.","headers":{"Retry-After":{"description":"The number of seconds until the rate limiting resets.","schema":{"minimum":0,"type":"integer","format":"int32"}}}}}},"paths":{"/api/v1/catalog/{tagOrId}/custom-events":{"post":{"operationId":"createCustomEventForEntity","parameters":[{"description":"The tag (`x-cortex-tag`) or unique, auto-generated identifier (CID) for the entity. If the tag contains forward slashes, URL-encode each `/` as `%2F`. The tag is matched exactly as encoded, including leading, trailing, and consecutive slashes, which are preserved and not collapsed (for example, the tag `/services/payments-api` is referenced as `%2Fservices%2Fpayments-api`). Tags containing slashes are supported via the API but not in the Cortex UI; this difference is expected.","in":"path","name":"tagOrId","required":true,"schema":{"type":"string","description":"Entity identifier - can be a tag or CID"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveCustomEventRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomEventResponse"}}},"description":"Successfully created custom event"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomEventResponse"}}},"description":"Bad Request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomEventResponse"}}},"description":"Entity not found"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Create custom event for entity","tags":["Custom Events"]}}}} ``` ## PUT /api/v1/catalog/{tagOrId}/custom-events/{uuid} > Update custom event by UUID ```json {"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Custom Events"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","description":"All requests to the Cortex API need to provide an `Authorization: Bearer ` header, where `` is an API key created in the Settings page of your workspace.","scheme":"bearer","type":"http"}},"schemas":{"SaveCustomEventRequest":{"required":["timestamp","title","type"],"type":"object","properties":{"customData":{"type":"object","additionalProperties":{"type":"object","description":"Optional property to store additional data"},"description":"Optional property to store additional data"},"description":{"type":"string","description":"Optional description of custom event"},"timestamp":{"type":"string","description":"Time when event occurred","format":"date-time"},"title":{"type":"string","description":"Name for custom event"},"type":{"type":"string","description":"Type of custom event"},"url":{"type":"string","description":"Optional URL associated with custom event"}}},"CustomEventResponse":{"required":["timestamp","title","type","uuid"],"type":"object","properties":{"customData":{"type":"object","additionalProperties":{"type":"object","description":"Optional property to store additional data"},"description":"Optional property to store additional data"},"description":{"type":"string","description":"Optional description of custom event"},"timestamp":{"type":"string","description":"Time when event occurred","format":"date-time"},"title":{"type":"string","description":"Name for custom event"},"type":{"type":"string","description":"Type of custom event"},"url":{"type":"string","description":"Optional URL associated with custom event"},"uuid":{"type":"string","description":"Automatically generated identifier","format":"uuid"}}},"TooManyRequestsProblemDetail":{"required":["type","title","status"],"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"retryAfter":{"minimum":0,"type":"integer","description":"The number of seconds until the rate limiting resets.","format":"int32"},"status":{"maximum":599,"minimum":100,"type":"integer","format":"int32","enum":[429]},"title":{"type":"string"},"type":{"type":"string","format":"uri-reference"}}}},"responses":{"TooManyRequests":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsProblemDetail"}}},"description":"The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.","headers":{"Retry-After":{"description":"The number of seconds until the rate limiting resets.","schema":{"minimum":0,"type":"integer","format":"int32"}}}}}},"paths":{"/api/v1/catalog/{tagOrId}/custom-events/{uuid}":{"put":{"operationId":"replaceCustomEventForEntityByUuid","parameters":[{"description":"The tag (`x-cortex-tag`) or unique, auto-generated identifier (CID) for the entity. If the tag contains forward slashes, URL-encode each `/` as `%2F`. The tag is matched exactly as encoded, including leading, trailing, and consecutive slashes, which are preserved and not collapsed (for example, the tag `/services/payments-api` is referenced as `%2Fservices%2Fpayments-api`). Tags containing slashes are supported via the API but not in the Cortex UI; this difference is expected.","in":"path","name":"tagOrId","required":true,"schema":{"type":"string","description":"Entity identifier - can be a tag or CID"}},{"in":"path","name":"uuid","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveCustomEventRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomEventResponse"}}},"description":"Successfully updated custom event"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomEventResponse"}}},"description":"Bad Request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomEventResponse"}}},"description":"Entity or custom event not found"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Update custom event by UUID","tags":["Custom Events"]}}}} ``` ## DELETE /api/v1/catalog/{tagOrId}/custom-events > Delete ALL custom events for an entity ```json {"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Custom Events"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","description":"All requests to the Cortex API need to provide an `Authorization: Bearer ` header, where `` is an API key created in the Settings page of your workspace.","scheme":"bearer","type":"http"}},"responses":{"TooManyRequests":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsProblemDetail"}}},"description":"The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.","headers":{"Retry-After":{"description":"The number of seconds until the rate limiting resets.","schema":{"minimum":0,"type":"integer","format":"int32"}}}}},"schemas":{"TooManyRequestsProblemDetail":{"required":["type","title","status"],"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"retryAfter":{"minimum":0,"type":"integer","description":"The number of seconds until the rate limiting resets.","format":"int32"},"status":{"maximum":599,"minimum":100,"type":"integer","format":"int32","enum":[429]},"title":{"type":"string"},"type":{"type":"string","format":"uri-reference"}}}}},"paths":{"/api/v1/catalog/{tagOrId}/custom-events":{"delete":{"operationId":"deleteCustomEventsForEntity","parameters":[{"description":"The tag (`x-cortex-tag`) or unique, auto-generated identifier (CID) for the entity. If the tag contains forward slashes, URL-encode each `/` as `%2F`. The tag is matched exactly as encoded, including leading, trailing, and consecutive slashes, which are preserved and not collapsed (for example, the tag `/services/payments-api` is referenced as `%2Fservices%2Fpayments-api`). Tags containing slashes are supported via the API but not in the Cortex UI; this difference is expected.","in":"path","name":"tagOrId","required":true,"schema":{"type":"string","description":"Entity identifier - can be a tag or CID"}},{"in":"query","name":"type","required":false,"schema":{"type":"string"}},{"deprecated":true,"description":"Use 'startTime' instead","in":"query","name":"timestamp","required":false,"schema":{"type":"string","format":"date-time"}},{"description":"If provided, events with greater than or equal to timestamp will be deleted (a date-time without a time-zone in the ISO-8601 calendar system)","in":"query","name":"startTime","required":false,"schema":{"type":"string","format":"date-time"}},{"description":"If provided, events with less than or equal to timestamp will be deleted (a date-time without a time-zone in the ISO-8601 calendar system)","in":"query","name":"endTime","required":false,"schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Successfully deleted custom events"},"204":{"description":"No Content"},"400":{"description":"Bad Request"},"404":{"description":"Entity not found"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Delete ALL custom events for an entity","tags":["Custom Events"]}}}} ``` ## DELETE /api/v1/catalog/{tagOrId}/custom-events/{uuid} > Delete custom events by UUID ```json {"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Custom Events"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","description":"All requests to the Cortex API need to provide an `Authorization: Bearer ` header, where `` is an API key created in the Settings page of your workspace.","scheme":"bearer","type":"http"}},"responses":{"TooManyRequests":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsProblemDetail"}}},"description":"The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.","headers":{"Retry-After":{"description":"The number of seconds until the rate limiting resets.","schema":{"minimum":0,"type":"integer","format":"int32"}}}}},"schemas":{"TooManyRequestsProblemDetail":{"required":["type","title","status"],"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"retryAfter":{"minimum":0,"type":"integer","description":"The number of seconds until the rate limiting resets.","format":"int32"},"status":{"maximum":599,"minimum":100,"type":"integer","format":"int32","enum":[429]},"title":{"type":"string"},"type":{"type":"string","format":"uri-reference"}}}}},"paths":{"/api/v1/catalog/{tagOrId}/custom-events/{uuid}":{"delete":{"operationId":"deleteCustomEventForEntityByUuid","parameters":[{"description":"The tag (`x-cortex-tag`) or unique, auto-generated identifier (CID) for the entity. If the tag contains forward slashes, URL-encode each `/` as `%2F`. The tag is matched exactly as encoded, including leading, trailing, and consecutive slashes, which are preserved and not collapsed (for example, the tag `/services/payments-api` is referenced as `%2Fservices%2Fpayments-api`). Tags containing slashes are supported via the API but not in the Cortex UI; this difference is expected.","in":"path","name":"tagOrId","required":true,"schema":{"type":"string","description":"Entity identifier - can be a tag or CID"}},{"in":"path","name":"uuid","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successfully deleted custom event"},"204":{"description":"No Content"},"400":{"description":"Bad Request"},"404":{"description":"Entity or custom event not found"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Delete custom events by UUID","tags":["Custom Events"]}}}} ```