# 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 for the entity.","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 for the entity.","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 for the entity.","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 for the entity.","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 for the entity.","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 for the entity.","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"]}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.cortex.io/api/readme/custom-events.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.