{"openapi":"3.1.0","info":{"title":"Particle Products (BYOK) API","version":"0.1.0","description":"Particle Products (BYOK) lets an AI assistant read your own Particle Products data through the Particle Products API with a key you supply (Particle access token). Read-only: 10 tools (list_my_products, get_product, list_product_firmware, get_product_firmware, list_product_groups, get_online_metrics, get_event_metrics, get_function_call_metrics, get_variable_request_metrics, get_fleet_sim_usage)....\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-particle-products.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-particle-products/docs"},"termsOfService":"https://connectorbay.com/byok-particle-products/terms"},"servers":[{"url":"https://byok-particle-products.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-particle-products/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_my_products":{"post":{"operationId":"list_my_products","summary":"List the Particle products the token's user can access with id, platform id, name, slug, description and device groups. ","description":"List the Particle products the token's user can access with id, platform id, name, slug, description and device groups. Use for \"Which Particle products do I have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_my_productsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_product":{"post":{"operationId":"get_product","summary":"Get one Particle product: id, name, slug, description, platform id, organization and device protection status. Use for \"","description":"Get one Particle product: id, name, slug, description, platform id, organization and device protection status. Use for \"Show the Particle product my-product\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"product":{"description":"Product id (a number) or product slug, for example 'my-product'.","maxLength":80,"title":"Product","type":"string"}},"required":["product"],"title":"get_productArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_product_firmware":{"post":{"operationId":"list_product_firmware","summary":"List all firmware versions uploaded to a product with version, title, description, file size, whether it is the product ","description":"List all firmware versions uploaded to a product with version, title, description, file size, whether it is the product default, upload time, released groups and device count. Use for \"Which firmware versions does my Particle product have and how many devices run each\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"product":{"description":"Product id (a number) or product slug, for example 'my-product'.","maxLength":80,"title":"Product","type":"string"}},"required":["product"],"title":"list_product_firmwareArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_product_firmware":{"post":{"operationId":"get_product_firmware","summary":"Get one firmware version of a product by its version number. Use for \"Show version 3 of the firmware of Particle product","description":"Get one firmware version of a product by its version number. Use for \"Show version 3 of the firmware of Particle product my-product\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"product":{"description":"Product id (a number) or product slug, for example 'my-product'.","maxLength":80,"title":"Product","type":"string"},"version":{"description":"Firmware version number, for example 3.","maximum":1000000,"minimum":1,"title":"Version","type":"integer"}},"required":["product","version"],"title":"get_product_firmwareArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_product_groups":{"post":{"operationId":"list_product_groups","summary":"List the device groups of a product with name, description, firmware version and colour. Optionally filter by part of th","description":"List the device groups of a product with name, description, firmware version and colour. Optionally filter by part of the group name. Use for \"Which device groups does my Particle product have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"product":{"description":"Product id (a number) or product slug, for example 'my-product'.","maxLength":80,"title":"Product","type":"string"},"name":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Only groups whose name contains this text.","title":"Name"}},"required":["product"],"title":"list_product_groupsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_online_metrics":{"post":{"operationId":"get_online_metrics","summary":"Count the product devices that had an active cloud connection per time bucket, optionally by firmware version, Device OS","description":"Count the product devices that had an active cloud connection per time bucket, optionally by firmware version, Device OS version or group. Use for \"How many devices of my Particle product were online each hour yesterday\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"product":{"description":"Product id (a number) or product slug, for example 'my-product'.","maxLength":80,"title":"Product","type":"string"},"start_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the period as ISO 8601, for example 2026-10-01T00:00:00.000Z (default: now).","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End of the period as ISO 8601 (default: now).","title":"End Date"},"bucket_size":{"anyOf":[{"maximum":2592000,"minimum":16,"type":"integer"},{"type":"null"}],"default":null,"description":"Seconds per time bucket; must be greater than 15 (default 900).","title":"Bucket Size"},"product_fw":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only devices running this product firmware version number.","title":"Product Fw"},"device_os_version":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only devices running this Device OS version, for example '5.8.0'.","title":"Device Os Version"},"device_group":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Only devices in this device group.","title":"Device Group"}},"required":["product"],"title":"get_online_metricsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_event_metrics":{"post":{"operationId":"get_event_metrics","summary":"Count the events devices of a product published per time bucket. Use for \"How many events did my Particle fleet publish ","description":"Count the events devices of a product published per time bucket. Use for \"How many events did my Particle fleet publish per hour yesterday\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"product":{"description":"Product id (a number) or product slug, for example 'my-product'.","maxLength":80,"title":"Product","type":"string"},"start_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the period as ISO 8601, for example 2026-10-01T00:00:00.000Z (default: now).","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End of the period as ISO 8601 (default: now).","title":"End Date"},"bucket_size":{"anyOf":[{"maximum":2592000,"minimum":16,"type":"integer"},{"type":"null"}],"default":null,"description":"Seconds per time bucket; must be greater than 15 (default 900).","title":"Bucket Size"},"product_fw":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only devices running this product firmware version number.","title":"Product Fw"},"device_os_version":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only devices running this Device OS version, for example '5.8.0'.","title":"Device Os Version"},"device_group":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Only devices in this device group.","title":"Device Group"}},"required":["product"],"title":"get_event_metricsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_function_call_metrics":{"post":{"operationId":"get_function_call_metrics","summary":"Count Particle.function calls on product devices per time bucket by outcome: success, failure or offline. Use for \"How m","description":"Count Particle.function calls on product devices per time bucket by outcome: success, failure or offline. Use for \"How many function calls to my Particle devices failed yesterday\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"product":{"description":"Product id (a number) or product slug, for example 'my-product'.","maxLength":80,"title":"Product","type":"string"},"start_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the period as ISO 8601, for example 2026-10-01T00:00:00.000Z (default: now).","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End of the period as ISO 8601 (default: now).","title":"End Date"},"bucket_size":{"anyOf":[{"maximum":2592000,"minimum":16,"type":"integer"},{"type":"null"}],"default":null,"description":"Seconds per time bucket; must be greater than 15 (default 900).","title":"Bucket Size"},"product_fw":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only devices running this product firmware version number.","title":"Product Fw"},"device_os_version":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only devices running this Device OS version, for example '5.8.0'.","title":"Device Os Version"},"device_group":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Only devices in this device group.","title":"Device Group"}},"required":["product"],"title":"get_function_call_metricsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_variable_request_metrics":{"post":{"operationId":"get_variable_request_metrics","summary":"Count Particle.variable reads on product devices per time bucket by outcome: success, failure or offline. Use for \"How m","description":"Count Particle.variable reads on product devices per time bucket by outcome: success, failure or offline. Use for \"How many variable reads on my Particle devices found them offline yesterday\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"product":{"description":"Product id (a number) or product slug, for example 'my-product'.","maxLength":80,"title":"Product","type":"string"},"start_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the period as ISO 8601, for example 2026-10-01T00:00:00.000Z (default: now).","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End of the period as ISO 8601 (default: now).","title":"End Date"},"bucket_size":{"anyOf":[{"maximum":2592000,"minimum":16,"type":"integer"},{"type":"null"}],"default":null,"description":"Seconds per time bucket; must be greater than 15 (default 900).","title":"Bucket Size"},"product_fw":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only devices running this product firmware version number.","title":"Product Fw"},"device_os_version":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only devices running this Device OS version, for example '5.8.0'.","title":"Device Os Version"},"device_group":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Only devices in this device group.","title":"Device Group"}},"required":["product"],"title":"get_variable_request_metricsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_fleet_sim_usage":{"post":{"operationId":"get_fleet_sim_usage","summary":"Get the fleet-wide cellular data used by a product in the current billing period: total megabytes, active SIM count and ","description":"Get the fleet-wide cellular data used by a product in the current billing period: total megabytes, active SIM count and usage per day. Use for \"How much cellular data has my Particle fleet used this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"product":{"description":"Product id (a number) or product slug, for example 'my-product'.","maxLength":80,"title":"Product","type":"string"}},"required":["product"],"title":"get_fleet_sim_usageArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}