Try free
Documentation
API

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

ParameterTypeDescription
namestringFilter by name (case-insensitive substring match).
typeIdstringFilter by type ID (slug).
tagIdstringFilter by tag ID (slug or ref).
attributeIdstringFilter by attribute ID (slug or ref).
attributeValuestringFilter by attribute value (requires attributeId).
statestringFilter 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

ValueDescription
id?: stringSystem-generated ID. Use this to update existing components.
ref?: stringUser-defined identifier. Use this for custom identification.
name: stringThe component's name.
desc?: stringOptional description of the component.
state?: stringComponent state: "DRAFT", "ACTIVE", or "ARCHIVED". Defaults to "DRAFT".
typeId?: stringThe ID of the type assigned to this component.
apiContext?: stringOptional 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"
    }
  ]'

Authentication

Learn how to authenticate with the Revision API using API keys. Get started with secure programmatic access to your architecture data.

Manage Attributes

API reference for managing attributes in Revision. Learn to create, update, and configure custom metadata fields for your architecture components.

On this page

Manage ComponentsList All ComponentsQuery ParametersGet ComponentCreate ComponentUpdate ComponentUpsert Batch ComponentsDelete ComponentGet DependenciesData TypesExamplesFiltering components by typeGetting dependencies for a componentCreating a new componentGetting a component by IDUpdating an existing componentUpserting batch components

Product

Compare

Resources

© 2026 Revision

Data & privacy policySecurityTerms of Service