Manage Model

/api/external/model

info

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

---

The Model API allows you to create components and diagrams in a single request, making it possible to set up complete architectures and solutions in one go. This is particularly useful for infrastructure-as-code workflows, automated deployments, and bulk imports.

Creating components and diagrams together

Use this endpoint to create components and diagrams in one go. The main benefit is the ability to reference components in diagrams using refs before the components are actually created.

Create model

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

Example of creating a complete model with components and diagrams:

{
  "components": [
    {
      "ref": "api-gateway",
      "name": "API Gateway",
      "desc": "Main entry point for all API requests",
      "typeId": "eE1d4atd1Og",
      "state": "ACTIVE"
    },
    {
      "ref": "user-service",
      "name": "User Service", 
      "desc": "Handles user management and authentication",
      "typeId": "9e5vdfuqxio",
      "state": "ACTIVE"
    },
    {
      "ref": "database",
      "name": "User Database",
      "desc": "Stores user data and credentials",
      "typeId": "kebvFua3Uxt",
      "state": "ACTIVE"
    }
  ],
  "diagrams": [
    {
      "name": "System Overview",
      "desc": "High-level architecture diagram",
      "state": "ACTIVE",
      "level": "C1",
      "componentInstances": [
        {
          "ref": "gateway-instance",
          "component": "api-gateway",
          "position": { "x": 2, "y": 5 },
          "width": 6,
          "height": 3,
          "isContainer": false
        },
        {
          "ref": "user-instance", 
          "component": "user-service",
          "position": { "x": 12, "y": 2 },
          "width": 5,
          "height": 3,
          "isContainer": false
        },
        {
          "ref": "db-instance",
          "component": "database", 
          "position": { "x": 12, "y": 8 },
          "width": 4,
          "height": 2,
          "isContainer": false
        }
      ],
      "relations": [
        {
          "fromComponentInstance": "gateway-instance",
          "toComponentInstance": "user-instance",
          "label": "Routes user requests",
          "desc": "HTTP requests for user operations"
        },
        {
          "fromComponentInstance": "user-instance",
          "toComponentInstance": "db-instance",
          "label": "Queries user data"
        }
      ],
      "textareas": [
        {
          "position": { "x": 2, "y": 12 },
          "width": 8,
          "text": "Core user management system\nHandles authentication and data storage"
        }
      ]
    }
  ]
}

Reference System

Learn about Create vs Update to understand how ref fields work for cross-referencing within requests.

warning

If you receive an error, the entire operation has been cancelled, and no changes have been made.

Data Structure

The model endpoint accepts a JSON object with two optional arrays. Both use the same data types as their individual API endpoints:

• components: Array of component objects. See Components API Data Types for full field definitions.
• diagrams: Array of diagram objects. See Diagrams API Data Types for full field definitions.

The main benefit is creating components and diagrams together, allowing you to reference components in diagrams before the components are created.

---

Examples

Creating a complete microservices architecture

curl -X POST https://your-organization.revision.app/api/external/model \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer a0e08cad-184b-48a4-miku-14776a549b79" \
  -d '{
    "components": [
      {
        "ref": "frontend-app",
        "name": "Frontend Application",
        "desc": "React-based user interface",
        "typeId": "eE1d4atd1Og",
        "state": "ACTIVE"
      },
      {
        "ref": "api-service",
        "name": "API Service",
        "desc": "Main backend API service",
        "typeId": "9e5vdfuqxio",
        "state": "ACTIVE"
      }
    ],
    "diagrams": [
      {
        "name": "Application Architecture",
        "desc": "Frontend to backend architecture",
        "level": "C2",
        "state": "ACTIVE",
        "componentInstances": [
          {
            "ref": "frontend-inst",
            "component": "frontend-app",
            "position": {"x": 0, "y": 0},
            "width": 4,
            "height": 2
          },
          {
            "ref": "api-inst", 
            "component": "api-service",
            "position": {"x": 8, "y": 0},
            "width": 4,
            "height": 2
          }
        ],
        "relations": [
          {
            "fromComponentInstance": "frontend-inst",
            "toComponentInstance": "api-inst",
            "label": "API calls"
          }
        ]
      }
    ]
  }'

YAML Format Support

The model API supports YAML format as an alternative to JSON. YAML can be particularly useful in build pipelines, infrastructure-as-code workflows, and CI/CD environments where YAML is the natural choice for configuration files.

Headers required for YAML

When using YAML format, specify the appropriate content type headers:

Content-Type: application/yaml
Accept: application/yaml
Authorization: Bearer your-api-key

Creating a model using YAML

components:
  - ref: api-gateway
    name: API Gateway
    desc: Main entry point for all API requests
    typeId: eE1d4atd1Og
    state: ACTIVE

  - ref: auth-service
    name: Authentication Service
    desc: Handles user authentication and authorization
    typeId: 9e5vdfuqxio
    state: ACTIVE

diagrams:
  - name: System Architecture
    desc: Overview of the system architecture
    level: C1
    componentInstances:
      - ref: gateway-1
        component: api-gateway
      
      - ref: auth-1
        component: auth-service
    
    relations:
      - fromComponentInstance: gateway-1
        toComponentInstance: auth-1
        label: "HTTPS"