API: Manage Components

/api/external/component   

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

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

Getting all components

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

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

[
  {
    "id": "abcdef123456",
    "name": "Example Component",
    "desc": "Example, a plain text description",
    "state": "ACTIVE",
    "typeSlug": "bcdefg234567",
    "apiContext": "my-context-20260101",
    "attributes": [
      {
        "id": "cdefgh345678",
        "value": "example@revision.app"
      },
      {
        "id": "defghi456789",
        "value": 39
      }
    ]
  }
]

Setting components

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

Creating components

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

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

[
  {
    "name": "Advanced Component",
    "desc": "An advanced component used for very advanced things.",
    "state": "ACTIVE",
    "attributes": [
      {"id": "O0hAiH4tsUn3", "value": true}
    ]
  },
  {
    "id": "5i5UK2BuqwZG",
    "name": "Basic Component"
  },
]

Updating components

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

Updating a component completely overwrites the existing component in-place, partial updates are 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": "p5k9wlMqTyIw",
    "name": "Advanced Component",
    "desc": "An advanced component used for very advanced things.",
    "typeSlug": "FoyfTF4umV9h",
    "apiContext": "my-api-context"
  },
  {
    "id": "5i5UK2BuqwZG",
    "name": "Basic Component"
  },
]

Returned data

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

{"error":"Value for STRING attribute 'NykFht2OdZoO' must be a string."}   

{"error":"Value for LINK attribute 'WHiF0L5NqxoW' must be a valid URL."}     

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.state: Invalid enum value. Expected 'DRAFT' | 'ACTIVE' | 'ARCHIVED', received ''"}     

Here, the second component in the array attempts to pass an ID as a number, and the eighth component is lacking a state.

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

In Revision

Revision will let team members know that a component was updated through the API when editing it, to inform them that changes could potentially be overwritten in the future:

Data Types

Value Description
name: string?      Optional field, the component's name.
id: string?      An internal ID set by Revision. Reuse this to update components.
state: enum?     Optional field, DRAFT | ACTIVE | ARCHIVED, defaults to draft.
desc: string?      Optional field, the component's description in plain text.
typeSlug: string?      Optional field, the slug for this component's type.
apiContext: string?     

Optional field, used to keep track of a payload, so that you know which request last modified the component. 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.

Components created inside of Revision will not have this field set.
attributes: object[]?     Optional field, an array. See below for the object structure.

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

Attributes

Value Description
id: string     The ID of an existing attribute.
value: string | number | boolean | null     A value for the attribute. Must be the correct data type for a given attribute's type, see below.
Attribute Type Data Type Details
STRING     string    Use an empty string ("") for no value.
NUMBER     number    Any number, positive or negative, with or without decimals.
BOOLEAN     boolean    
LINK     string     Has to be a valid URL or an empty string ("").
LIST     string    The name of the list item, e.g. "Medium".
USERLIST     string | null    Has to be the full email address of an organization member, or null. Use null to select no user (called "None" in the Revision dropdown).

More documentation surrounding attribute management is available on the attribute API page.

Example cURL requests for this endpoint:

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

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

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

Related Articles