Manage Components

/api/external/component

info

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.

List All Components

Retrieve a list of all components.

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

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

[
  {
    "id": "8hgFyqbE9a6",
    "name": "Demo Component",
    "desc": "This is a documentation demo component.",
    "typeId": "eE1d4atd1Og",
    "state": "ACTIVE",
    "attributes": [
      {
        "id": "5cW9LmzRZcu",
        "value": "Second"
      }
    ]
  },
  {
    "id": "hgpKj29kN7A",
    "name": "Second Demo Component", 
    "desc": null,
    "typeId": "9e5vdfuqxio",
    "state": "ACTIVE",
    "attributes": [],
    "apiContext": "2026-01-01 01:01:01"
  }
]

Get Component

Retrieve a specific component by ID.

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

This returns a JSON response with the component:

{
  "id": "8hgFyqbE9a6",
  "name": "Demo Component",
  "desc": "This is a documentation demo component.",
  "typeId": "eE1d4atd1Og",
  "state": "ACTIVE",
  "attributes": [
    {
      "id": "5cW9LmzRZcu",
      "value": "Second"
    }
  ]
}

Create Component

Create a new component.

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

Example of creating a new component:

{
  "name": "User Authentication Service",
  "desc": "Handles user login, logout, and session management",
  "typeId": "eE1d4atd1Og",
  "state": "ACTIVE",
  "attributes": [
    {
      "id": "5cW9LmzRZcu",
      "value": "Production"
    }
  ]
}

Update Component

Update an existing component.

PATCH https://your-organization.revision.app/api/external/component/{id}

Example of updating an existing component:

{
  "name": "Enhanced Auth Service",
  "desc": "Updated authentication service with OAuth2 support",
  "typeId": "kebvFua3Uxt",
  "state": "ACTIVE",
  "attributes": [
    {
      "id": "5cW9LmzRZcu",
      "value": "Staging"
    }
  ]
}

Partial Updates

When updating, you only need to send the fields you want to change. Omitted fields remain unchanged. Set a field to null to clear its value.

Upsert Batch Components

Create or update multiple components in a single batch operation.

PATCH https://your-organization.revision.app/api/external/component/upsert-batch

Example of upserting multiple components:

[
  {
    "name": "Brand new component",
    "typeId": "eE1d4atd1Og"
  },
  {
    "id": "8hgFyqbE9a6",
    "name": "Updated Component Name",
    "desc": "This is an updated documentation demo component.",
    "typeId": "kebvFua3Uxt",
    "state": "ARCHIVED"
  },
  {
    "name": "Another new component",
    "desc": "With description",
    "typeId": "kebvFua3Uxt"
  }
]

tip

In batch operations, include an id or ref to update an existing component, or omit both to create a new one.

Data Types

Value	Description
`id?: string`	System-generated ID. Use this to update existing components.
`ref?: string`	User-defined identifier. Use this for custom identification.
`name: string`	The component's name.
`desc?: string`	Optional description of the component.
`state?: string`	Component state: `"DRAFT"`, `"ACTIVE"`, or `"ARCHIVED"`. Defaults to `"DRAFT"`.
`typeId?: string`	The ID of the type assigned to this component.
`apiContext?: string`	Optional tracking field. Defaults to current timestamp in format `2026-01-01 01:01:01`.
`linksTo?: string[]`	Optional array of component IDs that this component links to.
`attributes?: object[]`	Optional array of attribute objects with `id` and `value` properties.

Examples

Creating a new component

curl -X POST https://your-organization.revision.app/api/external/component \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer a0e08cad-184b-48a4-miku-14776a549b79" \
  -d '{
    "name": "User Authentication Service",
    "desc": "Handles user login, logout, and session management",
    "typeId": "eE1d4atd1Og",
    "state": "ACTIVE",
    "attributes": [
      {
        "id": "5cW9LmzRZcu",
        "value": "Production"
      }
    ]
  }'

Getting a component by ID

curl -X GET https://your-organization.revision.app/api/external/component/8hgFyqbE9a6 \
  -H "Authorization: Bearer a0e08cad-184b-48a4-miku-14776a549b79"

Updating an existing component

curl -X PATCH https://your-organization.revision.app/api/external/component/8hgFyqbE9a6 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer a0e08cad-184b-48a4-miku-14776a549b79" \
  -d '{
    "name": "Enhanced Auth Service",
    "desc": "Updated authentication service with OAuth2 support",
    "typeId": "kebvFua3Uxt",
    "state": "ACTIVE",
    "attributes": [
      {
        "id": "5cW9LmzRZcu",
        "value": "Staging"
      }
    ]
  }'

Upserting batch components

curl -X PATCH https://your-organization.revision.app/api/external/component/upsert-batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer a0e08cad-184b-48a4-miku-14776a549b79" \
  -d '[
    {
      "name": "New Service",
      "typeId": "eE1d4atd1Og",
      "state": "ACTIVE"
    },
    {
      "id": "8hgFyqbE9a6",
      "name": "Updated Service",
      "state": "ARCHIVED"
    }
  ]'

List All Components​

Get Component​

Create Component​

Update Component​

Upsert Batch Components​

Data Types​

Examples​

Creating a new component​

Getting a component by ID​

Updating an existing component​

Upserting batch components​