> For the complete documentation index, see [llms.txt](https://docs.remote.it/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.remote.it/developer-tools/api/usage/custom-attributes.md).

# Custom Attributes

Attach your own metadata to Remote.It users, devices and services with custom attributes, including per-context value overrides.

Attributes can be added to Users, Devices and Services. Attributes can have overrides defined by context. This is used for your own custom metadata.

### Add/Update Attribute

| Parameter | Data Type | Description                                                                                           |
| --------- | --------- | ----------------------------------------------------------------------------------------------------- |
| name      | String    | <p><strong>required</strong></p><p>Name of attribute</p>                                              |
| value     | String    | <p><strong>required</strong></p><p>Value of attribute<br><code>null</code> to remove</p>              |
| serviceId | String    | <p><strong>required</strong></p><p>The userId, deviceId or serviceId the attribute is assigned to</p> |
| context   | String    | defined context of the attribute. Allows for override of attribute value for the same name            |

```graphql
mutation {
  setAttribute(
    name: "CustomAttribute",
    value: "ValueOfAttribute",
    serviceId: "80:00:00:00:12:34:56:78",
    context: "CustomContext"
  )
}
```

Query Response

```graphql
{
  "data": {
    "setAttribute": "ValueOfAttribute"
  }
}
```

### Category and Status Fields

We have reserved names of remote.it Device attributes which will be displayed on the Web Portal and Desktop UIs. These attributes are for Category and Status fields. The UI currently can display Category A-E and Status A-E. These must be set against the Device ID (also known as the Bulk Service's "Service ID" of the remote.it Device). The convention for the name is $remoteit.categoryA for category attributes and $remoteit.statusA for status attributes. The convention is the same for removing and retrieving these attributes.

**Example Category Mutation**

```graphql
mutation {
  setAttribute(
    name: "$remoteit.categoryA",
    value: "my category A value",
    serviceId: "80:00:00:00:12:34:56:78",
  )
}
```

### Remove Attribute

```graphql
mutation {
  setAttribute(
    name: "CustomAttribute",
    value: null,
    serviceId: "80:00:00:00:12:34:56:78",
  )
}
```

### Set Multiple Attributes

This method shows how to update multiple attributes on a single device by passing in a JSON formatted variables.

```graphql
#Query
mutation UpdateMultipleAttributes($attributes: Object!, $serviceId: String!) {
	setAttributes(attributes: $attributes, serviceId: $serviceId)
}

#Variables
{
  "attributes": {
    "$remoteit": {
      "categoryA": "Uptime: 1h, 06m",
      "categoryB": "Version: 1.0",
      "categoryC": "Serial Number: x292jsu2",
      "categoryD": "MAC: AUWS83729A"
    },
    "MoreJsonAttributes": {
      "version": "1.0"
    },
    "StringAttribute": "newvalue"
  },
  "serviceId": "80:00:00:00:01:12:12:12"
}
```

### Retrieve Attributes

```graphql
{
  login {
    attributes #User Attributes
    devices{
      items{
        attributes #Device Attributes
        services{ 
          attributes(context: "customContext") #Service Attributes
        }
      }			
    }
  }
}
```

Query Response

```graphql
{
  "data": {
    "login": {
      "attributes": { #User Attributes
	"newAttribute": "CustomAttributeValue",
	},
     "devices": {
	"items": [
	{
	"attributes": { #Device Attributes
	  "newAttribute": "CustomAttributeValue"
	},
	"services": [
	{
	  "attributes": { #Service Attributes
	     "newAttribute": "ContextAttributeValue"
	   }
	},...]						
	}
	]
      }
    }
  }
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.remote.it/developer-tools/api/usage/custom-attributes.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
