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.

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:

[
  {
    "name": "Example Component",
    "id": "39",
    "desc": "Example, a plain text description",
    "typeSlug": "abcd1234",
    "apiContext": "my-context-20250613"
  }
]

Setting components

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

You can both create new components and update existing ones by supplying unique or existing component IDs. Using an existing ID completely overwrites the existing component, partial updates are not possible.


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

[
    {
        "name": "Advanced Component",
        "id": "comp-001",
        "desc": "An advanced component used for very advanced things."
        "typeSlug": "abcd1234",
        "apiContext": "my-api-context"
    },
    {
        "name": "Basic Component",
        "id": "comp-002",
        "apiContext": "my-api-context"
    },
]

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.apiContext: Required"}

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


⚠ If any types in the sent components do not exist, you will receive an error, the entire operation will be cancelled, and no changes will be made.

Data Types

Value Description
name: string The component's name.
id: number An internal ID. Reuse this to update an existing component.
desc: string? Optional field, the component's description in plain text.
typeSlug: string? Optional field, the slug for this component's type.
apiContext: string 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, but we do not enforce this.

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/component -H "Content-Type: application/json" -H "x-api-key: a0e08cad-184b-48a4-miku-14776a549b79"

$ 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 @components.json

Related Articles