API: Manage Attributes

/api/external/attribute

This API requires authentication with an API key from your organization. See our API Authentication article for more details.

The attributes API allows for fetching, creating, and updating your organization's attributes. Learn more about attributes on the documentation page for attributes.

Getting all attributes

GET https://your-organization.revision.app/api/external/attribute

This returns a JSON response with an array of all of your attributes, with these types, following this example structure:

[
  {
    "id": "NykFht2OdZoO",
    "type": "STRING",
    "name": "Demo",
    "required": false,
    "apiContext": "2025-10-17 09:26:59",
    "desc": "This is a documentation demo attribute.",
    "forTypes": ["QnAORD5smVpA", "xTzgaWYcZiWw"]
  },
  {
    "id": "9Jogx4rAthg5",
    "type": "LIST",
    "name": "Priority",
    "required": false,
    "list": ["High", "Medium", "Low"],
    "forTypes": []
  },
  {
    "id": "7tIdGBjRjNUV",
    "type": "LINK",
    "name": "Repository",
    "required": false,
    "forTypes": []
  }
]

Setting attributes

You can both create new attributes and update existing ones by using the PUT and POST verbs, respectively. An ID may not be provided when creating an attribute, and updating requires specifying one.

Creating attributes

PUT https://your-organization.revision.app/api/external/attribute

Example of valid data to provide in a PUT request, following these types:

[
  {
    "name": "Demo",
    "desc": "This is a documentation demo attribute.",
    "type": "LINK",
    "forTypes": ["7tIdGBjRjNUV", "QfFl7RPI60t9"],
    "required": true
  }
]

Updating attributes

POST https://your-organization.revision.app/api/external/attributes

Updating an attribute completely overwrites it in-place, partial updates are as such not possible. (That is to say, leaving fields out from a POST request will make them blank in Revision.)


Example of valid data to provide in a POST request, following these types:

[
  {
    "id": "5cW9LmzRZcu",
    "name": "New Demo",
    "desc": "This is an updated documentation demo attribute.",
    "type": "LIST",
    "list": ["First", "Second", "Third"],
    "forTypes": ["7tIdGBjRjNUV"],
    "required": false
  }
]

Returned data

Revision will return the full JSON data for the created attribute(s) if successful, or an error message if it was not. Invalid IDs & types, as well as missing required values or other issues will be returned as errors with descriptions. Examples:

{"error":"Duplicate list values are not allowed, got several of: High"}

{"error":"Type with slug 'Yh7FB31oOLbn' does not exist."}

If you attempt to send invalid JSON data, your will receive a response indicating where your sent data failed its validation. Example:

{"error":"Invalid JSON: 2.id: Expected string, received number, 8.type: Required"}   

Here, the second attribute in the array attempts to pass an ID as a number, and the eighth attribute is lacking its type value.

⚠ If you receive an error, the entire operation has been cancelled, and no changes have been made.

Data Types

Value Description
name: string    The attribute's name.
id: string?    An internal ID set by Revision. Reuse this to update attributes.
type: enum

The attribute's type,

STRING | NUMBER | BOOLEAN | LINK | USERLIST | LIST
desc: string?    Optional field, the attribute's description.
forTypes: string[]?    Optional field, an array of type slugs to limit the attribute to.
required: boolean? Optional field, whether or not this attribute is required. Defaults to false.
apiContext: string?   

Optional field, used to keep track of a payload, so that you know which request last modified the attribute. We recommend using a unique value, such as an incrementing number or the date/time of the request. Defaults to a date if not provided, in the format of 2026-01-01 01:01:01 .

Attributes created inside of Revision will not have this field set.
list: string[]?   An array required and only permitted when the attribute's type is LIST. The array contains strings of possible list options.

Tip: You can find type slugs by right-clicking types in the type selector.

An image of the type selector in Revision, with an open context menu showing

Example cURL requests for this endpoint:

$ curl https://your-organization.revision.app/api/external/attribute -H "Content-Type: application/json" -H "x-api-key: a0e08cad-184b-48a4-miku-14776a549b79"

$ curl -X PUT https://your-organization.revision.app/api/external/attribute -H "Content-Type: application/json" -H "x-api-key: a0e08cad-184b-48a4-miku-14776a549b79" -d @new-attributes.json

$ curl -X POST https://your-organization.revision.app/api/external/attribute -H "Content-Type: application/json" -H "x-api-key: a0e08cad-184b-48a4-miku-14776a549b79" -d @updated-attributes.json

Related Articles