Manage Templates
/api/external/template
This API requires authentication with an API key from your organization. See our API Authentication article for more details.
The Template API allows you to sync 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.
Sync Template
Use this endpoint to sync components and diagrams together. The main benefit is the ability to reference components in diagrams using ref identifiers before the components are actually created.
POST https://your-organization.revision.app/api/external/template
JSON Format
Example of syncing a complete template with components and diagrams:
{
"components": [
{
"id": "web-app",
"name": "Web Application",
"desc": "React frontend",
"state": "ACTIVE",
"linksTo": ["frontend-architecture"]
},
{
"id": "api-layer",
"name": "API Layer",
"desc": "Node.js backend",
"state": "ACTIVE",
"linksTo": ["backend-architecture"]
},
{
"id": "data-store",
"name": "Data Store",
"desc": "PostgreSQL database",
"state": "ACTIVE",
"linksTo": ["data-architecture"]
}
],
"diagrams": [
{
"id": "high-level-view",
"name": "High-Level Architecture",
"desc": "System overview with all components",
"state": "ACTIVE",
"componentInstances": [
{
"ref": "web-1",
"componentId": "web-app"
},
{
"ref": "api-1",
"componentId": "api-layer"
},
{
"ref": "db-1",
"componentId": "data-store"
}
],
"relations": [
{
"fromRef": "web-1",
"toRef": "api-1",
"label": "REST API",
"desc": "Client makes API requests"
},
{
"fromRef": "api-1",
"toRef": "db-1",
"label": "SQL",
"desc": "Database queries"
}
]
},
{
"id": "frontend-architecture",
"name": "Frontend Architecture",
"desc": "Detailed frontend component structure",
"state": "ACTIVE",
"componentInstances": [
{
"ref": "web-detail",
"componentId": "web-app"
}
]
},
{
"id": "backend-architecture",
"name": "Backend Architecture",
"desc": "API layer details",
"state": "ACTIVE",
"componentInstances": [
{
"ref": "api-detail",
"componentId": "api-layer"
}
]
},
{
"id": "data-architecture",
"name": "Data Architecture",
"desc": "Database schema and data flow",
"state": "ACTIVE",
"componentInstances": [
{
"ref": "db-detail",
"componentId": "data-store"
}
]
}
]
}
YAML Format
The Template 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.
When using YAML format, specify the appropriate content type headers:
Content-Type: application/yaml
Accept: application/yaml
Authorization: Bearer your-api-key
Example of syncing a template using YAML:
components:
- id: api-gateway
name: API Gateway
desc: Main entry point for all API requests
state: ACTIVE
- id: auth-service
name: Authentication Service
desc: Handles user authentication and authorization
state: ACTIVE
- id: user-service
name: User Service
desc: Manages user profiles and preferences
state: ACTIVE
diagrams:
- id: system-overview
name: System Architecture Overview
desc: High-level view of the system architecture
level: C1
state: ACTIVE
componentInstances:
- ref: gateway-1
componentId: api-gateway
- ref: auth-1
componentId: auth-service
- ref: user-1
componentId: user-service
relations:
- fromRef: gateway-1
toRef: auth-1
label: HTTPS
- fromRef: gateway-1
toRef: user-1
label: HTTPS
- fromRef: auth-1
toRef: user-1
label: gRPC
Use id fields to identify components and diagrams. Reference component IDs in diagram componentId fields to create cross-references within the same request.
If you receive an error, the entire operation is cancelled, and no changes are made.
Data Structure
The template endpoint accepts a JSON or YAML object with two optional arrays:
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 syncing components and diagrams together, allowing you to reference components in diagrams before the components are created.
Examples
Syncing a template with JSON
curl -X POST https://your-organization.revision.app/api/external/template \
-H "Content-Type: application/json" \
-H "Authorization: Bearer a0e08cad-184b-48a4-miku-14776a549b79" \
-d '{
"components": [
{
"id": "frontend-app",
"name": "Frontend Application",
"desc": "React-based user interface",
"state": "ACTIVE"
},
{
"id": "api-service",
"name": "API Service",
"desc": "Main backend API service",
"state": "ACTIVE"
}
],
"diagrams": [
{
"id": "app-architecture",
"name": "Application Architecture",
"desc": "Frontend to backend architecture",
"level": "C2",
"state": "ACTIVE",
"componentInstances": [
{
"ref": "frontend-inst",
"componentId": "frontend-app"
},
{
"ref": "api-inst",
"componentId": "api-service"
}
],
"relations": [
{
"fromRef": "frontend-inst",
"toRef": "api-inst",
"label": "API calls"
}
]
}
]
}'
Syncing a template with YAML
curl -X POST https://your-organization.revision.app/api/external/template \
-H "Content-Type: application/yaml" \
-H "Accept: application/yaml" \
-H "Authorization: Bearer a0e08cad-184b-48a4-miku-14776a549b79" \
-d '
components:
- id: api-gateway
name: API Gateway
desc: Main entry point for all API requests
state: ACTIVE
diagrams:
- id: gateway-overview
name: Gateway Architecture
level: C1
state: ACTIVE
componentInstances:
- ref: gateway-1
componentId: api-gateway
'