From 97cbff77efe49a0cc0132da5c3b4a4649facc8fc Mon Sep 17 00:00:00 2001 From: Deshraj Yadav Date: Fri, 14 Nov 2025 20:53:31 -0800 Subject: [PATCH] Add events API docs and spec updates (#3752) --- docs/api-reference.mdx | 4 + docs/api-reference/events/get-event.mdx | 6 + docs/api-reference/events/get-events.mdx | 13 ++ docs/docs.json | 60 +++++-- docs/openapi.json | 202 ++++++++++++++++++++++- 5 files changed, 269 insertions(+), 16 deletions(-) create mode 100644 docs/api-reference/events/get-event.mdx create mode 100644 docs/api-reference/events/get-events.mdx diff --git a/docs/api-reference.mdx b/docs/api-reference.mdx index 9673a8034..0f31c61c9 100644 --- a/docs/api-reference.mdx +++ b/docs/api-reference.mdx @@ -56,6 +56,10 @@ Explore the full API organized by functionality: Core and advanced operations: CRUD, search, batch updates, history, and exports + + Track and monitor the status of asynchronous memory operations + + Manage users, agents, and their associated memory data diff --git a/docs/api-reference/events/get-event.mdx b/docs/api-reference/events/get-event.mdx new file mode 100644 index 000000000..08db45271 --- /dev/null +++ b/docs/api-reference/events/get-event.mdx @@ -0,0 +1,6 @@ +--- +title: 'Get Event' +openapi: get /v1/event/{event_id}/ +--- + +Retrieve details about a specific event by passing its `event_id`. This endpoint is particularly helpful for tracking the status, payload, and completion details of asynchronous memory operations. diff --git a/docs/api-reference/events/get-events.mdx b/docs/api-reference/events/get-events.mdx new file mode 100644 index 000000000..2e83979f9 --- /dev/null +++ b/docs/api-reference/events/get-events.mdx @@ -0,0 +1,13 @@ +--- +title: 'Get Events' +openapi: get /v1/events/ +--- + +List recent events for your organization and project. + +## Use Cases + +- **Dashboards**: Summarize adds/searches over time by paging through events. +- **Alerting**: Poll for `FAILED` events and trigger follow-up workflows. +- **Audit**: Store the returned payload/metadata for compliance logs. + diff --git a/docs/docs.json b/docs/docs.json index 332c3a331..a7fc430ae 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -12,7 +12,7 @@ "navigation": { "versions": [ { - "version": "v1.0.0", + "version": "v1.0.1", "anchors": [ { "anchor": "Documentation", @@ -24,7 +24,9 @@ { "group": "Start Here", "icon": "home", - "pages": ["introduction"] + "pages": [ + "introduction" + ] } ] }, @@ -105,7 +107,9 @@ { "group": "Support & Troubleshooting", "icon": "life-buoy", - "pages": ["platform/faqs"] + "pages": [ + "platform/faqs" + ] }, { "group": "Migration Guide", @@ -119,7 +123,9 @@ { "group": "Contribute", "icon": "clipboard-list", - "pages": ["platform/contribute"] + "pages": [ + "platform/contribute" + ] } ] }, @@ -274,7 +280,10 @@ { "group": "Community & Support", "icon": "users", - "pages": ["contributing/development", "contributing/documentation"] + "pages": [ + "contributing/development", + "contributing/documentation" + ] } ] }, @@ -298,7 +307,9 @@ { "group": "Getting Started", "icon": "lightbulb", - "pages": ["cookbooks/overview"] + "pages": [ + "cookbooks/overview" + ] }, { "group": "Essentials", @@ -369,7 +380,9 @@ { "group": "Overview", "icon": "plug", - "pages": ["integrations"] + "pages": [ + "integrations" + ] }, { "group": "Agent Frameworks", @@ -399,7 +412,9 @@ { "group": "Cloud & Infrastructure", "icon": "cloud", - "pages": ["integrations/aws-bedrock"] + "pages": [ + "integrations/aws-bedrock" + ] }, { "group": "Developer Tools", @@ -421,7 +436,10 @@ { "group": "Getting Started", "icon": "rocket", - "pages": ["api-reference", "api-reference/organizations-projects"] + "pages": [ + "api-reference", + "api-reference/organizations-projects" + ] }, { "group": "Core Memory Operations", @@ -448,6 +466,14 @@ "api-reference/memory/delete-memories" ] }, + { + "group": "Events APIs", + "icon": "clock", + "pages": [ + "api-reference/events/get-events", + "api-reference/events/get-event" + ] + }, { "group": "Entities APIs", "icon": "users", @@ -498,12 +524,16 @@ { "group": "Changelog", "icon": "rocket", - "pages": ["changelog"] + "pages": [ + "changelog" + ] }, { "group": "Legacy Docs", "icon": "archive", - "pages": ["v0x/introduction"] + "pages": [ + "v0x/introduction" + ] } ] } @@ -524,7 +554,11 @@ { "group": "Getting Started", "icon": "rocket", - "pages": ["v0x/introduction", "v0x/quickstart", "v0x/faqs"] + "pages": [ + "v0x/introduction", + "v0x/quickstart", + "v0x/faqs" + ] }, { "group": "Core Concepts", @@ -1040,4 +1074,4 @@ "destination": "/platform/features/memory-export" } ] -} +} \ No newline at end of file diff --git a/docs/openapi.json b/docs/openapi.json index 7205f340f..4feb00a77 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -359,13 +359,209 @@ "tags": [ "events" ], - "summary": "Retrieve all events for the currently logged-in user.", - "description": "This endpoint returns a paginated list of events associated with the authenticated user.\nYou can filter the events by event type, start date, and end date.\n\nQuery Parameters:\n- event_type: Filter by event type (ADD or SEARCH)\n- start_date: Filter events after this date (format: YYYY-MM-DD)\n- end_date: Filter events before this date (format: YYYY-MM-DD)\n- page: Page number for pagination\n- page_size: Number of items per page (default: 50, max: 100)", + "summary": "Retrieve all events for current organization and project.", "operationId": "events_list", "responses": { "200": { "description": "Successfully retrieved events.", - "content": {} + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "count": { + "type": "integer", + "description": "Total number of events matching the filters." + }, + "next": { + "type": "string", + "nullable": true, + "description": "URL for the next page of results." + }, + "previous": { + "type": "string", + "nullable": true, + "description": "URL for the previous page of results." + }, + "results": { + "type": "array", + "description": "Array of event objects.", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "The unique identifier of the event." + }, + "event_type": { + "type": "string", + "description": "The type of event (e.g., ADD, SEARCH)." + }, + "status": { + "type": "string", + "enum": [ + "PENDING", + "RUNNING", + "FAILED", + "SUCCEEDED" + ], + "description": "The current status of the event." + }, + "payload": { + "type": "object", + "description": "The original payload associated with the event." + }, + "metadata": { + "type": "object", + "nullable": true, + "description": "Additional metadata associated with the event." + }, + "results": { + "type": "array", + "description": "Array of results produced by the event." + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the event was created." + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the event was last updated." + }, + "started_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when event processing started." + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when event processing completed." + }, + "latency": { + "type": "number", + "description": "Processing time in milliseconds." + } + } + } + } + }, + "required": [ + "count", + "results" + ] + } + } + } + } + } + } + }, + "/v1/event/{event_id}/": { + "get": { + "tags": [ + "events" + ], + "summary": "Retrieve details of a specific event by its ID.", + "operationId": "event_read", + "parameters": [ + { + "name": "event_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "The unique identifier of the event (UUID)." + } + ], + "responses": { + "200": { + "description": "Successfully retrieved event details.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "The unique identifier of the event." + }, + "event_type": { + "type": "string", + "description": "The type of event (e.g., ADD, SEARCH)." + }, + "status": { + "type": "string", + "enum": [ + "PENDING", + "RUNNING", + "FAILED", + "SUCCEEDED" + ], + "description": "The current status of the event." + }, + "payload": { + "type": "object", + "description": "The original payload associated with the event." + }, + "metadata": { + "type": "object", + "nullable": true, + "description": "Additional metadata associated with the event." + }, + "results": { + "type": "array", + "description": "Array of results produced by the event." + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the event was created." + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the event was last updated." + }, + "started_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when event processing started." + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when event processing completed." + }, + "latency": { + "type": "number", + "description": "Processing time in milliseconds." + } + } + } + } + } + }, + "404": { + "description": "Event not found.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "detail": { + "type": "string" + } + } + } + } + } } } }