{"openapi":"3.1.0","info":{"title":"Particle (BYOK) API","version":"0.1.0","description":"Particle (BYOK) lets an AI assistant read your own Particle data through the Particle API with a key you supply (access token of a product team member (scopes devices:list, devices:get, groups:list, devices.variable:get, devices.function:call)). Read-only: 4 tools (list_product_devices, get_product_device, read_product_variable, list_device_groups). The BYOK key travels with each request, is used...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-particle-product-control.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-particle-product-control/docs"},"termsOfService":"https://connectorbay.com/byok-particle-product-control/terms"},"servers":[{"url":"https://byok-particle-product-control.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-particle-product-control/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_product_devices":{"post":{"operationId":"list_product_devices","summary":"List devices of a product fleet with optional filters and sorting. Needs a token with devices:list scope. Pages of 25 by","description":"List devices of a product fleet with optional filters and sorting. Needs a token with devices:list scope. Pages of 25 by default. Use for \"Which devices in my Particle product are running old firmware\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"product_id_or_slug":{"description":"Product ID (a number) or product slug.","maxLength":80,"title":"Product Id Or Slug","type":"string"},"device_name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Partial device name to match.","title":"Device Name"},"device_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Partial device ID to match.","title":"Device Id"},"groups":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated full device group names; only devices in these groups.","title":"Groups"},"sort_attr":{"anyOf":[{"enum":["deviceName","deviceId","firmwareVersion","lastConnection"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort by deviceName, deviceId, firmwareVersion or lastConnection.","title":"Sort Attr"},"sort_dir":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction: asc or desc.","title":"Sort Dir"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Records per page (default 25).","title":"Per Page"}},"required":["product_id_or_slug"],"title":"list_product_devicesArguments","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_device":{"post":{"operationId":"get_product_device","summary":"Get one device of a product fleet: firmware, desired firmware, groups, quarantine state, last contact and the names of t","description":"Get one device of a product fleet: firmware, desired firmware, groups, quarantine state, last contact and the names of the functions and variables it exposes. Needs devices:get scope. Use for \"Which functions does device 0123456789abcdef01234567 of my Particle product expose\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"product_id_or_slug":{"description":"Product ID (a number) or product slug.","maxLength":80,"title":"Product Id Or Slug","type":"string"},"device_id":{"description":"Particle device ID (24 hex characters) of a device in the product.","maxLength":200,"title":"Device Id","type":"string"}},"required":["product_id_or_slug","device_id"],"title":"get_product_deviceArguments","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/read_product_variable":{"post":{"operationId":"read_product_variable","summary":"Read the current value of one cloud variable of a product device (for example a temperature or counter). The device must","description":"Read the current value of one cloud variable of a product device (for example a temperature or counter). The device must be online. Use for \"What is the temperature variable of device 0123456789abcdef01234567 in my Particle product\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"product_id_or_slug":{"description":"Product ID (a number) or product slug.","maxLength":80,"title":"Product Id Or Slug","type":"string"},"device_id":{"description":"Particle device ID (24 hex characters) of a device in the product.","maxLength":200,"title":"Device Id","type":"string"},"variable_name":{"description":"Name of a cloud variable the device firmware exposes, for example temperature.","maxLength":64,"title":"Variable Name","type":"string"}},"required":["product_id_or_slug","device_id","variable_name"],"title":"read_product_variableArguments","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_device_groups":{"post":{"operationId":"list_device_groups","summary":"List the device groups of a product (name, description, firmware version, color), optionally filtered by part of the nam","description":"List the device groups of a product (name, description, firmware version, color), optionally filtered by part of the name. Use for \"Which device groups does my Particle product have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"product_id_or_slug":{"description":"Product ID (a number) or product slug.","maxLength":80,"title":"Product Id Or Slug","type":"string"},"name":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Part of a group name to filter by.","title":"Name"}},"required":["product_id_or_slug"],"title":"list_device_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}}}}