Manage Diagrams

/api/external/diagram

info

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

The diagrams API allows for fetching, creating, and updating your organization's diagrams.

List All Diagrams

Retrieve a list of all diagrams.

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

This returns a JSON response with an array of all of your diagrams, including basic diagram information and their contained elements.

Get Diagram

Retrieve a specific diagram by ID.

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

This returns a JSON response with the diagram and all its component instances, relations, and text areas.

Response Types

You can receive either JSON or SVG data from this endpoint by specifying your preference in an Accept header.

The following response types are available:

application/json (JSON)
application/svg+xml (SVG)

When requesting an SVG, Revision will generate an image of the current state of the diagram.

If an Accept header is not provided, or is invalid, JSON data will be returned by default.

Create Diagram

Create a new diagram.

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

Example of creating a new diagram:

{
  "name": "System Overview",
  "desc": "High-level system architecture",
  "level": "C1",
  "state": "ACTIVE",
  "componentInstances": [
    {
      "ref": "web-app",
      "componentId": "8hgFyqbE9a6"
    },
    {
      "ref": "database",
      "componentId": "hgpKj29kN7A"
    }
  ],
  "relations": [
    {
      "fromRef": "web-app",
      "toRef": "database",
      "label": "queries"
    }
  ]
}

Update Diagram

Update an existing diagram.

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

Example of updating an existing diagram:

{
  "name": "Updated System Overview",
  "desc": "Modified architecture diagram",
  "level": "C2",
  "componentInstances": [
    {
      "ref": "updated-web-app",
      "componentId": "8hgFyqbE9a6",
      "position": { "x": 1, "y": 1 },
      "width": 4,
      "height": 3
    },
    {
      "ref": "cache-layer",
      "componentId": "xK9mP2nQ5r7"
    }
  ],
  "relations": [
    {
      "fromRef": "updated-web-app",
      "toRef": "cache-layer",
      "label": "caches data"
    }
  ]
}

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 Diagrams

Create or update multiple diagrams in a single batch operation.

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

Example of upserting multiple diagrams:

[
  {
    "name": "New Diagram",
    "level": "C1",
    "componentInstances": [
      {
        "ref": "service-1",
        "componentId": "8hgFyqbE9a6"
      }
    ]
  },
  {
    "id": "existing-diagram-id",
    "name": "Updated Diagram",
    "level": "C2",
    "state": "ACTIVE"
  }
]

tip

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

Advanced

Automatic Layout and Sizing

Component instances support both manual positioning/sizing and automatic layout:

Position: If a position field is provided with x and y coordinates, the component will be placed at that exact location on the diagram grid. If no position is specified, Revision will automatically layout the component instance in an optimal position.

Size: If width and height fields are provided, the component will use those exact dimensions. If size fields are omitted, Revision will automatically determine appropriate sizing for the component instance.

This allows for flexible diagram creation where you can specify exact placement for critical components while letting Revision handle layout for others.

Container Instances and Grouping

Component instances with isContainer: true act as parent containers that can group other components. Containers are visually rendered as dotted boundary boxes surrounding their child components in the diagram.

To establish parent-child relationships:

Set isContainer: true on the parent component instance
Reference the container's id (or ref during creation) in other component instances' parentId field

Child components positioned inside a container will be visually grouped within the container's dotted boundary. This is useful for representing system boundaries, microservice groups, or architectural layers.

{
  "componentInstances": [
    {
      "ref": "backend-services",
      "placeholder": "Backend Services",
      "isContainer": true,
      "position": { "x": 0, "y": 0 },
      "width": 10,
      "height": 6
    },
    {
      "ref": "auth-service",
      "componentId": "aB3dE4fG5h6",
      "parentId": "backend-services",
      "position": { "x": 1, "y": 1 }
    },
    {
      "ref": "user-service",
      "componentId": "iJ7kL8mN9o0",
      "parentId": "backend-services",
      "position": { "x": 6, "y": 1 }
    }
  ]
}

Data Types

Diagram

Value	Description
`id?: string`	System-generated ID. Use this to update existing diagrams.
`ref?: string`	User-defined identifier. Use this for custom identification.
`name: string`	The diagram's name.
`desc?: string`	Optional description of the diagram.
`state?: string`	Diagram state: `"DRAFT"`, `"ACTIVE"`, or `"ARCHIVED"`. Defaults to `"DRAFT"`.
`level: string`	Diagram level following C4 model: `"C1"`, `"C2"`, `"C3"`, or `"C4"`.
`url?: string`	Read-only URL to view the diagram in Revision.
`tags?: object[]`	Optional array of tag objects associated with the diagram.
`componentInstances?: object[]`	Optional array of component instance objects placed on the diagram.
`textareas?: object[]`	Optional array of text areas for annotations on the diagram.
`relations?: object[]`	Optional array of relation objects connecting component instances.

Component Instances

A diagram is primarily made up of component instances. Both components and containers are instances, differentiated by the isContainer boolean. Components may have a parent, but containers can not.

Component instances can have a given component ID, but it is not mandatory. We refer to instances without a component as placeholders. If an instance does not have an assigned component, it has a placeholder string instead.

Value	Description
`id?: string`	System-generated ID for the component instance. Used for connecting with relations.
`ref?: string`	User-defined reference identifier for the component instance.
`componentId?: string`	ID or ref of the component to instantiate on the diagram.
`placeholder?: string`	Optional text to display when no component is assigned.
`isContainer?: boolean`	Whether this instance acts as a container for other instances. Defaults to `false`.
`parentId?: string`	ID or ref of the parent container instance.
`position?: { x: number, y: number }`	X (left-right) and Y (up-down) positions in the editor grid. Whole number, can be negative. Omit to let Revision automatically layout this instance.
`width?: number`	Width of the component instance. Whole number, min `1`, max `100`.
`height?: number`	Height of the component instance. Whole number, min `1`, max `100`.

As none of the fields are required, you can provide an empty object ({}) to create a generic placeholder.

Text Areas

Value	Description
`position: { x: number, y: number }`	X (left-right) and Y (up-down) positions in the editor grid. Whole number, can be negative. Omit to let Revision automatically layout this instance.
`width?: number`	Width of the text area. Whole number, minimum `1`, maximum `100`.
`text?: string`	Plain text representation of the text area's text content.

warning

Text areas do not have a height. Their height is determined by the lines of text in them.

Relations

Value	Description
`label?: string`	Plain text representation of the relation's label.
`desc?: string`	Plain text representation of the relation's long-form description.
`fromRef: string`	ID or ref of the source component instance.
`toRef: string`	ID or ref of the target component instance.
`linksTo?: string[]`	Optional array of diagram IDs or refs that this relation links to.

Examples

Creating a new diagram

curl -X POST https://your-organization.revision.app/api/external/diagram \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer a0e08cad-184b-48a4-miku-14776a549b79" \
  -d '{
    "name": "System Architecture Overview",
    "desc": "High-level view of our microservices architecture",
    "level": "C1",
    "state": "ACTIVE",
    "componentInstances": [
      {
        "ref": "web-frontend",
        "componentId": "eE1d4atd1Og",
        "position": {"x": 0, "y": 0},
        "width": 3,
        "height": 2
      },
      {
        "ref": "api-gateway",
        "componentId": "kebvFua3Uxt",
        "position": {"x": 5, "y": 0},
        "width": 2,
        "height": 2
      }
    ],
    "relations": [
      {
        "fromRef": "web-frontend",
        "toRef": "api-gateway",
        "label": "API calls"
      }
    ],
    "textareas": [
      {
        "position": {"x": 1, "y": 3},
        "width": 4,
        "text": "User-facing components"
      }
    ]
  }'

Getting a diagram by ID

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

Updating an existing diagram

curl -X PATCH https://your-organization.revision.app/api/external/diagram/existing-diagram-id \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer a0e08cad-184b-48a4-miku-14776a549b79" \
  -d '{
    "name": "Updated Architecture",
    "desc": "Enhanced system with caching layer",
    "level": "C2",
    "state": "ACTIVE",
    "componentInstances": [
      {
        "ref": "web-app",
        "componentId": "eE1d4atd1Og",
        "position": {"x": 0, "y": 0},
        "width": 3,
        "height": 2
      },
      {
        "ref": "cache",
        "componentId": "3KAXkoiYl2z",
        "position": {"x": 4, "y": 0},
        "width": 2,
        "height": 2
      }
    ],
    "relations": [
      {
        "fromRef": "web-app",
        "toRef": "cache",
        "label": "caches data"
      }
    ]
  }'

Upserting batch diagrams

curl -X PATCH https://your-organization.revision.app/api/external/diagram/upsert-batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer a0e08cad-184b-48a4-miku-14776a549b79" \
  -d '[
    {
      "name": "New Diagram",
      "level": "C1",
      "state": "ACTIVE"
    },
    {
      "id": "existing-diagram-id",
      "name": "Updated Diagram",
      "level": "C2"
    }
  ]'

List All Diagrams​

Get Diagram​

Response Types​

Create Diagram​

Update Diagram​

Upsert Batch Diagrams​

Advanced​

Automatic Layout and Sizing​

Container Instances and Grouping​

Data Types​

Diagram​

Component Instances​

Text Areas​

Relations​

Examples​

Creating a new diagram​

Getting a diagram by ID​

Updating an existing diagram​

Upserting batch diagrams​