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.

Getting all diagrams

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

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

Creating diagrams

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

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",
    "componentInstances": [
      {
        "ref": "web-app",
        "component": "8hgFyqbE9a6"
      },
      {
        "ref": "database", 
        "component": "hgpKj29kN7A"
      }
    ],
    "relations": [
      {
        "fromComponentInstance": "web-app",
        "toComponentInstance": "database",
        "label": "queries"
      }
    ]
  }
]

Updating diagrams

Update existing diagrams using the POST endpoint with the diagram'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/diagram

Example of updating an existing diagram:

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

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",
      "component": "aB3dE4fG5h6",
      "parentId": "backend-services",
      "position": { "x": 1, "y": 1 }
    },
    {
      "ref": "user-service", 
      "component": "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.
`component?: 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`.
`parent?: 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.
`fromComponentInstance: string`	ID or ref of the source component instance.
`toComponentInstance: string`	ID or ref of the target component instance.
`linksTo?: string[]`	Optional array of diagram IDs 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",
          "component": "eE1d4atd1Og",
          "position": {"x": 0, "y": 0},
          "width": 3,
          "height": 2
        },
        {
          "ref": "api-gateway", 
          "component": "kebvFua3Uxt",
          "position": {"x": 5, "y": 0},
          "width": 2,
          "height": 2
        }
      ],
      "relations": [
        {
          "fromComponentInstance": "web-frontend",
          "toComponentInstance": "api-gateway",
          "label": "API calls"
        }
      ],
      "textareas": [
        {
          "position": {"x": 1, "y": 3},
          "width": 4,
          "text": "User-facing components"
        }
      ]
    }
  ]'

Updating an existing 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 '[
    {
      "id": "existing-diagram-id",
      "name": "Updated Architecture", 
      "desc": "Enhanced system with caching layer",
      "level": "C2",
      "state": "ACTIVE",
      "componentInstances": [
        {
          "ref": "web-app",
          "component": "eE1d4atd1Og",
          "position": {"x": 0, "y": 0},
          "width": 3,
          "height": 2
        },
        {
          "ref": "cache",
          "component": "3KAXkoiYl2z", 
          "position": {"x": 4, "y": 0},
          "width": 2,
          "height": 2
        }
      ],
      "relations": [
        {
          "fromComponentInstance": "web-app",
          "toComponentInstance": "cache", 
          "label": "caches data"
        }
      ]
    }
  ]'

Getting all diagrams​

Creating diagrams​

Updating diagrams​

Advanced​

Automatic Layout and Sizing​

Container Instances and Grouping​

Data Types​

Diagram​

Component Instances​

Text Areas​

Relations​

Examples​

Creating a new diagram​

Updating an existing diagram​