Updating settings for a specific device via API

Golioth Cloud Help
1

Description

Hello,

I would like to change the settings for a single device using the API.
According to the OpenAPI documentation, I’m using the PUT /v1/projects/{projectId}/settings/{settingId} endpoint, but it updates the setting value for all my devices.

Is there a query parameter I can add to specify the device ID?

Thanks for your help,
Have a nice day!

Expected Behavior

Change the setting for one device

Actual Behavior

Change the settings for all devices

Environment

Not applicable.

Logs and Console Output

Not applicable.

3

Hey @mathieu.legros,

You’re hitting the right Settings endpoint, but in your query, you’re using the Settings ID from the Project-wide Device Settings instead of the override specific to that device.

Just to clarify: each Project-wide setting has its own Settings ID. When a setting is overridden at the device level, a separate Settings ID is created for that device. This means you can update project settings globally or override them on a per-device basis.

A GET request to /v1/projects/{projectId}/settings will return only the Project-wide Settings IDs. In contrast, a GET to /v1/projects/{projectId}/devices/{deviceId}/settings will return both: the inherited Project-wide Settings and any device-specific overrides (if they differ from the project defaults).

So, to override a setting at the device level, use the same API endpoint but pass the device-specific Settings ID instead.

4

Hello @marko,

Thanks for your reply.

I’m using the /v1/projects/{projectId}/devices/{deviceId}/settings request and I insert the “id” value as setting ID in the /v1/projects/{projectId}/settings/{settingId}.

Wich object should i use in the first request’s response ?

{
  "list": [
    {
      "id": "string",
      "key": "string",
      "value": "string",
      "dataType": "string",
      "projectId": "string",
      "blueprintId": "string",
      "deviceId": "string",
      "createdAt": "2025-06-04T08:43:58.492Z",
      "updatedAt": "2025-06-04T08:43:58.492Z"
    }
  ],
  "total": 0
}
5

Hey @mathieu.legros,

To override a device-specific setting, you should use the "id" field from the object where the "deviceId" is present. In the response you shared, the presence of the "deviceId" field indicates that the setting is specific to a particular device — meaning the corresponding "id" refers to a device-level override.

If the "deviceId" field is missing, then the "id" belongs to a project-wide setting instead.

If you’re trying to override a setting for a specific device, use the "id" from the object where "deviceId" matches the device you’re targeting.

If no such device-specific setting exists yet, you’ll need to create an override by sending a POST request to:

/v1/projects/{projectId}/settings

With a body, for example:

{ 
  "key": "TEST",
  "value": 22,
  "dataType": "integer",
  "deviceId": "<your-device-id>"
}
6

Thanks a lot @marko ,

Just to confirm I understood correctly:

I retried the process step by step on my side:

  • I have a device with ID “XXX” that inherits several settings from the global configuration.
  • I manually changed one of the settings through the interface.
  • Then, I used the endpoint GET https://api.golioth.io/v1/projects/{project_id}/devices/XXX/settings and got the full list of settings. The modified setting appears twice: once from the global settings, and once as a device-specific override:
{
  "list": [
    {
      "id": <id>,
      "key": <key>,
      "value": false,
      "dataType": "boolean",
      "projectId": <projectId>,
      "createdAt": "2025-01-24T12:45:12.409Z",
      "updatedAt": "2025-06-04T13:00:20.183Z"
    },
    {
      "id": <id>,
      "key": <key>,
      "value": true,
      "dataType": "boolean",
      "projectId": <projectId>,
      "deviceId": <deviceId>,
      "createdAt": "2025-05-26T15:59:01.089Z",
      "updatedAt": "2025-06-04T13:00:20.183Z"
    }
  ],
  "total": 11
}
  • So if I want to update the setting just for that device, I should use the second object (the one that includes the deviceId) in the PUT request, correct?

From what I understand, if I want to apply a different value for a setting on a specific device, I need to override it with the request /v1/projects/{projectId}/settings. Is that the expected behavior?

7

Hey @mathieu.legros,

I manually changed one of the settings through the interface.

Yes, you can either do that manually via the Console or programmatically with a POST request to /v1/projects/{projectId}/settings, where in the request body you provide the deviceId.

So if I want to update the setting just for that device, I should use the second object (the one that includes the deviceId) in the PUT request, correct?

Exactly — if you’re targeting a specific device, use the object that includes a deviceId and send a PUT request to /v1/projects/{projectId}/settings/{settingId}.

From what I understand, if I want to apply a different value for a setting on a specific device, I need to override it with the request /v1/projects/{projectId}/settings. Is that the expected behavior?

You should use a PUT request to the /v1/projects/{projectId}/settings/{settingId} endpoint — the only difference is whether the settingId you provide corresponds to a device-specific override or a project-level setting.