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.

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, 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"
  }
]

Creating components

Create new components using the POST endpoint without providing an id field.

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

Example of creating a new component:

[
  {
    "name": "Demo Component",
    "desc": "This is a documentation demo component.",
    "typeId": "eE1d4atd1Og"
  }
]

Example of creating multiple components:

[
  {
    "name": "Brand new component",
    "typeId": "eE1d4atd1Og"
  },
  {
    "name": "Another new component", 
    "desc": "With description",
    "typeId": "kebvFua3Uxt"
  }
]

Updating components

Update existing components using the POST endpoint with the component's id or ref field.

Create vs Update

Learn about Create vs Update to understand how to identify resources for create and update operations.

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

Example of updating an existing component:

[
  {
    "id": "8hgFyqbE9a6",
    "name": "Updated Component Name",
    "desc": "This is an updated documentation demo component.",
    "typeId": "kebvFua3Uxt",
    "state": "ARCHIVED",
    "attributes": [
      {
        "id": "5cW9LmzRZcu",
        "value": "Updated Value"
      }
    ]
  }
]

Create vs Update

Learn about Create vs Update to understand partial updates and field modification.

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"
        }
      ]
    }
  ]'

Updating an existing 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 '[
    {
      "id": "eE1d4atd1Og",
      "name": "Enhanced Auth Service",
      "desc": "Updated authentication service with OAuth2 support", 
      "typeId": "kebvFua3Uxt",
      "state": "ACTIVE",
      "attributes": [
        {
          "id": "5cW9LmzRZcu",
          "value": "Staging"
        }
      ]
    }
  ]'