From 5f70bc4ca7e700b1920c50a1377ed85f6097ac1f Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Tue, 27 Jan 2026 09:37:31 -0500 Subject: [PATCH 1/2] refactor: rename /api/pulse to /api/pulses with array response - Refactor endpoint from /api/pulse to /api/pulses (plural) - GET now returns array of pulses instead of single pulse - For personal keys: returns array with single pulse - For org keys: returns pulses for all accounts in organization - Add optional account_id filter for org keys - Add optional active filter (true/false/undefined) - Update PulsesResponse schema to return pulses array - Rename docs folder and update navigation Co-Authored-By: Claude Opus 4.5 --- api-reference/openapi.json | 56 +++++++++++++++++++--- api-reference/pulse/get.mdx | 4 -- api-reference/pulses/list.mdx | 4 ++ api-reference/{pulse => pulses}/update.mdx | 2 +- docs.json | 6 +-- 5 files changed, 57 insertions(+), 15 deletions(-) delete mode 100644 api-reference/pulse/get.mdx create mode 100644 api-reference/pulses/list.mdx rename api-reference/{pulse => pulses}/update.mdx (50%) diff --git a/api-reference/openapi.json b/api-reference/openapi.json index f13f5887..3b34d1b9 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -2679,34 +2679,44 @@ } } }, - "/api/pulse": { + "/api/pulses": { "get": { - "description": "Retrieve pulse information for the authenticated account.", + "description": "Retrieve pulse information for accounts. For personal API keys, returns an array with a single pulse for the key owner's account. For organization API keys, returns pulses for all accounts within the organization.", "parameters": [ { "name": "account_id", "in": "query", - "description": "UUID of the account to retrieve the pulse for. Only applicable for organization API keys - org keys can specify an account_id for any account within their organization. If not provided, returns the pulse for the API key's own account.", + "description": "Filter to a specific account. Only applicable for organization API keys - org keys can filter to any account within their organization. Personal keys cannot use this parameter.", "required": false, "schema": { "type": "string", "format": "uuid" } + }, + { + "name": "active", + "in": "query", + "description": "Filter by active status. Set to 'true' to return only active pulses, 'false' for inactive pulses. If not provided, returns all pulses regardless of active status.", + "required": false, + "schema": { + "type": "string", + "enum": ["true", "false"] + } } ], "responses": { "200": { - "description": "Pulse retrieved successfully", + "description": "Pulses retrieved successfully", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PulseResponse" + "$ref": "#/components/schemas/PulsesResponse" } } } }, "400": { - "description": "Bad request", + "description": "Bad request - invalid query parameters", "content": { "application/json": { "schema": { @@ -2724,11 +2734,21 @@ } } } + }, + "403": { + "description": "Forbidden - account_id is not a member of the organization or personal key tried to filter by account_id", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } } } }, "patch": { - "description": "Update the pulse settings for the authenticated account. Use this to enable or disable the pulse.", + "description": "Update the pulse settings for an account. Use this to enable or disable the pulse.", "requestBody": { "description": "Pulse fields to update", "required": true, @@ -6845,6 +6865,28 @@ } } }, + "PulsesResponse": { + "type": "object", + "required": ["status", "pulses"], + "properties": { + "status": { + "type": "string", + "enum": ["success", "error"], + "description": "Status of the request" + }, + "pulses": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Pulse" + }, + "description": "Array of pulse objects. For personal keys, contains one pulse. For org keys, contains pulses for all accounts in the organization." + }, + "error": { + "type": "string", + "description": "Error message (only present if status is error)" + } + } + }, "UpdatePulseRequest": { "type": "object", "required": ["active"], diff --git a/api-reference/pulse/get.mdx b/api-reference/pulse/get.mdx deleted file mode 100644 index dc62468a..00000000 --- a/api-reference/pulse/get.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: 'Get Pulse' -openapi: 'GET /api/pulse' ---- diff --git a/api-reference/pulses/list.mdx b/api-reference/pulses/list.mdx new file mode 100644 index 00000000..b08d254c --- /dev/null +++ b/api-reference/pulses/list.mdx @@ -0,0 +1,4 @@ +--- +title: 'List Pulses' +openapi: 'GET /api/pulses' +--- diff --git a/api-reference/pulse/update.mdx b/api-reference/pulses/update.mdx similarity index 50% rename from api-reference/pulse/update.mdx rename to api-reference/pulses/update.mdx index af2de569..e9095363 100644 --- a/api-reference/pulse/update.mdx +++ b/api-reference/pulses/update.mdx @@ -1,4 +1,4 @@ --- title: 'Update Pulse' -openapi: 'PATCH /api/pulse' +openapi: 'PATCH /api/pulses' --- diff --git a/docs.json b/docs.json index 6de3657a..ae40b228 100644 --- a/docs.json +++ b/docs.json @@ -41,10 +41,10 @@ ] }, { - "group": "Pulse", + "group": "Pulses", "pages": [ - "api-reference/pulse/get", - "api-reference/pulse/update" + "api-reference/pulses/list", + "api-reference/pulses/update" ] }, { From e9471b921b4a12a9af297882c8f35535693f4790 Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Tue, 27 Jan 2026 09:44:35 -0500 Subject: [PATCH 2/2] fix: update PATCH /api/pulses to return PulsesResponse array Align PATCH response with GET endpoint for consistent API behavior. Both endpoints now return the same PulsesResponse schema with an array of pulses. Co-Authored-By: Claude Opus 4.5 --- api-reference/openapi.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api-reference/openapi.json b/api-reference/openapi.json index 3b34d1b9..6ec04b4c 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -2748,7 +2748,7 @@ } }, "patch": { - "description": "Update the pulse settings for an account. Use this to enable or disable the pulse.", + "description": "Update the pulse settings for an account. Use this to enable or disable the pulse. Returns an array of pulses for consistency with the GET endpoint.", "requestBody": { "description": "Pulse fields to update", "required": true, @@ -2766,7 +2766,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PulseResponse" + "$ref": "#/components/schemas/PulsesResponse" } } }