Back to Details

revision-external-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Revision External API

Revision External API

REST API for managing architecture documentation in Revision workspaces.
用于管理Revision工作区中架构文档的REST API。

Prerequisites

前提条件

Before making any API calls, the user must provide two things:
  1. Organization URL: Each organization has its own subdomain, e.g. 
    https://acme-company.revision.app/
    . This is the base URL for all API requests. Always ask the user for their organization URL — there is no default.
  2. API key: A Bearer token from the workspace settings.
在发出任何API调用之前，用户必须提供两项信息：
  1. 组织URL：每个组织都有自己的子域名，例如 
    https://acme-company.revision.app/
    。这是所有API请求的基础URL。务必向用户索要他们的组织URL——没有默认值。
  2. API密钥：来自工作区设置的Bearer令牌。

Authentication

身份验证

All requests require a Bearer token (API key from workspace settings):
Authorization: Bearer <api-key>
所有请求都需要Bearer令牌（来自工作区设置的API密钥）：
Authorization: Bearer <api-key>

Base URL

基础URL

The base URL is the organization's own Revision URL. Every organization has a unique subdomain:
https://{organization}.revision.app
For example: 
https://acme-company.revision.app
Important: Do not use a generic URL. Always use the organization-specific subdomain provided by the user.
基础URL是组织专属的Revision URL。每个组织都有唯一的子域名：
https://{organization}.revision.app
例如：
https://acme-company.revision.app
重要提示：不要使用通用URL。务必使用用户提供的组织专属子域名。

Resources

资源

ResourceEndpointsDescription
ComponentsCRUD + batch upsert + filterArchitecture components (services, databases, etc.)
DiagramsCRUD + batch upsert + filterArchitecture diagrams with component instances, relations, textareas
AttributesCRUD + batch upsertCustom attribute definitions on components
TagsCRUD + batch upsertTags for categorizing diagrams
TypesRead-onlyComponent type definitions
TemplatePOSTBulk sync of components + diagrams in a single transaction
资源端点描述
组件CRUD + 批量插入更新 + 过滤架构组件（服务、数据库等）
图表CRUD + 批量插入更新 + 过滤包含组件实例、关系、文本区域的架构图表
属性CRUD + 批量插入更新组件上的自定义属性定义
标签CRUD + 批量插入更新用于分类图表的标签
类型只读组件类型定义
模板POST在单个事务中批量同步组件和图表

Quick Start

快速开始

List components

列出组件

bash
curl -H "Authorization: Bearer $API_KEY" \
  https://acme-company.revision.app/api/external/components
bash
curl -H "Authorization: Bearer $API_KEY" \
  https://acme-company.revision.app/api/external/components

Create a component

创建组件

bash
curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "User Service", "state": "ACTIVE"}' \
  https://acme-company.revision.app/api/external/components
bash
curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "User Service", "state": "ACTIVE"}' \
  https://acme-company.revision.app/api/external/components

Create a component with a predictable ID

创建带可预测ID的组件

bash
curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "user-service", "name": "User Service", "state": "ACTIVE"}' \
  https://acme-company.revision.app/api/external/components
bash
curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "user-service", "name": "User Service", "state": "ACTIVE"}' \
  https://acme-company.revision.app/api/external/components

Update a component

更新组件

bash
curl -X PATCH -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "User Service", "state": "ACTIVE", "desc": "Handles user auth"}' \
  https://acme-company.revision.app/api/external/components/component-id
bash
curl -X PATCH -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "User Service", "state": "ACTIVE", "desc": "Handles user auth"}' \
  https://acme-company.revision.app/api/external/components/component-id

Standard CRUD Pattern

标准CRUD模式

Every resource (components, diagrams, attributes, tags) follows the same pattern:
MethodPathAction
GET
/api/external/{resource}
List all (with optional query filters on components, diagrams, types)
POST
/api/external/{resource}
Create (single item)
GET
/api/external/{resource}/{id}
Get by ID
PATCH
/api/external/{resource}/{id}
Update by ID
PATCH
/api/external/{resource}/upsert-batch
Batch upsert (items with 
id
are updated, without are created)
Note: DELETE endpoints exist but are not yet implemented (return 501).
ID behavior: If you provide an 
id
when creating, that exact ID is used (predictable). If you omit 
id
, one is auto-generated. Providing a predictable 
id
is useful when you need to reference the resource elsewhere (e.g. a component's 
id
in a component instance's 
componentId
).
Create requests accept a single object (not an array). Returns 201 on success.
Batch upsert is the most powerful pattern: send items with 
id
to update, without 
id
to create, all in one request.
所有资源（组件、图表、属性、标签）都遵循相同的模式：
方法路径操作
GET
/api/external/{resource}
列出所有资源（组件、图表、类型支持可选查询过滤）
POST
/api/external/{resource}
创建（单个项目）
GET
/api/external/{resource}/{id}
根据ID获取资源
PATCH
/api/external/{resource}/{id}
根据ID更新资源
PATCH
/api/external/{resource}/upsert-batch
批量插入更新（带
id
的项目会被更新，不带
id
的会被创建）
注意：DELETE端点存在但尚未实现**（返回501）。**
ID行为：如果在创建时提供
id
，则会使用该确切ID（可预测）。如果省略
id
，则会自动生成一个。当你需要在其他地方引用该资源时（例如组件实例的
componentId
中引用组件的
id
），提供可预测的
id
会很有用。
创建请求接受单个对象（而非数组）。成功时返回201。
批量插入更新是最强大的模式：发送带
id
的项目进行更新，不带
id
的项目进行创建，所有操作在一个请求中完成。

Component Schema

组件Schema

json
{
  "id": "string",
  "name": "string",
  "state": "DRAFT | ACTIVE | ARCHIVED",
  "desc": "string | null",
  "inlineDesc": false,
  "typeId": "string | null",
  "apiContext": "string",
  "attributes": [{ "id": "string", "value": "boolean | number | string | null" }],
  "linksTo": ["diagram-id-1", "diagram-id-2"]
}
  • id
    : Optional on create — provide it for a predictable ID, omit for auto-generated
  • apiContext
    : Optional label to group related imports (defaults to current UTC timestamp if omitted)
  • linksTo
    : Array of diagram IDs this component links to
  • attributes
    : Component attribute values (reference attribute definitions by 
    id
    )
json
{
  "id": "string",
  "name": "string",
  "state": "DRAFT | ACTIVE | ARCHIVED",
  "desc": "string | null",
  "inlineDesc": false,
  "typeId": "string | null",
  "apiContext": "string",
  "attributes": [{ "id": "string", "value": "boolean | number | string | null" }],
  "linksTo": ["diagram-id-1", "diagram-id-2"]
}
  • id
    ：创建时可选——提供它以使用可预测的ID，省略则自动生成
  • apiContext
    ：用于分组相关导入的可选标签（如果省略，默认为当前UTC时间戳）
  • linksTo
    ：此组件链接到的图表ID数组
  • attributes
    ：组件属性值（通过
    id
    引用属性定义）

Diagram Schema

图表Schema

json
{
  "id": "string",
  "name": "string",
  "state": "DRAFT | ACTIVE | ARCHIVED",
  "url": "string",
  "desc": "string | null",
  "level": "C0 | C1 | C2 | C3 | C4 | D1 | P0 | null",
  "tags": ["tag-id-1"],
  "apiContext": "string",
  "componentInstances": [],
  "relations": [],
  "textareas": []
}
json
{
  "id": "string",
  "name": "string",
  "state": "DRAFT | ACTIVE | ARCHIVED",
  "url": "string",
  "desc": "string | null",
  "level": "C0 | C1 | C2 | C3 | C4 | D1 | P0 | null",
  "tags": ["tag-id-1"],
  "apiContext": "string",
  "componentInstances": [],
  "relations": [],
  "textareas": []
}

Diagram Levels

图表层级

LevelMeaning
C0Landscape
C1System Context
C2Container
C3Component
C4Code
D1Deployment
P0Process
层级含义
C0全景图
C1系统上下文
C2容器
C3组件
C4代码
D1部署
P0流程

Component Instances

组件实例

A component is part of the architecture model — a reusable entity that can be referenced across many diagrams. A component instance is a visual placeholder on a diagram. It can optionally link to a component via 
componentId
, but it doesn't have to — unlinked instances are just standalone placeholders with a name and type.
Two types:
Important: 
position
, 
width
, and 
height
are all optional. When omitted, Revision will automatically lay out and size the instances. Prefer omitting them unless the user explicitly asks for specific positioning or sizing — auto-layout produces better results.
Non-container (default):
json
{
  "ref": "unique-ref",
  "componentId": "component-id | null",
  "parent": "container-ref",
  "isContainer": false,
  "placeholder": { "text": "Name", "typeId": "type-id" }
}
Container (groups other instances):
json
{
  "ref": "unique-ref",
  "componentId": "component-id | null",
  "isContainer": true,
  "placeholder": { "text": "Name", "typeId": "type-id" }
}
  • ref
    is required and must be unique within the diagram
  • componentId
    links the instance to a component definition (null for placeholders)
  • Non-containers can reference a 
    parent
    container via the container's 
    ref
  • Containers cannot have a parent
  • position
    , 
    width
    , 
    height
    are optional — omit them to let Revision auto-layout and auto-size
组件是架构模型的一部分——可在多个图表中引用的可重用实体。组件实例是图表上的可视化占位符。它可以通过
componentId
可选地链接到组件，但不是必须的——未链接的实例只是带有名称和类型的独立占位符。
两种类型：
重要提示：
position
、
width
和
height
都是可选的。省略时，Revision会自动布局和调整实例大小。除非用户明确要求特定的位置或大小，否则建议省略这些参数——自动布局的效果更好。
非容器（默认）：
json
{
  "ref": "unique-ref",
  "componentId": "component-id | null",
  "parent": "container-ref",
  "isContainer": false,
  "placeholder": { "text": "Name", "typeId": "type-id" }
}
容器（用于分组其他实例）：
json
{
  "ref": "unique-ref",
  "componentId": "component-id | null",
  "isContainer": true,
  "placeholder": { "text": "Name", "typeId": "type-id" }
}
  • ref
    是必填项，且在图表内必须唯一
  • componentId
    将实例链接到组件定义（占位符为null）
  • 非容器可以通过容器的
    ref
    引用
    parent
    容器
  • 容器不能有父容器
  • position
    、
    width
    、
    height
    是可选的——省略这些参数让Revision自动布局和调整大小

Relations

关系

Directed edges between component instances:
json
{
  "fromRef": "instance-ref-1",
  "toRef": "instance-ref-2",
  "label": "string | null",
  "desc": "string | null",
  "linksTo": ["diagram-id"]
}
组件实例之间的有向边：
json
{
  "fromRef": "instance-ref-1",
  "toRef": "instance-ref-2",
  "label": "string | null",
  "desc": "string | null",
  "linksTo": ["diagram-id"]
}

Textareas

文本区域

Free text on diagrams:
json
{
  "position": { "x": 100, "y": 100 },
  "width": 300,
  "text": "string | null"
}
图表上的自由文本：
json
{
  "position": { "x": 100, "y": 100 },
  "width": 300,
  "text": "string | null"
}

Attribute Schema

属性Schema

Custom fields on components:
json
{
  "id": "string",
  "name": "string",
  "desc": "string | null",
  "type": "STRING | NUMBER | BOOLEAN | LINK | USERLIST | LIST",
  "list": ["option1", "option2"],
  "forTypes": ["type-id-1"],
  "required": false,
  "apiContext": "string"
}
  • list
    is only valid when 
    type
    is 
    LIST
    (and required for LIST)
  • forTypes
    : Restrict attribute to specific component types
组件上的自定义字段：
json
{
  "id": "string",
  "name": "string",
  "desc": "string | null",
  "type": "STRING | NUMBER | BOOLEAN | LINK | USERLIST | LIST",
  "list": ["option1", "option2"],
  "forTypes": ["type-id-1"],
  "required": false,
  "apiContext": "string"
}
  • list
    仅在
    type
    为
    LIST
    时有效（且是LIST类型的必填项）
  • forTypes
    ：将属性限制为特定组件类型

Tag Schema

标签Schema

json
{
  "id": "string",
  "name": "string",
  "desc": "string | null",
  "color": "gray | red | orange | yellow | green | blue | purple",
  "apiContext": "string"
}
json
{
  "id": "string",
  "name": "string",
  "desc": "string | null",
  "color": "gray | red | orange | yellow | green | blue | purple",
  "apiContext": "string"
}

Type Schema (Read-Only)

类型Schema（只读）

json
{
  "id": "string",
  "name": "string"
}
Types are managed in the Revision UI. List via 
GET /api/external/types
. Supports optional 
name
query parameter for filtering.
json
{
  "id": "string",
  "name": "string"
}
类型在Revision UI中管理。通过
GET /api/external/types
列出。支持可选的
name
查询参数进行过滤。

Template Sync

模板同步

Bulk sync components and diagrams in a single transaction:
bash
curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"components": [...], "diagrams": [...]}' \
  https://acme-company.revision.app/api/external/template
Accepts both JSON and YAML. Components and diagrams follow their standard schemas.
在单个事务中批量同步组件和图表：
bash
curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"components": [...], "diagrams": [...]}' \
  https://acme-company.revision.app/api/external/template
接受JSON和YAML格式。组件和图表遵循其标准Schema。

Filtering & Dependencies

过滤与依赖

Filtering Components

过滤组件

GET /api/external/components?name=...&typeId=...&tagId=...&attributeId=...&attributeValue=...&state=...
All filters optional. 
attributeValue
requires 
attributeId
.
GET /api/external/components?name=...&typeId=...&tagId=...&attributeId=...&attributeValue=...&state=...
所有过滤器都是可选的。
attributeValue
需要配合
attributeId
使用。

Filtering Diagrams

过滤图表

GET /api/external/diagrams?componentId=...&tagId=...&name=...&level=...&state=...
All filters optional.
GET /api/external/diagrams?componentId=...&tagId=...&name=...&level=...&state=...
所有过滤器都是可选的。

Filtering Types

过滤类型

GET /api/external/types?name=...
GET /api/external/types?name=...

Component Dependencies

组件依赖

GET /api/external/components/{id}/dependencies
Returns 
DependencySearchResult[]
— upstream and downstream direct dependencies for a component.
GET /api/external/components/{id}/dependencies
返回
DependencySearchResult[]
——组件的上游和下游直接依赖。

Workflow: Create a Diagram with Components

工作流：创建包含组件的图表

A typical end-to-end flow: search for duplicates, create components, then create a diagram that references them.
  1. Search for existing duplicates — MUST do this before creating anything:
    • For each component you plan to create, search by name: 
      GET /api/external/components?name=<name>
    • For the diagram, search by name: 
      GET /api/external/diagrams?name=<name>
    • If matches are found → ask the user whether to reuse the existing resource or create a new one
    • If the user chooses to reuse → use the existing resource's 
      id
      instead of creating a new one
    • If no matches → proceed to create
    • Skip ONLY when the user explicitly says "create a new..." or "update the existing..."
  2. List types to find the right 
    typeId
    values:
bash
curl -H "Authorization: Bearer $API_KEY" \
  https://acme-company.revision.app/api/external/types
  1. Create components (skip any that the user chose to reuse from step 1):
bash
curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "user-service", "name": "User Service", "state": "ACTIVE"}' \
  https://acme-company.revision.app/api/external/components
bash
curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "user-db", "name": "User Database", "state": "ACTIVE"}' \
  https://acme-company.revision.app/api/external/components
  1. Create a diagram with component instances and a relation:
bash
curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "User Service Context",
    "level": "C2",
    "state": "ACTIVE",
    "componentInstances": [
      { "ref": "us", "componentId": "user-service" },
      { "ref": "udb", "componentId": "user-db" }
    ],
    "relations": [
      { "fromRef": "us", "toRef": "udb", "label": "Reads/writes" }
    ]
  }' \
  https://acme-company.revision.app/api/external/diagrams
  1. Verify by fetching the diagram back:
bash
curl -H "Authorization: Bearer $API_KEY" \
  https://acme-company.revision.app/api/external/diagrams/<returned-id>
For bulk operations, use the template endpoint to sync everything in a single transaction instead.
典型的端到端流程：搜索重复项，创建组件，然后创建引用这些组件的图表。
  1. 搜索现有重复项——创建任何资源前必须执行此步骤：
    • 对于每个计划创建的组件，按名称搜索：
      GET /api/external/components?name=<name>
    • 对于图表，按名称搜索：
      GET /api/external/diagrams?name=<name>
    • 如果找到匹配项→询问用户是重用现有资源还是创建新资源
    • 如果用户选择重用→使用现有资源的
      id
      而不是创建新资源
    • 如果没有匹配项→继续创建
    • 仅当用户明确说“创建新的...”或“更新现有的...”时，才跳过此步骤
  2. 列出类型以找到正确的
    typeId
    值：
bash
curl -H "Authorization: Bearer $API_KEY" \
  https://acme-company.revision.app/api/external/types
  1. 创建组件（跳过用户在步骤1中选择重用的组件）：
bash
curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "user-service", "name": "User Service", "state": "ACTIVE"}' \
  https://acme-company.revision.app/api/external/components
bash
curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "user-db", "name": "User Database", "state": "ACTIVE"}' \
  https://acme-company.revision.app/api/external/components
  1. 创建包含组件实例和关系的图表：
bash
curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "User Service Context",
    "level": "C2",
    "state": "ACTIVE",
    "componentInstances": [
      { "ref": "us", "componentId": "user-service" },
      { "ref": "udb", "componentId": "user-db" }
    ],
    "relations": [
      { "fromRef": "us", "toRef": "udb", "label": "Reads/writes" }
    ]
  }' \
  https://acme-company.revision.app/api/external/diagrams
  1. 验证：通过获取图表来确认：
bash
curl -H "Authorization: Bearer $API_KEY" \
  https://acme-company.revision.app/api/external/diagrams/<returned-id>
对于批量操作，使用模板端点在单个事务中同步所有内容，而不是分别操作。

Output Summary

输出摘要

After every mutation (create, update, batch upsert, or template sync), print a summary that clearly separates what was created from what was updated.
Format:
Created:
  - Component "User Service" (id: user-service)
  - Diagram "System Context" (id: system-context)

Updated:
  - Component "Auth Service" (id: auth-service) — updated name, desc
Rules:
  • Use Created for POST (201) responses and batch upsert items that had no 
    id
    provided
  • Use Updated for PATCH (200) responses and batch upsert items that had an 
    id
    provided
  • Always include the resource type, name, and ID
  • For updates, briefly note which fields changed
  • Omit a section if it's empty (e.g. don't print "Updated:" if nothing was updated)
每次执行变更操作（创建、更新、批量插入更新或模板同步）后，打印一个摘要，明确区分创建的内容和更新的内容。
格式：
Created:
  - Component "User Service" (id: user-service)
  - Diagram "System Context" (id: system-context)

Updated:
  - Component "Auth Service" (id: auth-service) — updated name, desc
规则：
  • 对于POST（201）响应和批量插入更新中未提供
    id
    的项目，使用Created
  • 对于PATCH（200）响应和批量插入更新中提供了
    id
    的项目，使用Updated
  • 始终包含资源类型、名称和ID
  • 对于更新操作，简要说明哪些字段被修改
  • 如果某个部分为空，则省略该部分（例如，如果没有更新任何内容，则不要打印“Updated:”）

Error Responses

错误响应

All errors return:
json
{ "error": "description" }
StatusMeaning
400Validation error
401Missing or invalid API key
404Resource not found
405Method not allowed
501Not implemented (e.g. DELETE endpoints)
所有错误都会返回：
json
{ "error": "description" }
状态码含义
400验证错误
401API密钥缺失或无效
404资源未找到
405不允许使用该方法
501未实现（例如DELETE端点）

Error Recovery

错误恢复

When an API call fails:
  1. 401: Confirm the API key is correct and the Authorization header uses 
    Bearer
    prefix.
  2. 400: Read the 
    error
    field — it describes the validation issue. Fix the request body and retry.
  3. 404: Verify the resource ID. Use the list endpoint (
    GET /api/external/{resource}
    ) to confirm the resource exists.
  4. 501: DELETE is not implemented. Use PATCH to set 
    state: "ARCHIVED"
    instead.
Always verify mutations by fetching the resource back after create/update to confirm the change took effect.
当API调用失败时：
  1. 401：确认API密钥正确，且Authorization头使用
    Bearer
    前缀。
  2. 400：阅读
    error
    字段——它描述了验证问题。修复请求体并重试。
  3. 404：验证资源ID。使用列表端点（
    GET /api/external/{resource}
    ）确认资源是否存在。
  4. 501：DELETE未实现。使用PATCH将
    state: "ARCHIVED"
    来替代。
创建/更新后，始终通过获取资源来验证变更是否生效。

Full OpenAPI Spec

完整OpenAPI规范

For the complete OpenAPI 3.0.3 specification with all request/response schemas, see OPENAPI.md.
如需包含所有请求/响应Schema的完整OpenAPI 3.0.3规范，请查看OPENAPI.md。