Manage Components

/api/external/components, /api/external/components/:id

info

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

The components API allows for fetching, creating, and updating a workspace's components.

List All Components

Retrieve a list of all components.

GET https://your-workspace.revision.app/api/external/components

Query Parameters

Parameter	Type	Description
`name`	`string`	Filter by name (case-insensitive substring match).
`typeId`	`string`	Filter by type ID (slug).
`tagId`	`string`	Filter by tag ID (slug or ref).
`attributeId`	`string`	Filter by attribute ID (slug or ref).
`attributeValue`	`string`	Filter by attribute value (requires `attributeId`).
`state`	`string`	Filter by state (`"DRAFT"`, `"ACTIVE"`, `"ARCHIVED"`).

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-workspace.revision.app/api/external/components/{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-workspace.revision.app/api/external/components

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-workspace.revision.app/api/external/components/{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-workspace.revision.app/api/external/components/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.

Delete Component

Not Implemented

This endpoint is not yet implemented and will return a 501 status code.

DELETE https://your-organization.revision.app/api/external/components/{id}

Get Dependencies

Retrieve the upstream and downstream dependencies of a specific component.

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

This returns a JSON response with an array of dependencies:

[
  {
    "component": { "id": "8hgFyqbE9a6", "name": "API Gateway" },
    "direction": "upstream",
    "diagrams": [{ "id": "diag1", "name": "System Overview" }]
  },
  {
    "component": { "id": "hgpKj29kN7A", "name": "Database Service" },
    "direction": "downstream",
    "diagrams": [{ "id": "diag2", "name": "Data Flow" }]
  }
]

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

Filtering components by type

curl -X GET "https://your-organization.revision.app/api/external/components?typeId=eE1d4atd1Og" \
  -H "Authorization: Bearer your-api-key-here"

Getting dependencies for a component

curl -X GET https://your-organization.revision.app/api/external/components/8hgFyqbE9a6/dependencies \
  -H "Authorization: Bearer your-api-key-here"

Creating a new component

curl -X POST https://your-workspace.revision.app/api/external/components \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key-here" \
  -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-workspace.revision.app/api/external/components/8hgFyqbE9a6 \
  -H "Authorization: Bearer a0e08cad-184b-48a4-miku-14776a549b79"

Updating an existing component

curl -X PATCH https://your-workspace.revision.app/api/external/components/8hgFyqbE9a6 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key-here" \
  -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-workspace.revision.app/api/external/components/upsert-batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key-here" \
  -d '[
    {
      "name": "New Service",
      "typeId": "eE1d4atd1Og",
      "state": "ACTIVE"
    },
    {
      "id": "8hgFyqbE9a6",
      "name": "Updated Service",
      "state": "ARCHIVED"
    }
  ]'

List All Components​

Query Parameters​

Get Component​

Create Component​

Update Component​

Upsert Batch Components​

Delete Component​

Get Dependencies​

Data Types​

Examples​

Filtering components by type​

Getting dependencies for a component​

Creating a new component​

Getting a component by ID​

Updating an existing component​

Upserting batch components​