List environment variables for an organization, Sandbox, product, or device.
", + "group": "Env.1", + "permission": [ + { + "name": "env:list" + } + ], + "examples": [ + { + "title": "List Sandbox environment variables", + "content": "$ curl https://api.particle.io/v1/env \\\n -H \"Authorization: Bearer :access_token\"", + "type": "bash" + }, + { + "title": "List organization environment variables", + "content": "$ curl https://api.particle.io/v1/orgs/:orgIdOrSlug/env \\\n -H \"Authorization: Bearer :access_token\"", + "type": "bash" + }, + { + "title": "List product environment variables", + "content": "$ curl https://api.particle.io/v1/products/:productIdOrSlug/env \\\n -H \"Authorization: Bearer :access_token\"", + "type": "bash" + }, + { + "title": "List product device environment variables", + "content": "$ curl https://api.particle.io/v1/products/:productIdOrSlug/env/:deviceId \\\n -H \"Authorization: Bearer :access_token\"", + "type": "bash" + }, + { + "title": "List device environment variables for any device your account has access to.", + "content": "$ curl https://api.particle.io/v1/env/:deviceId \\\n -H \"Authorization: Bearer :access_token\"", + "type": "bash" + } + ], + "success": { + "fields": { + "Success 200": [ + { + "group": "Success 200", + "type": "Object", + "optional": true, + "field": "on_device", + "isArray": false, + "description": "Current state of environment variables on the device. Only present for device scope. May be null if the device has never reported its environment variables.
Flat key-value map of the actual environment variables currently on the device.
" + }, + { + "group": "Success 200", + "type": "String", + "optional": false, + "parentNode": { + "path": "on_device", + "field": "on_device", + "type": "Object", + "isArray": false + }, + "field": "on_device.last_reported_at", + "isArray": false, + "description": "ISO 8601 timestamp of when the device last reported its environment variables.
" + }, + { + "group": "Success 200", + "type": "Boolean", + "optional": true, + "parentNode": { + "path": "on_device", + "field": "on_device", + "type": "Object", + "isArray": false + }, + "field": "on_device.development_env", + "isArray": false, + "description": "If true, the device is running custom firmware with environment variables that don't match any product firmware.
The last rolled out environment variables. May be null if no rollout has occurred.
Environment variables defined at this scope level at the time of the last rollout. Keys are variable names, values are objects with a value property.
Environment variables inherited from parent scopes at the time of the last rollout. Only present for product and device scopes. Keys are variable names, values are objects with from and value properties.
The scope where the inherited variable is defined (Owner, Product, Firmware).
The value of the inherited variable.
" + }, + { + "group": "Success 200", + "type": "String", + "optional": false, + "parentNode": { + "path": "last_snapshot", + "field": "last_snapshot", + "type": "Object", + "isArray": false + }, + "field": "last_snapshot.rollout_at", + "isArray": false, + "description": "ISO 8601 timestamp of when the last rollout occurred. May be null.
User ID of the user who initiated the last rollout. May be null.
The latest values of the environment variables. All changes may not be rolled out yet. Contains own and optionally inherited properties.
Environment variables defined at this scope level. Keys are variable names, values are objects with a value property.
Environment variables inherited from parent scopes (product or owner). Only present for product and device scopes. Keys are variable names, values are objects with from and value properties.
The scope where the inherited variable is defined (Owner, Product, Firmware).
The value of the inherited variable.
" + }, + { + "group": "Success 200", + "type": "String", + "optional": false, + "parentNode": { + "path": "latest", + "field": "latest", + "type": "Object", + "isArray": false + }, + "field": "latest.created_at", + "isArray": false, + "description": "ISO 8601 timestamp of when the environment variables were first created at this scope. May be null.
ISO 8601 timestamp of when the environment variables were last updated at this scope. May be null.
User ID of the user who created the environment variables at this scope. May be null.
User ID of the user who last updated the environment variables at this scope. May be null.
Create or update a single environment variable for an organization, Sandbox, product, or device.
", + "group": "Env.2", + "permission": [ + { + "name": "env:update" + } + ], + "parameter": { + "fields": { + "Parameter": [ + { + "group": "Parameter", + "type": "String", + "optional": false, + "field": "key", + "isArray": false, + "description": "Environment variable name.
" + } + ] + } + }, + "examples": [ + { + "title": "Set Sandbox environment variable", + "content": "$ curl -X PUT https://api.particle.io/v1/env/MY_KEY \\\n -H \"Authorization: Bearer :access_token\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"value\": \"my_value\" }'", + "type": "bash" + }, + { + "title": "Set organization environment variable", + "content": "$ curl -X PUT https://api.particle.io/v1/orgs/:orgIdOrSlug/env/MY_KEY \\\n -H \"Authorization: Bearer :access_token\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"value\": \"my_value\" }'", + "type": "bash" + }, + { + "title": "Set product environment variable", + "content": "$ curl -X PUT https://api.particle.io/v1/products/:productIdOrSlug/env/MY_KEY \\\n -H \"Authorization: Bearer :access_token\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"value\": \"my_value\" }'", + "type": "bash" + }, + { + "title": "Set product device environment variable", + "content": "$ curl -X PUT https://api.particle.io/v1/products/:productIdOrSlug/env/:deviceId/MY_KEY \\\n -H \"Authorization: Bearer :access_token\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"value\": \"my_value\" }'", + "type": "bash" + }, + { + "title": "Set device environment variable for any device your account has access to", + "content": "$ curl -X PUT https://api.particle.io/v1/env/:deviceId/MY_KEY \\\n -H \"Authorization: Bearer :access_token\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"value\": \"my_value\" }'", + "type": "bash" + } + ], + "body": [ + { + "group": "Body", + "type": "String", + "optional": false, + "field": "value", + "isArray": false, + "description": "The value to set for the environment variable.
" + } + ], + "success": { + "fields": { + "Success 200": [ + { + "group": "Success 200", + "type": "Object", + "optional": false, + "field": "-", + "isArray": false, + "description": "Updated environment variables. See List environment variables for the response attributes.
" + } + ] + } + }, + "version": "0.0.0", + "filename": "src/views/env.js", + "groupTitle": "Env.2" + }, + { + "type": "delete", + "url": "/v1/env/:key", + "title": "Delete environment variable", + "name": "deleteEnv", + "description": "Delete a single environment variable for an organization, Sandbox, product, or device.
", + "group": "Env.3", + "permission": [ + { + "name": "env:update" + } + ], + "parameter": { + "fields": { + "Parameter": [ + { + "group": "Parameter", + "type": "String", + "optional": false, + "field": "key", + "isArray": false, + "description": "Environment variable name.
" + } + ] + } + }, + "examples": [ + { + "title": "Delete Sandbox environment variable", + "content": "$ curl -X DELETE https://api.particle.io/v1/env/MY_KEY \\\n -H \"Authorization: Bearer :access_token\"", + "type": "bash" + }, + { + "title": "Delete organization environment variable", + "content": "$ curl -X DELETE https://api.particle.io/v1/orgs/:orgIdOrSlug/env/MY_KEY \\\n -H \"Authorization: Bearer :access_token\"", + "type": "bash" + }, + { + "title": "Delete product environment variable", + "content": "$ curl -X DELETE https://api.particle.io/v1/products/:productIdOrSlug/env/MY_KEY \\\n -H \"Authorization: Bearer :access_token\"", + "type": "bash" + }, + { + "title": "Delete product device environment variable", + "content": "$ curl -X DELETE https://api.particle.io/v1/products/:productIdOrSlug/env/:deviceId/MY_KEY \\\n -H \"Authorization: Bearer :access_token\"", + "type": "bash" + }, + { + "title": "Delete device environment variable for any device your account has access to", + "content": "$ curl -X DELETE https://api.particle.io/v1/env/:deviceId/MY_KEY \\\n -H \"Authorization: Bearer :access_token\"", + "type": "bash" + } + ], + "success": { + "fields": { + "Success 200": [ + { + "group": "Success 200", + "type": "Object", + "optional": false, + "field": "-", + "isArray": false, + "description": "Updated environment variables. See List environment variables for the response attributes.
" + } + ] + } + }, + "version": "0.0.0", + "filename": "src/views/env.js", + "groupTitle": "Env.3" + }, + { + "type": "patch", + "url": "/v1/env", + "title": "Bulk update environment variables", + "name": "patchEnv", + "description": "Apply multiple changes to environment variables for an organization, Sandbox, product, or device in a single request.
", + "group": "Env.4", + "permission": [ + { + "name": "env:update" + } + ], + "examples": [ + { + "title": "Update Sandbox/organization environment variables", + "content": "$ curl -X PATCH https://api.particle.io/v1/env \\\n -H \"Authorization: Bearer :access_token\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"ops\": [{ \"op\": \"Set\", \"key\": \"DATA\", \"value\": \"odata\" }] }'", + "type": "bash" + }, + { + "title": "Update organization environment variables", + "content": "$ curl -X PATCH https://api.particle.io/v1/orgs/:orgIdOrSlug/env \\\n -H \"Authorization: Bearer :access_token\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"ops\": [{ \"op\": \"Set\", \"key\": \"GLOBAL_DATA\", \"value\": \"toall\" }] }'", + "type": "bash" + }, + { + "title": "Update product environment variables", + "content": "$ curl -X PATCH https://api.particle.io/v1/products/:productIdOrSlug/env \\\n -H \"Authorization: Bearer :access_token\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"ops\": [{ \"op\": \"Set\", \"key\": \"DATA\", \"value\": \"pdata\" }] }'", + "type": "bash" + }, + { + "title": "Update product device environment variables", + "content": "$ curl -X PATCH https://api.particle.io/v1/products/:productIdOrSlug/env/:deviceId \\\n -H \"Authorization: Bearer :access_token\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"ops\": [{ \"op\": \"Set\", \"key\": \"DATA\", \"value\": \"ddata\" }] }'", + "type": "bash" + }, + { + "title": "Update device environment variables for any product device you can access", + "content": "$ curl -X PATCH https://api.particle.io/v1/env/:deviceId \\\n -H \"Authorization: Bearer :access_token\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"ops\": [{ \"op\": \"Set\", \"key\": \"DATA\", \"value\": \"ddata\" }] }'", + "type": "bash" + }, + { + "title": "Request format", + "content": "{\n \"ops\": [\n { \"op\": \"Set\", \"key\": \"SOME_KEY\", \"value\": \"some value\" },\n { \"op\": \"Unset\", \"key\": \"OLD_KEY\" }\n ]\n}", + "type": "json" + } + ], + "body": [ + { + "group": "Body", + "type": "Object[]", + "optional": false, + "field": "ops", + "isArray": true, + "description": "List of change operations to apply (max 50 operations).
" + }, + { + "group": "Body", + "type": "String", + "allowedValues": [ + "\"Set\"", + "\"Unset\"" + ], + "optional": false, + "parentNode": { + "path": "ops", + "field": "ops", + "type": "Object[]", + "isArray": true + }, + "field": "ops.op", + "isArray": false, + "description": "Operation type.
Set: Create or update an environment variable at this scope.Unset: Delete an environment variable at this scope.Environment variable name.
" + }, + { + "group": "Body", + "type": "String", + "optional": true, + "parentNode": { + "path": "ops", + "field": "ops", + "type": "Object[]", + "isArray": true + }, + "field": "ops.value", + "isArray": false, + "description": "The value to set. Required when op is Set.
Updated environment variables. See List environment variables for the response attributes.
" + } + ] + } + }, + "version": "0.0.0", + "filename": "src/views/env.js", + "groupTitle": "Env.4" + }, + { + "type": "get", + "url": "/v1/env/render", + "title": "Render environment variables", + "name": "renderEnv", + "description": "Render environment variables for an organization, Sandbox, product, or device. The response is a flat key/value map of the effective variables after inheritance and overrides are applied.
", + "group": "Env.5", + "permission": [ + { + "name": "env:list" + } + ], + "examples": [ + { + "title": "Render Sandbox environment variables", + "content": "$ curl https://api.particle.io/v1/env/render \\\n -H \"Authorization: Bearer :access_token\"", + "type": "bash" + }, + { + "title": "Render organization environment variables", + "content": "$ curl https://api.particle.io/v1/orgs/:orgIdOrSlug/env/render \\\n -H \"Authorization: Bearer :access_token\"", + "type": "bash" + }, + { + "title": "Render product environment variables", + "content": "$ curl https://api.particle.io/v1/products/:productIdOrSlug/env/render \\\n -H \"Authorization: Bearer :access_token\"", + "type": "bash" + }, + { + "title": "Render product device environment variables", + "content": "$ curl https://api.particle.io/v1/products/:productIdOrSlug/env/:deviceId/render \\\n -H \"Authorization: Bearer :access_token\"", + "type": "bash" + }, + { + "title": "Render device environment variables for any device your account has access to.", + "content": "$ curl https://api.particle.io/v1/env/:deviceId/render \\\n -H \"Authorization: Bearer :access_token\"", + "type": "bash" + } + ], + "success": { + "fields": { + "Success 200": [ + { + "group": "Success 200", + "type": "Object", + "optional": false, + "field": "env", + "isArray": false, + "description": "Flat key-value map of the effective environment variables after inheritance and overrides are applied.
" + }, + { + "group": "Success 200", + "type": "String", + "optional": false, + "field": "last_updated_at", + "isArray": false, + "description": "ISO 8601 timestamp of when the environment variables were last updated at this scope. May be null.
ISO 8601 timestamp of when the last rollout occurred. May be null.
User ID of the user who initiated the last rollout. May be null.
Review changes that can be rolled out
", + "group": "Env.6", + "permission": [ + { + "name": "env:rollout" + } + ], + "examples": [ + { + "title": "Review environment variables rollout for a Sandbox", + "content": "$ curl https://api.particle.io/v1/env/rollout \\\n -H \"Authorization: Bearer :access_token\"", + "type": "bash" + }, + { + "title": "Review environment variables rollout for an organization", + "content": "$ curl https://api.particle.io/v1/orgs/:orgIdOrSlug/env/rollout \\\n -H \"Authorization: Bearer :access_token\"", + "type": "bash" + }, + { + "title": "Review environment variables rollout for a product", + "content": "$ curl https://api.particle.io/v1/products/:productIdOrSlug/env/rollout \\\n -H \"Authorization: Bearer :access_token\"", + "type": "bash" + }, + { + "title": "Review environment variables rollout for a device", + "content": "$ curl https://api.particle.io/v1/env/:deviceId/rollout \\\n -H \"Authorization: Bearer :access_token\"", + "type": "bash" + } + ], + "success": { + "fields": { + "Success 200": [ + { + "group": "Success 200", + "type": "Object", + "optional": false, + "field": "from_snapshot", + "isArray": false, + "description": "Changes compared to the last rolled out snapshot.
" + }, + { + "group": "Success 200", + "type": "Object[]", + "optional": false, + "parentNode": { + "path": "from_snapshot", + "field": "from_snapshot", + "type": "Object", + "isArray": false + }, + "field": "from_snapshot.changes", + "isArray": true, + "description": "List of changes to environment variables.
" + }, + { + "group": "Success 200", + "type": "String", + "allowedValues": [ + "\"Added\"", + "\"Changed\"", + "\"Removed\"" + ], + "optional": false, + "parentNode": { + "path": "from_snapshot.changes", + "parentNode": { + "path": "from_snapshot", + "field": "from_snapshot", + "type": "Object", + "isArray": false + }, + "field": "from_snapshot.changes", + "type": "Object[]", + "isArray": true + }, + "field": "from_snapshot.changes.op", + "isArray": false, + "description": "Type of change.
" + }, + { + "group": "Success 200", + "type": "String", + "optional": false, + "parentNode": { + "path": "from_snapshot.changes", + "parentNode": { + "path": "from_snapshot", + "field": "from_snapshot", + "type": "Object", + "isArray": false + }, + "field": "from_snapshot.changes", + "type": "Object[]", + "isArray": true + }, + "field": "from_snapshot.changes.key", + "isArray": false, + "description": "Name of the environment variable.
" + }, + { + "group": "Success 200", + "type": "String", + "optional": true, + "parentNode": { + "path": "from_snapshot.changes", + "parentNode": { + "path": "from_snapshot", + "field": "from_snapshot", + "type": "Object", + "isArray": false + }, + "field": "from_snapshot.changes", + "type": "Object[]", + "isArray": true + }, + "field": "from_snapshot.changes.before", + "isArray": false, + "description": "Previous value. Present when op is Changed or Removed.
New value. Present when op is Changed or Added.
Map of unchanged environment variables (key to value).
" + }, + { + "group": "Success 200", + "type": "Object", + "optional": true, + "field": "from_device", + "isArray": false, + "description": "Changes compared to what is currently on the device. Only present for device scope.
" + }, + { + "group": "Success 200", + "type": "Object[]", + "optional": false, + "parentNode": { + "path": "from_device", + "field": "from_device", + "type": "Object", + "isArray": false + }, + "field": "from_device.changes", + "isArray": true, + "description": "List of changes to environment variables.
" + }, + { + "group": "Success 200", + "type": "String", + "allowedValues": [ + "\"Added\"", + "\"Changed\"", + "\"Removed\"" + ], + "optional": false, + "parentNode": { + "path": "from_device.changes", + "parentNode": { + "path": "from_device", + "field": "from_device", + "type": "Object", + "isArray": false + }, + "field": "from_device.changes", + "type": "Object[]", + "isArray": true + }, + "field": "from_device.changes.op", + "isArray": false, + "description": "Type of change.
" + }, + { + "group": "Success 200", + "type": "String", + "optional": false, + "parentNode": { + "path": "from_device.changes", + "parentNode": { + "path": "from_device", + "field": "from_device", + "type": "Object", + "isArray": false + }, + "field": "from_device.changes", + "type": "Object[]", + "isArray": true + }, + "field": "from_device.changes.key", + "isArray": false, + "description": "Name of the environment variable.
" + }, + { + "group": "Success 200", + "type": "String", + "optional": true, + "parentNode": { + "path": "from_device.changes", + "parentNode": { + "path": "from_device", + "field": "from_device", + "type": "Object", + "isArray": false + }, + "field": "from_device.changes", + "type": "Object[]", + "isArray": true + }, + "field": "from_device.changes.before", + "isArray": false, + "description": "Previous value. Present when op is Changed or Removed.
New value. Present when op is Changed or Added.
Map of unchanged environment variables (key to value).
" + } + ] + }, + "examples": [ + { + "title": "Owner/Product response", + "content": "HTTP/1.1 200 OK\n{\n \"from_snapshot\": {\n \"changes\": [\n { \"op\": \"Added\", \"key\": \"MY_DATA\", \"after\": \"wowza!\" },\n { \"op\": \"Removed\", \"key\": \"ANOTHER_ONE\", \"before\": \"woahza!\" },\n { \"op\": \"Changed\", \"key\": \"THING_NUMBER_THREE\", \"before\": \"previous\", \"after\": \"postvious\" }\n ],\n \"unchanged\": {\n \"DATA\": \"yes\",\n \"OTHER\": \"also yes\"\n }\n }\n}", + "type": "json" + }, + { + "title": "Device response", + "content": "HTTP/1.1 200 OK\n{\n \"from_device\": {\n \"changes\": [\n { \"op\": \"Added\", \"key\": \"MY_DATA\", \"after\": \"wowza!\" },\n { \"op\": \"Removed\", \"key\": \"ANOTHER_ONE\", \"before\": \"woahza!\" },\n { \"op\": \"Changed\", \"key\": \"THING_NUMBER_THREE\", \"before\": \"previous\", \"after\": \"postvious\" }\n ],\n \"unchanged\": {\n \"DATA\": \"yes\",\n \"OTHER\": \"also yes\"\n }\n },\n \"from_snapshot\": {\n \"changes\": [\n { \"op\": \"Added\", \"key\": \"MY_DATA\", \"after\": \"wowza!\" },\n { \"op\": \"Removed\", \"key\": \"ANOTHER_ONE\", \"before\": \"woahza!\" },\n { \"op\": \"Changed\", \"key\": \"THING_NUMBER_THREE\", \"before\": \"previous\", \"after\": \"postvious\" }\n ],\n \"unchanged\": {\n \"DATA\": \"yes\",\n \"OTHER\": \"also yes\"\n }\n }\n}", + "type": "json" + } + ] + }, + "version": "0.0.0", + "filename": "src/views/env.js", + "groupTitle": "Env.6" + }, + { + "type": "post", + "url": "/v1/env/rollout", + "title": "Start environment variables rollout", + "name": "startEnvRollout", + "description": "Apply updated environment variable values and make them available to devices.
When rolling out immediately, devices that are currently available to receive OTA updates will receive updated environment variables. Devices that are busy or offline will apply the update when they become ready. When rolling out on next connection, as devices handshake (begin new secure sessions) with the Device Cloud, they will receive updated environment variables.
", + "group": "Env.7", + "permission": [ + { + "name": "env:rollout" + } + ], + "body": [ + { + "group": "Body", + "type": "String", + "allowedValues": [ + "\"Immediate\"", + "\"Connect\"" + ], + "optional": false, + "field": "when", + "isArray": false, + "description": "Rollout timing.
" + } + ], + "examples": [ + { + "title": "Start environment variables rollout for a Sandbox", + "content": "$ curl -X POST https://api.particle.io/v1/env/rollout \\\n -H \"Authorization: Bearer :access_token\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"when\": \"Immediate\" }'", + "type": "bash" + }, + { + "title": "Start environment variables rollout for an organization", + "content": "$ curl -X POST https://api.particle.io/v1/orgs/:orgIdOrSlug/env/rollout \\\n -H \"Authorization: Bearer :access_token\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"when\": \"Immediate\" }'", + "type": "bash" + }, + { + "title": "Start environment variables rollout for a product", + "content": "$ curl -X POST https://api.particle.io/v1/products/:productIdOrSlug/env/rollout \\\n -H \"Authorization: Bearer :access_token\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"when\": \"Immediate\" }'", + "type": "bash" + }, + { + "title": "Start environment variables rollout for a device", + "content": "$ curl -X POST https://api.particle.io/v1/env/:deviceId/rollout \\\n -H \"Authorization: Bearer :access_token\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"when\": \"Immediate\" }'", + "type": "bash" + } + ], + "success": { + "fields": { + "Success 200": [ + { + "group": "Success 200", + "type": "Boolean", + "optional": false, + "field": "success", + "isArray": false, + "description": "Indicates if the rollout was successful.
" + } + ] + }, + "examples": [ + { + "title": "Response", + "content": "HTTP/1.1 201 Created\n{\n \"success\": true\n}", + "type": "json" + } + ] + }, + "version": "0.0.0", + "filename": "src/views/env.js", + "groupTitle": "Env.7" + }, { "type": "get", "url": "/v1/events/:eventPrefix", @@ -8735,6 +9816,15 @@ "field": "secrets", "isArray": false, "description": "An array of Cloud secrets to use with the webhook. Each element needs a name property and can have an optional template_name property. Insert the value into the webhook using {{{SECRET_NAME}}} where SECRET_NAME is the template_name or name if template_name is omitted.
Set to true to include environment variables in the webhook. Insert the value into the webhook using {{{ENV_VAR_NAME}}}
The template that was used to create this webhook
" + }, + { + "group": "Body", + "type": "Boolean", + "optional": true, + "field": "use_env", + "isArray": false, + "description": "Set to true to include environment variables in the webhook. Insert the value into the webhook using {{{ENV_VAR_NAME}}}
Update the value of a cloud secret in the Sandbox or organization.
", + "title": "Create or Update the value of a cloud secret", + "name": "putSecret", + "description": "Creates or Updates the value of a cloud secret in the Sandbox or organization.
", "group": "Secrets.4", "permission": [ { @@ -14567,11 +15666,22 @@ "name": "getServiceAgreements", "description": "Get the service agreements related to a user
", "group": "ServiceAgreements.1", + "query": [ + { + "group": "Query", + "type": "Boolean", + "optional": true, + "field": "include_usage_summary", + "isArray": false, + "defaultValue": "true", + "description": "Set to false to exclude current_usage_summary from the response. Defaults to true. Requires service_agreements.usage_summary:get scope.
Set to false to exclude current_usage_summary from the response. Defaults to true. Requires service_agreements.usage_summary:get scope.
Email address for current user
" }, - { - "group": "Success 200", - "type": "Array", - "optional": false, - "field": "subscription_ids", - "isArray": false, - "description": "Subscriptions for SIM cards and products
" - }, { "group": "Success 200", "type": "Object", @@ -17946,7 +19059,7 @@ "examples": [ { "title": "GET /v1/user", - "content": "GET /v1/user\nHTTP/1.1 200 OK\n{\n \"username\": \"testuser@particle.io\",\n \"subscription_ids\": [],\n \"account_info\": {\n \"first_name\": \"Test\",\n \"last_name\": \"User\",\n \"business_account\": false\n },\n scim_provisioned: false,\n no_password: false,\n \"mfa\": {\n \"enabled\": false\n },\n \"wifi_device_count\": 0,\n \"cellular_device_count\": 0\n}", + "content": "GET /v1/user\nHTTP/1.1 200 OK\n{\n \"username\": \"testuser@particle.io\",\n \"account_info\": {\n \"first_name\": \"Test\",\n \"last_name\": \"User\",\n \"business_account\": false\n },\n scim_provisioned: false,\n no_password: false,\n \"mfa\": {\n \"enabled\": false\n },\n \"wifi_device_count\": 0,\n \"cellular_device_count\": 0\n}", "type": "json" } ] diff --git a/generated/particle_api.postman_collection.json b/generated/particle_api.postman_collection.json index c539dd07b2..0c9dcc5209 100644 --- a/generated/particle_api.postman_collection.json +++ b/generated/particle_api.postman_collection.json @@ -134,7 +134,7 @@ }, { "key": "expires_at", - "value": "2025-09-15T10:16:52.412Z", + "value": "2026-02-23T09:26:11.698Z", "disabled": true } ] @@ -199,7 +199,7 @@ }, { "key": "expires_at", - "value": "2025-09-15T10:16:52.415Z", + "value": "2026-02-23T09:26:11.700Z", "disabled": true } ] @@ -1596,7 +1596,7 @@ }, { "key": "expires_at", - "value": "2025-09-15T10:16:52.428Z", + "value": "2026-02-23T09:26:11.720Z", "disabled": true }, { @@ -1656,7 +1656,7 @@ }, { "key": "expires_at", - "value": "2025-09-15T10:16:52.428Z", + "value": "2026-02-23T09:26:11.721Z", "disabled": true }, { @@ -3210,13 +3210,13 @@ "query": [ { "key": "start_date", - "value": "2025-09-15T10:16:52.437Z", + "value": "2026-02-23T09:26:11.733Z", "description": "Oldest diagnostic to return, inclusive. Date in ISO8601 format.", "disabled": true }, { "key": "end_date", - "value": "2025-09-15T10:16:52.437Z", + "value": "2026-02-23T09:26:11.733Z", "description": "Newest diagnostic to return, exclusive. Date in ISO8601 format.", "disabled": true } @@ -3428,6 +3428,457 @@ } ] }, + { + "name": "Env", + "item": [ + { + "name": "List environment variables", + "request": { + "auth": null, + "method": "GET", + "header": [], + "body": null, + "url": { + "raw": "{{url}}/v1/env", + "host": [ + "{{url}}" + ], + "path": [ + "v1", + "env" + ], + "query": [], + "variables": [] + }, + "description": "List environment variables for an organization, Sandbox, product, or device." + }, + "response": [ + { + "name": "Response", + "originalRequest": { + "method": "GET", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + } + ], + "body": null, + "url": { + "raw": "{{url}}/v1/env", + "host": [ + "{{url}}" + ], + "path": [ + "v1", + "env" + ] + } + }, + "status": "OK", + "code": "200", + "_postman_previewlanguage": "json", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + } + ], + "body": "HTTP/1.1 200 OK\n{\n \"last_snapshot\": {\n \"own\": {\n \"DATA\": { \"value\": \"odata\" },\n \"GLOBAL_DATA\": { \"value\": \"toall\" }\n },\n \"rollout_at\": \"2025-12-19T21:34:29.671Z\",\n \"rollout_by\": \"some-user-id\"\n },\n \"latest\": {\n \"own\": {\n \"DATA\": { \"value\": \"odata\" },\n \"GLOBAL_DATA\": { \"value\": \"toall\" }\n }\n }\n}" + }, + { + "name": "Response", + "originalRequest": { + "method": "GET", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + } + ], + "body": null, + "url": { + "raw": "{{url}}/v1/env", + "host": [ + "{{url}}" + ], + "path": [ + "v1", + "env" + ] + } + }, + "status": "OK", + "code": "200", + "_postman_previewlanguage": "json", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + } + ], + "body": "HTTP/1.1 200 OK\n{\n \"last_snapshot\": {\n \"inherited\": {\n \"DATA\": { \"from\": \"Owner\", \"value\": \"odata\" },\n \"GLOBAL_DATA\": { \"from\": \"Owner\", \"value\": \"toall\" }\n },\n \"own\": {\n \"DATA\": { \"value\": \"pdata\" }\n },\n \"rollout_at\": \"2025-12-19T21:34:29.671Z\",\n \"rollout_by\": \"some-user-id\"\n },\n \"latest\": {\n \"inherited\": {\n \"DATA\": { \"from\": \"Owner\", \"value\": \"odata\" },\n \"GLOBAL_DATA\": { \"from\": \"Owner\", \"value\": \"toall\" }\n },\n \"own\": {\n \"DATA\": { \"value\": \"pdata\" }\n }\n }\n}" + }, + { + "name": "Response", + "originalRequest": { + "method": "GET", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + } + ], + "body": null, + "url": { + "raw": "{{url}}/v1/env", + "host": [ + "{{url}}" + ], + "path": [ + "v1", + "env" + ] + } + }, + "status": "OK", + "code": "200", + "_postman_previewlanguage": "json", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + } + ], + "body": "HTTP/1.1 200 OK\n{\n \"on_device\": {\n \"rendered\": {\n \"SOME_DATA_ON_MY_DEVICE\": \"yay!\"\n },\n \"last_reported_at\": \"2025-12-19T21:34:29.671Z\"\n },\n \"last_snapshot\": {\n \"inherited\": {\n \"DATA\": { \"from\": \"Product\", \"value\": \"pdata\" },\n \"GLOBAL_DATA\": { \"from\": \"Owner\", \"value\": \"toall\" }\n },\n \"own\": {\n \"DATA\": { \"value\": \"ddata\" }\n },\n \"rollout_at\": \"2025-12-19T21:34:29.671Z\",\n \"rollout_by\": \"some-user-id\"\n },\n \"latest\": {\n \"inherited\": {\n \"DATA\": { \"from\": \"Product\", \"value\": \"pdata\" },\n \"GLOBAL_DATA\": { \"from\": \"Owner\", \"value\": \"toall\" }\n },\n \"own\": {\n \"DATA\": { \"value\": \"ddata\" }\n }\n }\n}" + } + ] + }, + { + "name": "Render environment variables", + "request": { + "auth": null, + "method": "GET", + "header": [], + "body": null, + "url": { + "raw": "{{url}}/v1/env/render", + "host": [ + "{{url}}" + ], + "path": [ + "v1", + "env", + "render" + ], + "query": [], + "variables": [] + }, + "description": "Render environment variables for an organization, Sandbox, product, or device. The response is a flat key/value map of the effective variables after inheritance and overrides are applied." + }, + "response": [ + { + "name": "Response", + "originalRequest": { + "method": "GET", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + } + ], + "body": null, + "url": { + "raw": "{{url}}/v1/env/render", + "host": [ + "{{url}}" + ], + "path": [ + "v1", + "env", + "render" + ] + } + }, + "status": "OK", + "code": "200", + "_postman_previewlanguage": "json", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + } + ], + "body": "HTTP/1.1 200 OK\n{\n \"env\": {\n \"DATA\": \"value\",\n \"GLOBAL_DATA\": \"toall\",\n \"SOMETHING_ELSE\": \"something\"\n },\n \"last_updated_at\": \"2025-12-19T21:34:29.671Z\",\n \"rollout_at\": \"2025-12-19T21:34:29.671Z\",\n \"rollout_by\": \"some-user-id\"\n}" + } + ] + }, + { + "name": "Review environment variables rollout", + "request": { + "auth": null, + "method": "GET", + "header": [], + "body": null, + "url": { + "raw": "{{url}}/v1/env/rollout", + "host": [ + "{{url}}" + ], + "path": [ + "v1", + "env", + "rollout" + ], + "query": [], + "variables": [] + }, + "description": "Review changes that can be rolled out" + }, + "response": [ + { + "name": "Response", + "originalRequest": { + "method": "GET", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + } + ], + "body": null, + "url": { + "raw": "{{url}}/v1/env/rollout", + "host": [ + "{{url}}" + ], + "path": [ + "v1", + "env", + "rollout" + ] + } + }, + "status": "OK", + "code": "200", + "_postman_previewlanguage": "json", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + } + ], + "body": "HTTP/1.1 200 OK\n{\n \"from_snapshot\": {\n \"changes\": [\n { \"op\": \"Added\", \"key\": \"MY_DATA\", \"after\": \"wowza!\" },\n { \"op\": \"Removed\", \"key\": \"ANOTHER_ONE\", \"before\": \"woahza!\" },\n { \"op\": \"Changed\", \"key\": \"THING_NUMBER_THREE\", \"before\": \"previous\", \"after\": \"postvious\" }\n ],\n \"unchanged\": {\n \"DATA\": \"yes\",\n \"OTHER\": \"also yes\"\n }\n }\n}" + }, + { + "name": "Response", + "originalRequest": { + "method": "GET", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + } + ], + "body": null, + "url": { + "raw": "{{url}}/v1/env/rollout", + "host": [ + "{{url}}" + ], + "path": [ + "v1", + "env", + "rollout" + ] + } + }, + "status": "OK", + "code": "200", + "_postman_previewlanguage": "json", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + } + ], + "body": "HTTP/1.1 200 OK\n{\n \"from_device\": {\n \"changes\": [\n { \"op\": \"Added\", \"key\": \"MY_DATA\", \"after\": \"wowza!\" },\n { \"op\": \"Removed\", \"key\": \"ANOTHER_ONE\", \"before\": \"woahza!\" },\n { \"op\": \"Changed\", \"key\": \"THING_NUMBER_THREE\", \"before\": \"previous\", \"after\": \"postvious\" }\n ],\n \"unchanged\": {\n \"DATA\": \"yes\",\n \"OTHER\": \"also yes\"\n }\n },\n \"from_snapshot\": {\n \"changes\": [\n { \"op\": \"Added\", \"key\": \"MY_DATA\", \"after\": \"wowza!\" },\n { \"op\": \"Removed\", \"key\": \"ANOTHER_ONE\", \"before\": \"woahza!\" },\n { \"op\": \"Changed\", \"key\": \"THING_NUMBER_THREE\", \"before\": \"previous\", \"after\": \"postvious\" }\n ],\n \"unchanged\": {\n \"DATA\": \"yes\",\n \"OTHER\": \"also yes\"\n }\n }\n}" + } + ] + }, + { + "name": "Start environment variables rollout", + "request": { + "auth": null, + "method": "POST", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + } + ], + "body": { + "mode": "raw", + "raw": "{\n \"when\": \"string\"\n}" + }, + "url": { + "raw": "{{url}}/v1/env/rollout", + "host": [ + "{{url}}" + ], + "path": [ + "v1", + "env", + "rollout" + ], + "query": [], + "variables": [] + }, + "description": "Apply updated environment variable values and make them available to devices. \n\nWhen rolling out immediately, devices that are currently available to receive OTA updates will receive updated environment variables. Devices that are busy or offline will apply the update when they become ready. When rolling out on next connection, as devices handshake (begin new secure sessions) with the Device Cloud, they will receive updated environment variables." + }, + "response": [ + { + "name": "Response", + "originalRequest": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + } + ], + "body": { + "mode": "raw", + "raw": "{\n \"when\": \"string\"\n}" + }, + "url": { + "raw": "{{url}}/v1/env/rollout", + "host": [ + "{{url}}" + ], + "path": [ + "v1", + "env", + "rollout" + ] + } + }, + "status": "OK", + "code": "200", + "_postman_previewlanguage": "json", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + } + ], + "body": "HTTP/1.1 201 Created\n{\n \"success\": true\n}" + } + ] + }, + { + "name": "Set environment variable", + "request": { + "auth": null, + "method": "PUT", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + } + ], + "body": { + "mode": "raw", + "raw": "{\n \"value\": \"string\"\n}" + }, + "url": { + "raw": "{{url}}/v1/env/:key", + "host": [ + "{{url}}" + ], + "path": [ + "v1", + "env", + ":key" + ], + "query": [], + "variables": [ + { + "key": "key", + "value": "string", + "description": "Environment variable name.", + "disabled": false + } + ] + }, + "description": "Create or update a single environment variable for an organization, Sandbox, product, or device." + }, + "response": [] + }, + { + "name": "Bulk update environment variables", + "request": { + "auth": null, + "method": "PATCH", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + } + ], + "body": { + "mode": "raw", + "raw": "{\n \"ops\": [\n {\n \"key\": \"value\"\n },\n {\n \"key\": \"value\"\n }\n ]\n}" + }, + "url": { + "raw": "{{url}}/v1/env", + "host": [ + "{{url}}" + ], + "path": [ + "v1", + "env" + ], + "query": [], + "variables": [] + }, + "description": "Apply multiple changes to environment variables for an organization, Sandbox, product, or device in a single request." + }, + "response": [] + }, + { + "name": "Delete environment variable", + "request": { + "auth": null, + "method": "DELETE", + "header": [], + "body": null, + "url": { + "raw": "{{url}}/v1/env/:key", + "host": [ + "{{url}}" + ], + "path": [ + "v1", + "env", + ":key" + ], + "query": [], + "variables": [ + { + "key": "key", + "value": "string", + "description": "Environment variable name.", + "disabled": false + } + ] + }, + "description": "Delete a single environment variable for an organization, Sandbox, product, or device." + }, + "response": [] + } + ] + }, { "name": "Events", "item": [ @@ -4633,13 +5084,13 @@ "query": [ { "key": "start_date", - "value": "2025-09-15T10:16:52.445Z", + "value": "2026-02-23T09:26:11.742Z", "description": "DateTime to start on (inclusive), defaults to the current time. Date in ISO8601 format.", "disabled": true }, { "key": "end_date", - "value": "2025-09-15T10:16:52.445Z", + "value": "2026-02-23T09:26:11.742Z", "description": "DateTime to end on (inclusive), defaults to the current time. Date in ISO8601 format.", "disabled": true }, @@ -4740,13 +5191,13 @@ "query": [ { "key": "start_date", - "value": "2025-09-15T10:16:52.446Z", + "value": "2026-02-23T09:26:11.743Z", "description": "DateTime to start on (inclusive), defaults to the current time. Date in ISO8601 format.", "disabled": true }, { "key": "end_date", - "value": "2025-09-15T10:16:52.446Z", + "value": "2026-02-23T09:26:11.743Z", "description": "DateTime to end on (inclusive), defaults to the current time. Date in ISO8601 format.", "disabled": true }, @@ -4847,13 +5298,13 @@ "query": [ { "key": "start_date", - "value": "2025-09-15T10:16:52.447Z", + "value": "2026-02-23T09:26:11.744Z", "description": "DateTime to start on (inclusive), defaults to the current time. Date in ISO8601 format.", "disabled": true }, { "key": "end_date", - "value": "2025-09-15T10:16:52.447Z", + "value": "2026-02-23T09:26:11.745Z", "description": "DateTime to end on (inclusive), defaults to the current time. Date in ISO8601 format.", "disabled": true }, @@ -4954,13 +5405,13 @@ "query": [ { "key": "start_date", - "value": "2025-09-15T10:16:52.449Z", + "value": "2026-02-23T09:26:11.746Z", "description": "DateTime to start on (inclusive), defaults to the current time. Date in ISO8601 format.", "disabled": true }, { "key": "end_date", - "value": "2025-09-15T10:16:52.449Z", + "value": "2026-02-23T09:26:11.746Z", "description": "DateTime to end on (inclusive), defaults to the current time. Date in ISO8601 format.", "disabled": true }, @@ -5061,13 +5512,13 @@ "query": [ { "key": "start_date", - "value": "2025-09-15T10:16:52.450Z", + "value": "2026-02-23T09:26:11.748Z", "description": "DateTime to start on (inclusive), defaults to the current time. Date in ISO8601 format.", "disabled": true }, { "key": "end_date", - "value": "2025-09-15T10:16:52.450Z", + "value": "2026-02-23T09:26:11.748Z", "description": "DateTime to end on (inclusive), defaults to the current time. Date in ISO8601 format.", "disabled": true }, @@ -6013,7 +6464,7 @@ ], "body": { "mode": "raw", - "raw": "{\n \"integration_type\": \"string\",\n \"event\": \"string\",\n \"url\": \"string\",\n \"name\": \"string\",\n \"requestType\": \"string\",\n \"deviceID\": \"string\",\n \"body\": \"string\",\n \"json\": {\n \"key\": \"value\"\n },\n \"form\": {\n \"key\": \"value\"\n },\n \"query\": {\n \"key\": \"value\"\n },\n \"auth\": {\n \"key\": \"value\"\n },\n \"headers\": {\n \"key\": \"value\"\n },\n \"responseTopic\": \"string\",\n \"errorResponseTopic\": \"string\",\n \"responseTemplate\": \"string\",\n \"noDefaults\": false,\n \"disabled\": false,\n \"rejectUnauthorized\": false,\n \"template\": \"string\",\n \"parameters\": [\n 0,\n 1\n ],\n \"secrets\": [\n 0,\n 1\n ]\n}" + "raw": "{\n \"integration_type\": \"string\",\n \"event\": \"string\",\n \"url\": \"string\",\n \"name\": \"string\",\n \"requestType\": \"string\",\n \"deviceID\": \"string\",\n \"body\": \"string\",\n \"json\": {\n \"key\": \"value\"\n },\n \"form\": {\n \"key\": \"value\"\n },\n \"query\": {\n \"key\": \"value\"\n },\n \"auth\": {\n \"key\": \"value\"\n },\n \"headers\": {\n \"key\": \"value\"\n },\n \"responseTopic\": \"string\",\n \"errorResponseTopic\": \"string\",\n \"responseTemplate\": \"string\",\n \"noDefaults\": false,\n \"disabled\": false,\n \"rejectUnauthorized\": false,\n \"template\": \"string\",\n \"parameters\": [\n 0,\n 1\n ],\n \"secrets\": [\n 0,\n 1\n ],\n \"use_env\": false\n}" }, "url": { "raw": "{{url}}/v1/integrations", @@ -6049,7 +6500,7 @@ ], "body": { "mode": "raw", - "raw": "{\n \"integration_type\": \"string\",\n \"event\": \"string\",\n \"url\": \"string\",\n \"name\": \"string\",\n \"requestType\": \"string\",\n \"deviceID\": \"string\",\n \"body\": \"string\",\n \"json\": {\n \"key\": \"value\"\n },\n \"form\": {\n \"key\": \"value\"\n },\n \"query\": {\n \"key\": \"value\"\n },\n \"auth\": {\n \"key\": \"value\"\n },\n \"headers\": {\n \"key\": \"value\"\n },\n \"responseTopic\": \"string\",\n \"errorResponseTopic\": \"string\",\n \"responseTemplate\": \"string\",\n \"noDefaults\": false,\n \"disabled\": false,\n \"rejectUnauthorized\": false,\n \"template\": \"string\",\n \"parameters\": [\n 0,\n 1\n ],\n \"secrets\": [\n 0,\n 1\n ]\n}" + "raw": "{\n \"integration_type\": \"string\",\n \"event\": \"string\",\n \"url\": \"string\",\n \"name\": \"string\",\n \"requestType\": \"string\",\n \"deviceID\": \"string\",\n \"body\": \"string\",\n \"json\": {\n \"key\": \"value\"\n },\n \"form\": {\n \"key\": \"value\"\n },\n \"query\": {\n \"key\": \"value\"\n },\n \"auth\": {\n \"key\": \"value\"\n },\n \"headers\": {\n \"key\": \"value\"\n },\n \"responseTopic\": \"string\",\n \"errorResponseTopic\": \"string\",\n \"responseTemplate\": \"string\",\n \"noDefaults\": false,\n \"disabled\": false,\n \"rejectUnauthorized\": false,\n \"template\": \"string\",\n \"parameters\": [\n 0,\n 1\n ],\n \"secrets\": [\n 0,\n 1\n ],\n \"use_env\": false\n}" }, "url": { "raw": "{{url}}/v1/integrations", @@ -6313,7 +6764,7 @@ ], "body": { "mode": "raw", - "raw": "{\n \"event\": \"string\",\n \"deviceID\": \"string\",\n \"url\": \"string\",\n \"name\": \"string\",\n \"requestType\": \"string\",\n \"body\": \"string\",\n \"json\": {\n \"key\": \"value\"\n },\n \"form\": {\n \"key\": \"value\"\n },\n \"query\": {\n \"key\": \"value\"\n },\n \"auth\": {\n \"key\": \"value\"\n },\n \"headers\": {\n \"key\": \"value\"\n },\n \"responseTopic\": \"string\",\n \"errorResponseTopic\": \"string\",\n \"responseTemplate\": \"string\",\n \"noDefaults\": false,\n \"disabled\": false,\n \"rejectUnauthorized\": false,\n \"template\": \"string\"\n}" + "raw": "{\n \"event\": \"string\",\n \"deviceID\": \"string\",\n \"url\": \"string\",\n \"name\": \"string\",\n \"requestType\": \"string\",\n \"body\": \"string\",\n \"json\": {\n \"key\": \"value\"\n },\n \"form\": {\n \"key\": \"value\"\n },\n \"query\": {\n \"key\": \"value\"\n },\n \"auth\": {\n \"key\": \"value\"\n },\n \"headers\": {\n \"key\": \"value\"\n },\n \"responseTopic\": \"string\",\n \"errorResponseTopic\": \"string\",\n \"responseTemplate\": \"string\",\n \"noDefaults\": false,\n \"disabled\": false,\n \"rejectUnauthorized\": false,\n \"template\": \"string\",\n \"use_env\": false\n}" }, "url": { "raw": "{{url}}/v1/integrations/:integrationId", @@ -6356,7 +6807,7 @@ ], "body": { "mode": "raw", - "raw": "{\n \"event\": \"string\",\n \"deviceID\": \"string\",\n \"url\": \"string\",\n \"name\": \"string\",\n \"requestType\": \"string\",\n \"body\": \"string\",\n \"json\": {\n \"key\": \"value\"\n },\n \"form\": {\n \"key\": \"value\"\n },\n \"query\": {\n \"key\": \"value\"\n },\n \"auth\": {\n \"key\": \"value\"\n },\n \"headers\": {\n \"key\": \"value\"\n },\n \"responseTopic\": \"string\",\n \"errorResponseTopic\": \"string\",\n \"responseTemplate\": \"string\",\n \"noDefaults\": false,\n \"disabled\": false,\n \"rejectUnauthorized\": false,\n \"template\": \"string\"\n}" + "raw": "{\n \"event\": \"string\",\n \"deviceID\": \"string\",\n \"url\": \"string\",\n \"name\": \"string\",\n \"requestType\": \"string\",\n \"body\": \"string\",\n \"json\": {\n \"key\": \"value\"\n },\n \"form\": {\n \"key\": \"value\"\n },\n \"query\": {\n \"key\": \"value\"\n },\n \"auth\": {\n \"key\": \"value\"\n },\n \"headers\": {\n \"key\": \"value\"\n },\n \"responseTopic\": \"string\",\n \"errorResponseTopic\": \"string\",\n \"responseTemplate\": \"string\",\n \"noDefaults\": false,\n \"disabled\": false,\n \"rejectUnauthorized\": false,\n \"template\": \"string\",\n \"use_env\": false\n}" }, "url": { "raw": "{{url}}/v1/integrations/:integrationId", @@ -9804,7 +10255,7 @@ "value": "application/json" } ], - "body": "GET /v1/user/products\nHTTP/1.1 200 OK\n{\n \"products\": [{\n \"id\": 12345,\n \"platform_id\": 10,\n \"name\": \"My Product\",\n \"slug\": \"my-product\",\n \"description\": \"My test product\",\n \"subscription_id\": 1234,\n \"user\": \"me@example.com\"\n \"groups\": [\n \"one\",\n \"two\"\n ],\n \"settings\": {\n \"location\": {},\n \"known_application\": {\n \"opt_in\": true\n },\n \"quarantine\": false\n }\n }]\n}" + "body": "GET /v1/user/products\nHTTP/1.1 200 OK\n{\n \"products\": [{\n \"id\": 12345,\n \"platform_id\": 10,\n \"name\": \"My Product\",\n \"slug\": \"my-product\",\n \"description\": \"My test product\",\n \"user\": \"me@example.com\"\n \"groups\": [\n \"one\",\n \"two\"\n ],\n \"settings\": {\n \"location\": {},\n \"known_application\": {\n \"opt_in\": true\n },\n \"quarantine\": false\n }\n }]\n}" } ] }, @@ -9870,7 +10321,7 @@ "value": "application/json" } ], - "body": "GET /v1/products/photon\nHTTP/1.1 200 OK\n{\n \"product\": {\n \"id\": 12345,\n \"platform_id\": 10,\n \"name\": \"My Product\",\n \"slug\": \"my-product\",\n \"description\": \"My test product\",\n \"subscription_id\": 1234,\n \"user\": \"me@example.com\"\n \"groups\": [\n \"one\",\n \"two\"\n ],\n \"settings\": {\n \"location\": {},\n \"known_application\": {\n \"opt_in\": true\n },\n \"quarantine\": false\n },\n \"device_protection\": \"disabled\"\n }\n}" + "body": "GET /v1/products/photon\nHTTP/1.1 200 OK\n{\n \"product\": {\n \"id\": 12345,\n \"platform_id\": 10,\n \"name\": \"My Product\",\n \"slug\": \"my-product\",\n \"description\": \"My test product\",\n \"user\": \"me@example.com\"\n \"groups\": [\n \"one\",\n \"two\"\n ],\n \"settings\": {\n \"location\": {},\n \"known_application\": {\n \"opt_in\": true\n },\n \"quarantine\": false\n },\n \"device_protection\": \"disabled\"\n }\n}" } ] }, @@ -10803,7 +11254,7 @@ ] }, { - "name": "Update the value of a cloud secret", + "name": "Create or Update the value of a cloud secret", "request": { "auth": null, "method": "PUT", @@ -10837,7 +11288,7 @@ } ] }, - "description": "Update the value of a cloud secret in the Sandbox or organization." + "description": "Creates or Updates the value of a cloud secret in the Sandbox or organization." }, "response": [ { @@ -10965,7 +11416,14 @@ "user", "service_agreements" ], - "query": [], + "query": [ + { + "key": "include_usage_summary", + "value": false, + "description": "Set to false to exclude current_usage_summary from the response. Defaults to true. Requires service_agreements.usage_summary:get scope.", + "disabled": true + } + ], "variables": [] }, "description": "Get the service agreements related to a user" @@ -11003,7 +11461,7 @@ "value": "application/json" } ], - "body": " GET /v1/orgs/particle/service_agreements\n HTTP/1.1 200 OK\n{\n\t\"data\":[\n\t\t\t{\n\t\t\t\t\"id\":\"1\",\n\t\t\t\t\"type\":\"service_agreement\",\n\t\t\t\t\"attributes\":{\n\t\t\t\t\t\"owner_id\":\"abc123\",\n\t\t\t\t\t\"owner_type\":\"individual\",\n\t\t\t\t\t\"name\":\"Sandbox\",\n\t\t\t\t\t\"agreement_type\":\"developer\",\n\t\t\t\t\t\"duration\":\"monthly\",\n\t\t\t\t\t\"state\":\"active\",\n\t\t\t\t\t\"starts_on\":\"2021-04-08\",\n\t\t\t\t\t\"ends_on\":null,\n\t\t\t\t\t\"current_billing_period_start\":\"2021-04-08\",\n\t\t\t\t\t\"current_billing_period_end\":\"2021-05-07\",\n\t\t\t\t\t\"next_billing_period_start\":\"2021-05-08\",\n\t\t\t\t\t\"current_usage_summary\":{\n\t\t\t\t\t\t\"device_limit_reached\":false,\n\t\t\t\t\t\t\"connectivity\":{\n\t\t\t\t\t\t\t\"all\":{\n\t\t\t\t\t\t\t\t\"owned_devices\":0,\n\t\t\t\t\t\t\t\t\"billable_devices\":0,\n\t\t\t\t\t\t\t\t\"device_data\":0,\n\t\t\t\t\t\t\t\t\"device_messages\":0\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t\"wifi\":{\n\t\t\t\t\t\t\t\t\"owned_devices\":0,\n\t\t\t\t\t\t\t\t\"billable_devices\":0,\n\t\t\t\t\t\t\t\t\"device_data\":null,\n\t\t\t\t\t\t\t\t\"device_messages\":0\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t\"cellular\":{\n\t\t\t\t\t\t\t\t\"owned_devices\":0,\n\t\t\t\t\t\t\t\t\"billable_devices\":0,\n\t\t\t\t\t\t\t\t\"device_data\":0,\n\t\t\t\t\t\t\t\t\"device_messages\":0\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t\"asset_tracker\":{\n\t\t\t\t\t\t\t\t\"owned_devices\":0,\n\t\t\t\t\t\t\t\t\"billable_devices\":0,\n\t\t\t\t\t\t\t\t\"device_data\":0,\n\t\t\t\t\t\t\t\t\"device_messages\":0\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t}\n\t\t\t\t\t},\n\t\t\t\t\t\"pricing_terms\":{\n\t\t\t\t\t\t\"rates\":{\n\t\t\t\t\t\t\t\"all_platforms\":{\n\t\t\t\t\t\t\t\t\"duration\":\"monthly\",\n\t\t\t\t\t\t\t\t\"per_block\":0\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t\"pricing_model_version\":\"tier2021.1\"\n\t\t\t\t\t\t},\n\t\t\t\t\t\t\"device\":{\n\t\t\t\t\t\t\t\"name\":\"commercial_model:developer:device\",\n\t\t\t\t\t\t\t\"duration\":\"monthly\",\n\t\t\t\t\t\t\t\"max_devices\":100\n\t\t\t\t\t\t},\n\t\t\t\t\t\t\"messaging\":{\n\t\t\t\t\t\t\t\"name\":\"commercial_model:developer:messaging\",\n\t\t\t\t\t\t\t\"duration\":\"monthly\",\n\t\t\t\t\t\t\t\"max_messages\":100000\n\t\t\t\t\t\t},\n\t\t\t\t\t\t\"device_data\":{\n\t\t\t\t\t\t\t\"uom\":\"bytes\",\n\t\t\t\t\t\t\t\"name\":\"commercial_model:developer:device_data\",\n\t\t\t\t\t\t\t\"duration\":\"monthly\",\n\t\t\t\t\t\t\t\"max_data\":45000000,\n\t\t\t\t\t\t\t\"device_data\":45000000,\n\t\t\t\t\t\t\t\"devices_cap\":45000000,\n\t\t\t\t\t\t\t\"cap_exception\":true\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t]\n\t}" + "body": " GET /v1/users/service_agreements\n HTTP/1.1 200 OK\n{\n\t\"data\":[\n\t\t\t{\n\t\t\t\t\"id\":\"1\",\n\t\t\t\t\"type\":\"service_agreement\",\n\t\t\t\t\"attributes\":{\n\t\t\t\t\t\"owner_id\":\"abc123\",\n\t\t\t\t\t\"owner_type\":\"individual\",\n\t\t\t\t\t\"name\":\"Sandbox\",\n\t\t\t\t\t\"agreement_type\":\"developer\",\n\t\t\t\t\t\"duration\":\"monthly\",\n\t\t\t\t\t\"state\":\"active\",\n\t\t\t\t\t\"starts_on\":\"2021-04-08\",\n\t\t\t\t\t\"ends_on\":null,\n\t\t\t\t\t\"current_billing_period_start\":\"2021-04-08\",\n\t\t\t\t\t\"current_billing_period_end\":\"2021-05-07\",\n\t\t\t\t\t\"next_billing_period_start\":\"2021-05-08\",\n\t\t\t\t\t\"current_usage_summary\":{\n\t\t\t\t\t\t\"device_limit_reached\":false,\n\t\t\t\t\t\t\"connectivity\":{\n\t\t\t\t\t\t\t\"all\":{\n\t\t\t\t\t\t\t\t\"owned_devices\":0,\n\t\t\t\t\t\t\t\t\"billable_devices\":0,\n\t\t\t\t\t\t\t\t\"device_data\":0,\n\t\t\t\t\t\t\t\t\"device_messages\":0\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t\"wifi\":{\n\t\t\t\t\t\t\t\t\"owned_devices\":0,\n\t\t\t\t\t\t\t\t\"billable_devices\":0,\n\t\t\t\t\t\t\t\t\"device_data\":null,\n\t\t\t\t\t\t\t\t\"device_messages\":0\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t\"cellular\":{\n\t\t\t\t\t\t\t\t\"owned_devices\":0,\n\t\t\t\t\t\t\t\t\"billable_devices\":0,\n\t\t\t\t\t\t\t\t\"device_data\":0,\n\t\t\t\t\t\t\t\t\"device_messages\":0\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t\"asset_tracker\":{\n\t\t\t\t\t\t\t\t\"owned_devices\":0,\n\t\t\t\t\t\t\t\t\"billable_devices\":0,\n\t\t\t\t\t\t\t\t\"device_data\":0,\n\t\t\t\t\t\t\t\t\"device_messages\":0\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t}\n\t\t\t\t\t},\n\t\t\t\t\t\"pricing_terms\":{\n\t\t\t\t\t\t\"rates\":{\n\t\t\t\t\t\t\t\"all_platforms\":{\n\t\t\t\t\t\t\t\t\"duration\":\"monthly\",\n\t\t\t\t\t\t\t\t\"per_block\":0\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t\"pricing_model_version\":\"tier2021.1\"\n\t\t\t\t\t\t},\n\t\t\t\t\t\t\"device\":{\n\t\t\t\t\t\t\t\"name\":\"commercial_model:developer:device\",\n\t\t\t\t\t\t\t\"duration\":\"monthly\",\n\t\t\t\t\t\t\t\"max_devices\":100\n\t\t\t\t\t\t},\n\t\t\t\t\t\t\"messaging\":{\n\t\t\t\t\t\t\t\"name\":\"commercial_model:developer:messaging\",\n\t\t\t\t\t\t\t\"duration\":\"monthly\",\n\t\t\t\t\t\t\t\"max_messages\":100000\n\t\t\t\t\t\t},\n\t\t\t\t\t\t\"device_data\":{\n\t\t\t\t\t\t\t\"uom\":\"bytes\",\n\t\t\t\t\t\t\t\"name\":\"commercial_model:developer:device_data\",\n\t\t\t\t\t\t\t\"duration\":\"monthly\",\n\t\t\t\t\t\t\t\"max_data\":45000000,\n\t\t\t\t\t\t\t\"device_data\":45000000,\n\t\t\t\t\t\t\t\"devices_cap\":45000000,\n\t\t\t\t\t\t\t\"cap_exception\":true\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t]\n\t}" } ] }, @@ -11025,7 +11483,14 @@ ":orgIdOrSlug", "service_agreements" ], - "query": [], + "query": [ + { + "key": "include_usage_summary", + "value": false, + "description": "Set to false to exclude current_usage_summary from the response. Defaults to true. Requires service_agreements.usage_summary:get scope.", + "disabled": true + } + ], "variables": [ { "key": "orgIdOrSlug", @@ -12315,7 +12780,7 @@ "value": "application/json" } ], - "body": "GET /v1/user\nHTTP/1.1 200 OK\n{\n \"username\": \"testuser@particle.io\",\n \"subscription_ids\": [],\n \"account_info\": {\n \"first_name\": \"Test\",\n \"last_name\": \"User\",\n \"business_account\": false\n },\n scim_provisioned: false,\n no_password: false,\n \"mfa\": {\n \"enabled\": false\n },\n \"wifi_device_count\": 0,\n \"cellular_device_count\": 0\n}" + "body": "GET /v1/user\nHTTP/1.1 200 OK\n{\n \"username\": \"testuser@particle.io\",\n \"account_info\": {\n \"first_name\": \"Test\",\n \"last_name\": \"User\",\n \"business_account\": false\n },\n scim_provisioned: false,\n no_password: false,\n \"mfa\": {\n \"enabled\": false\n },\n \"wifi_device_count\": 0,\n \"cellular_device_count\": 0\n}" } ] }, diff --git a/scripts/apidoc.js b/scripts/apidoc.js index a47d714d64..7805f8f814 100644 --- a/scripts/apidoc.js +++ b/scripts/apidoc.js @@ -6,6 +6,7 @@ var fs = require('fs'); var path = require('path'); var apiScopes = []; +let firstLoad = true; function assignOrder(data) { data.forEach(function (route) { @@ -17,6 +18,12 @@ function assignOrder(data) { module.exports = function(options) { return function(files, metalsmith, done) { + // Only run this on first load, not when doing updates because the source files are not tracked + if (!firstLoad) { + return done(); + } + firstLoad = false; + var apiData = options.apis.map(function processApi(apiOptions) { const savePath = path.join(__dirname, '..', 'generated', path.basename(apiOptions.src) + '.json'); apiOptions.parse = true; diff --git a/src/assets/files/apiMenus.json b/src/assets/files/apiMenus.json index 6bfd6c0790..8ddaa4125c 100644 --- a/src/assets/files/apiMenus.json +++ b/src/assets/files/apiMenus.json @@ -5047,6 +5047,32 @@ "title": "backupRamSync - System calls", "dir": "backupramsync" }, + { + "title": "Enviroment variables - System - System calls", + "dir": "enviroment-variables-system", + "subsections": [ + { + "anchor": "getenv-enviroment-variables-system", + "title": "getEnv - Enviroment variables - System", + "isContent": true + }, + { + "anchor": "hasenv-enviroment-variables-system", + "title": "hasEnv - Enviroment variables - System", + "isContent": true + }, + { + "anchor": "listenv-enviroment-variables-system", + "title": "listEnv - Enviroment variables - System", + "isContent": true + }, + { + "anchor": "clearenv-enviroment-variables-system", + "title": "clearEnv - Enviroment variables - System", + "isContent": true + } + ] + }, { "title": "System config [ set ] - System calls", "dir": "system-config-set" diff --git a/src/assets/files/carriers.json b/src/assets/files/carriers.json index 156902fd20..b642e22023 100644 --- a/src/assets/files/carriers.json +++ b/src/assets/files/carriers.json @@ -26040,6 +26040,10 @@ "M1-5", "M1-12", "M1-13" + ], + "env": [ + "PARTICLE_CELLULAR_PREFERRED_BANDS", + "PARTICLE_CELLULAR_FORBIDDEN_BANDS" ] }, { @@ -26071,6 +26075,11 @@ "M1-5", "M1-12", "M1-13" + ], + "env": [ + "PARTICLE_CELLULAR_PREFERRED_PLMN", + "PARTICLE_CELLULAR_PREFERRED_BANDS", + "PARTICLE_CELLULAR_FORBIDDEN_BANDS" ] }, { @@ -26093,6 +26102,11 @@ ], "technologies": [ "M1" + ], + "env": [ + "PARTICLE_CELLULAR_PREFERRED_PLMN", + "PARTICLE_CELLULAR_PREFERRED_BANDS", + "PARTICLE_CELLULAR_FORBIDDEN_BANDS" ] }, { @@ -26158,6 +26172,11 @@ "technologies": [ "2G", "M1" + ], + "env": [ + "PARTICLE_CELLULAR_PREFERRED_PLMN", + "PARTICLE_CELLULAR_PREFERRED_BANDS", + "PARTICLE_CELLULAR_FORBIDDEN_BANDS" ] }, { @@ -26269,6 +26288,11 @@ "2G", "3G", "4G" + ], + "env": [ + "PARTICLE_CELLULAR_PREFERRED_PLMN", + "PARTICLE_CELLULAR_PREFERRED_BANDS", + "PARTICLE_CELLULAR_FORBIDDEN_BANDS" ] }, { @@ -26311,6 +26335,11 @@ "2G", "3G", "4G" + ], + "env": [ + "PARTICLE_CELLULAR_PREFERRED_PLMN", + "PARTICLE_CELLULAR_PREFERRED_BANDS", + "PARTICLE_CELLULAR_FORBIDDEN_BANDS" ] }, { @@ -26330,6 +26359,11 @@ "technologies": [ "3G", "4G" + ], + "env": [ + "PARTICLE_CELLULAR_PREFERRED_PLMN", + "PARTICLE_CELLULAR_PREFERRED_BANDS", + "PARTICLE_CELLULAR_FORBIDDEN_BANDS" ] }, { @@ -26429,6 +26463,13 @@ "technologies": [ "4G", "5G" + ], + "env": [ + "PARTICLE_CELLULAR_PREFERRED_PLMN", + "PARTICLE_CELLULAR_PREFERRED_BANDS", + "PARTICLE_CELLULAR_FORBIDDEN_BANDS", + "PARTICLE_CELLULAR_SIM_SLOT", + "PARTICLE_CELLULAR_RADIO_MODE" ] }, { @@ -26487,6 +26528,13 @@ "3G", "4G", "5G" + ], + "env": [ + "PARTICLE_CELLULAR_PREFERRED_PLMN", + "PARTICLE_CELLULAR_PREFERRED_BANDS", + "PARTICLE_CELLULAR_FORBIDDEN_BANDS", + "PARTICLE_CELLULAR_SIM_SLOT", + "PARTICLE_CELLULAR_RADIO_MODE" ] } ], diff --git a/src/assets/images/console/config-create.png b/src/assets/images/console/config-create.png new file mode 100644 index 0000000000..dbaa566cc0 Binary files /dev/null and b/src/assets/images/console/config-create.png differ diff --git a/src/assets/images/console/config-list.png b/src/assets/images/console/config-list.png new file mode 100644 index 0000000000..5f677bcdec Binary files /dev/null and b/src/assets/images/console/config-list.png differ diff --git a/src/assets/images/console/config-org.png b/src/assets/images/console/config-org.png new file mode 100644 index 0000000000..012150355e Binary files /dev/null and b/src/assets/images/console/config-org.png differ diff --git a/src/assets/images/console/config-product.png b/src/assets/images/console/config-product.png new file mode 100644 index 0000000000..a99cf382b5 Binary files /dev/null and b/src/assets/images/console/config-product.png differ diff --git a/src/assets/images/console/config-rollout.png b/src/assets/images/console/config-rollout.png new file mode 100644 index 0000000000..7bc2f66976 Binary files /dev/null and b/src/assets/images/console/config-rollout.png differ diff --git a/src/assets/images/console/config-sandbox.png b/src/assets/images/console/config-sandbox.png new file mode 100644 index 0000000000..0f33e69ded Binary files /dev/null and b/src/assets/images/console/config-sandbox.png differ diff --git a/src/assets/images/console/config-start.png b/src/assets/images/console/config-start.png new file mode 100644 index 0000000000..0414c06054 Binary files /dev/null and b/src/assets/images/console/config-start.png differ diff --git a/src/assets/images/console/config-update-delete.png b/src/assets/images/console/config-update-delete.png new file mode 100644 index 0000000000..4e06eb1b97 Binary files /dev/null and b/src/assets/images/console/config-update-delete.png differ diff --git a/src/assets/images/console/config-update-rollout.png b/src/assets/images/console/config-update-rollout.png new file mode 100644 index 0000000000..fd08e1c639 Binary files /dev/null and b/src/assets/images/console/config-update-rollout.png differ diff --git a/src/assets/js/api-helper-extras.js b/src/assets/js/api-helper-extras.js index 7bc3b15deb..cdab383826 100644 --- a/src/assets/js/api-helper-extras.js +++ b/src/assets/js/api-helper-extras.js @@ -3784,9 +3784,130 @@ $(document).ready(function() { run(); }) + $('.bandMaskCalculator').each(function() { + const thisPartial = $(this); + + const enableButtons = function() { + const s = $(thisPartial).find('.numInput').val(); + + const m = s.match(/^([0-9]+)$/); + if (m) { + $(thisPartial).find('.upButton').prop('disabled', false); + } + else { + $(thisPartial).find('.upButton').prop('disabled', true); + } + }; + + + const calculateDown = function() { + let mask = 0n; + $(thisPartial).find('.bandMaskInputCheckbox:checked').each(function() { + const band = BigInt($(this).data('band')); + mask |= (1n << (band - 1n)); + }); + $(thisPartial).find('.numInput').val(mask.toString(10)); + enableButtons(); + }; + + const calculateUp = function() { + const mask = BigInt($(thisPartial).find('.numInput').val()); + + $(thisPartial).find('.bandMaskInputCheckbox').each(function() { + const band = BigInt($(this).data('band')); + + const bandBit = 1n << (band - 1n); + $(this).prop('checked', (mask & bandBit) != 0); + + }); + } + + for(let band = 1; band < 128; band++) { + const divElem = document.createElement('div'); + $(divElem).css('width', '75px'); + + const labelElem = document.createElement('label'); + const inputElem = document.createElement('input'); + $(inputElem).attr('type', 'checkbox'); + $(inputElem).addClass('bandMaskInputCheckbox'); + $(inputElem).data('band', band); + $(inputElem).on('click', calculateDown); + $(labelElem).append(inputElem); + + const textElem = document.createTextNode('B' + band) + $(labelElem).append(textElem); + + $(divElem).append(labelElem); + + $(thisPartial).find('.bandsDiv').append(divElem); + } + enableButtons(); + + $(thisPartial).find('.numInput').on('change', function() { + enableButtons(); + }); + $(thisPartial).find('.numInput').on('keydown', function(ev) { + if (ev.key == 'Enter') { + calculateUp(); + } + enableButtons(); + }); + + + $(thisPartial).find('.downButton').on('click', calculateDown); + + $(thisPartial).find('.upButton').on('click', calculateUp); + + + $(thisPartial).find('.selectAllButton').on('click', function() { + $(thisPartial).find('.bandMaskInputCheckbox').prop('checked', true); + calculateDown(); + }); + $(thisPartial).find('.selectNoneButton').on('click', function() { + $(thisPartial).find('.bandMaskInputCheckbox').prop('checked', false); + calculateDown(); + }); + + }) + + $('.envVarSkus').each(async function() { + const thisPartial = $(this); + + const carriersJson = await apiHelper.getCarriersJson(); + + const varName = $(thisPartial).data('var'); + + const tbodyElem = $(thisPartial).find('.envVarSkusTableBody'); + + for(const skuObj of carriersJson.skus) { + if (!skuObj.modem || skuObj.lifecycle == 'Hidden') { + continue; + } + const modemObj = carriersJson.modems.find(e => e.model == skuObj.modem); + if (!modemObj || !modemObj.env) { + continue; + } + + if (!modemObj.env.includes(varName)) { + continue; + } + + const trElem = document.createElement('tr'); + + for(const field of ['name', 'desc', 'lifecycle', 'modem']) { + const tdElem = document.createElement('td'); + $(tdElem).text(skuObj[field]); + $(trElem).append(tdElem); + } + + $(tbodyElem).append(trElem); + } + }); + }); + /* function updateTinker(settings) { $('.apiHelperTinker').each(function() { diff --git a/src/content/getting-started/configuration/configuration.md b/src/content/getting-started/configuration/configuration.md new file mode 100644 index 0000000000..a74645971b --- /dev/null +++ b/src/content/getting-started/configuration/configuration.md @@ -0,0 +1,20 @@ +--- +title: Configuration +columns: two +layout: commonTwo.hbs +description: Configuration +--- + + +**Configuration** is a platform‑wide capability for Particle. Configuration is the control plane for tailoring how devices, cloud, and applications behave, used to solve real-life problems like modem behavior and operating system level radio configuration, as well as to align user applications needs from any vertical or use case. + +Configuration is used by all parts of IoT deployment: Device OS, cloud services, pre-built applications like Tracker Edge and Monitor Edge, and user applications. + +Configuration scales from organization‑wide defaults, to product‑level settings, to device‑specific overrides where appropriate. + +It comprises three complementary layers: + +- [Environment](/getting-started/configuration/environment/): lightweight, non‑secret name - value pairs that shape the runtime environment. They are ideal for fast, system level adjustments (endpoints, feature flags, polling intervals) without changing firmware. Available in the cloud and in the firmware. +- [Secrets](/getting-started/cloud/secrets/): secure, organization‑scoped values that integrations and logic can reference securely. +- Typed configuration: schema‑validated parameters that govern firmware‑level behavior at scale. A template (JSON Schema) is exposed so teams can type, document, and revision‑control options. + diff --git a/src/content/getting-started/configuration/environment.md b/src/content/getting-started/configuration/environment.md new file mode 100644 index 0000000000..353050de27 --- /dev/null +++ b/src/content/getting-started/configuration/environment.md @@ -0,0 +1,309 @@ +--- +title: Environment +columns: two +layout: commonTwo.hbs +description: Environment +includeDefinitions: [api-helper, api-helper-extras] + +--- + +{{!-- BEGIN shared-blurb 79e94a32-654d-4961-8498-5d7969690c4a --}} +Environment is a collection of lightweight, non‑secret, name - value pairs that shape the runtime environment. They are ideal for fast, system level adjustments (endpoints, feature flags, polling intervals) without changing firmware. Available in the cloud and in the firmware, they allow configuration of both Device OS features and user features in a hierarchical manner from organization, the product, with optional per-device overrides. +{{!-- END shared-blurb --}} + +The feature is available in Device OS 6.4.0 and later. + +## Variables + +Environment variables are name - value pairs. + +{{!-- BEGIN shared-blurb 436d14ef-9684-4d3e-85de-72de338ff565 --}} +- Variable names are uppercase letters, underscores and numbers only, and cannot start with a number. +- Variable names beginning with `PARTICLE_` are reserved for Particle use. +- Maximum variable name length: 128 characters. +- Maximum variable value length: Not limited per variable. +- The total size of all name - value pairs to be delivered to a device cannot exceed 16 Kbytes. +{{!-- END shared-blurb --}} + + +## Hierarchical + +### Organization products + +For products in an organization (basic, plus, or enterprise), you can set environment variables at the organization, product, or device level. + +> Organization ← Product ← Device + +If a variable is set in multiple layers, the most specific (rightmost) setting is used. + + +### Sandbox products + +For products in the free developer sandbox, you can set environment variables at the sandbox, product, or device level. + +> Sandbox ← Product ← Device + +If a variable is set in multiple layers, the most specific (rightmost) setting is used. + +Environment variables are only used for devices in a product. This is also the case for [Ledger](/getting-started/logic-ledger/ledger/). + +## Synchronized + +When variables are changed at a given level, the changed are staged for delivery to devices. + +Added, removed, or changed variables can be delivered immediately to online devices. For devices that are offline, changes are delivered when the device connects to the cloud. + +Each device has a snapshot, which is the combination of organization (or sandbox), product, and per-device environment variables specific to that device. + +When an update affects the snapshot for a device and the device is online, the snapshot is immediately sent to the device. The snapshot contains all values (not just the changed ones) and is limited to 16 kB, with the limit enforced on the JSON-encoded key–value pairs. + +When a device is comes online, a hash of its current snapshot is sent to the cloud. If the snapshot is not current, then the cloud sends a new snapshot to the device. + +## Console + +### Product - Console + +You will often configure your environment variables per-product. Once you have opened your organization or sandbox product, go to **Configuration** then **Environment** in the left navigation bar. + +{{imageOverlay src="/assets/images/console/config-product.png" class="no-darken"}} + +These environment variables are sent to every device in this product. + +### Organization - Console + +If you have access to an organization (basic, plus, or enterprise), you can set environment variables at the organization level in the **Organization - Configuration - Environment** section. + +{{imageOverlay src="/assets/images/console/config-org.png" class="no-darken"}} + +These environment variables are sent to every device in every product in the organization. + +### Sandbox - Console + +For the free developer sandbox, you can set environment variables in **Sandbox - Configuration - Environment** section. + +{{imageOverlay src="/assets/images/console/config-sandbox.png" class="no-darken"}} + +These environment variables are sent to every device in every product owned by this developer account. + +### Creating an environment variable + +When you create your first environment variable in a scope, you will see a screen similar to this: + +{{imageOverlay src="/assets/images/console/config-start.png" class="no-darken"}} + +To create an environment variable, fill in this screen: + +{{imageOverlay src="/assets/images/console/config-create.png" class="no-darken"}} + +{{!-- BEGIN shared-blurb 436d14ef-9684-4d3e-85de-72de338ff565 --}} +- Variable names are uppercase letters, underscores and numbers only, and cannot start with a number. +- Variable names beginning with `PARTICLE_` are reserved for Particle use. +- Maximum variable name length: 128 characters. +- Maximum variable value length: Not limited per variable. +- The total size of all name - value pairs to be delivered to a device cannot exceed 16 Kbytes. +{{!-- END shared-blurb --}} + +Once you've created a variable, you'll see a list of variables that you have created within this scope. + +{{imageOverlay src="/assets/images/console/config-list.png" class="no-darken"}} + +Creating a new variable does not immediately take effect. Once you have made all of the changes you intend to at this scope, click the **Next** button to roll out the changes. + +{{imageOverlay src="/assets/images/console/config-rollout.png" class="no-darken"}} + +Changes take effect immediately for online devices, and will be sent to offline devices when they next connect to the Particle cloud. + +When a device connects to the cloud a hash of the current environment is sent to the cloud and a new version is only sent if the device does not have the current environment snapshot for the device. + +### Environment variable values + +The value is a string that can be used for any data type, however, there are two built-in decoders in Device OS. + +#### Boolean environment variable values + +If the string has the value `true` or `false` (case-sensitive, lowercase), you can use the `bool` overload in Device OS. + +```cpp +// EXAMPLE +bool enabled; +if (System.getEnv("ENABLE_DEBUG", enabled) && enabled) { + // Variable was set and is value and true +} + +// PROTOTYPE in System class +static bool getEnv(const char* name, bool& value); +``` + +#### Integer environment variable values + +If the string has an valid 32-bit signed integer value, you can use the `int` overload in Device OS. + +```cpp +// EXAMPLE +int value; +if (System.getEnv("RETRY_PERIOD", value)) { + // Value was set, do something with it here +} + +// PROTOTYPE in System class +static bool getEnv(const char* name, int& value); +``` + +### Editing an environment variable + +When editing the environment, you can update or delete individual variables. + +{{imageOverlay src="/assets/images/console/config-update-delete.png" class="no-darken"}} + +Don't forget to rollout the changes to devices after updating. + +{{imageOverlay src="/assets/images/console/config-update-rollout.png" class="no-darken"}} + +## Cloud API + +Environment variables can be configured using the Cloud API. See the [Cloud API Reference](/reference/cloud-apis/api/#environment). + +## Device OS + +To read environment variables from your code, you use functions like `System.getEnv()`. These are described in the [Device OS API reference](/reference/device-os/api/system-calls/enviroment-variables-system/). + +Device OS 6.4.0 or later is required. + +## Firmware variables + +You can optionally include environment variables with your application using an application bundle, the same technology used for [Asset OTA](/getting-started/cloud/ota-updates/#asset-ota). + +This is useful for seeding the default variable values before your firmware connects to the cloud the first time, instead of checking whether the variable exists and embedding the value in your code when you read it. + + +### Using project.properties - Firmware variables + +The `env` key in the project.properties allows bundling of an application binary (.bin) file with an arbitrary JSON file of name - value pairs. + +``` +name=MyProject +env=env.json +``` + +As is the case with Asset OTA, specifying `env` will create a .zip file for your application that contains both the binary and its additional data. + +### Using particle bundle - Firmware variables + +Using the [Particle CLI](/reference/developer-tools/cli/#particle-bundle) `particle bundle` command with the `--env` option allows bundling of an application binary (.bin) file with an arbitrary JSON file of name - value pairs. + +## Device OS environment variables + +| Name | Description | Type | Version Added| +| :--- | :--- | :--- | +| `PARTICLE_BLUETOOTH_ENABLE` | Set to `false` to disable BLE | bool | 6.4.0 | +| `PARTICLE_ETHERNET_ENABLE` | Set to `false` to disable Ethernet | bool | 6.4.0 | +| `PARTICLE_WIFI_ENABLE` | Set to `false` to disable Wi-Fi | bool | 6.4.0 | + + +## Cellular environment variables + +{{box op="start" cssClass="boxed warningBox"}} +Changing cellular environment variables may adversely affect connectivity. Under normal circumstances you should never need to change these values, and if you do change them, be sure to test changes on a subset of your fleet that you have easy access to in case the changes make the device unable to connect to cellular again. +{{box op="end"}} + +### PARTICLE_CELLULAR_PREFERRED_PLMN + +- Available in Device OS 6.4.0 and later +- Gen 3 and Gen 4 devices +- This variable is not available on the B402, B404, BRN402, or BRN404 but is available on the B404X and BRN404X + +Sets the preferred list of operators in MCCMNC format. Up to three can be specified. For example: + +- `311480,310410` +- `311480` + +- If set to an empty string, the modem default is used. + +{{> env-var-skus var="PARTICLE_CELLULAR_PREFERRED_PLMN"}} + +### PARTICLE_CELLULAR_PREFERRED_BANDS + +- Available in Device OS 6.4.0 and later +- Gen 3 and Gen 4 devices + +Sets preferred bands using a band mask. After 10 minutes of failing to connect, the device reverts to using all bands instead of just the preferred bands. + +The band mask is a bit field of bands. For example: + +| Band | Bit | Mask | +| :--- | :--- | :--- | +| B1 | 0 | 1 | +| B2 | 1 | 2 | +| B3 | 2 | 4 | +| B4 | 3 | 8 | +| B5 | 4 | 16 | + +The value to store for the key is a uint128 value represented in decimal of the band mask values added together. + +{{> band-mask-calculator }} + +{{> env-var-skus var="PARTICLE_CELLULAR_PREFERRED_BANDS"}} + +### PARTICLE_CELLULAR_FORBIDDEN_BANDS + +- Available in Device OS 6.4.0 and later +- Gen 3 and Gen 4 devices + +Sets a mask of bands to not use. The band mask is the same uint128 format as for `PARTICLE_CELLULAR_PREFERRED_BANDS`. + +{{> env-var-skus var="PARTICLE_CELLULAR_FORBIDDEN_BANDS"}} + + +## Logic + +Environment variables are available in [Logic](/getting-started/logic-ledger/logic/) via the `env` member of the `FunctionContent`. + +{{!-- BEGIN shared-blurb a001a102-d85f-4def-941e-39e53459f5c4 --}} +- `functionInfo`: information about the function that was called +- `trigger`: information about the time the event was triggered +- `secrets`: cloud secrets for this product and organization +- `env`: environment variables for this function + +Additionally, one of the following parameters will be populated, based on the type of trigger: + +- `event`: information about the event that triggered the Logic Function +- `scheduled`: information about the schedule that triggered the Logic Function +- `ledgerChange`: information about a ledger database change the triggered the Logic Function (future) + +```js +// PROTOTYPE +export interface FunctionContext { + functionInfo: FunctionInfo, + trigger: TriggerInfo, + secrets: Record| SKU | +Name | +Lifecycle | +Modem | +
|---|