Manage Components

/api/external/components

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, updating, and deleting your organization's components.

List All Components

Retrieve a list of all components.

GET https://your-organization.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-organization.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-organization.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-organization.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-organization.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`.
`inlineDesc?: boolean`	Whether to display the description inline on diagrams. Defaults to `false`.
`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-organization.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-organization.revision.app/api/external/components/8hgFyqbE9a6 \
  -H "Authorization: Bearer your-api-key-here"

Updating an existing component

curl -X PATCH https://your-organization.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-organization.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​