Revision External API

REST API for managing architecture documentation in Revision workspaces.

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.

Authentication

All requests require a Bearer token (API key from workspace settings):

Authorization: Bearer <api-key>

Base 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.

Resources

Quick Start

List components

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

Create a component

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

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

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

Every resource (components, diagrams, attributes, tags) follows the same pattern:

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.

Component Schema

{
  "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)

Diagram Schema

{
  "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

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):

{
  "ref": "unique-ref",
  "componentId": "component-id | null",
  "parent": "container-ref",
  "isContainer": false,
  "placeholder": { "text": "Name", "typeId": "type-id" }
}

Container (groups other instances):

{
  "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

Relations

Directed edges between component instances:

{
  "fromRef": "instance-ref-1",
  "toRef": "instance-ref-2",
  "label": "string | null",
  "desc": "string | null",
  "linksTo": ["diagram-id"]
}

Textareas

Free text on diagrams:

{
  "position": { "x": 100, "y": 100 },
  "width": 300,
  "text": "string | null"
}

Attribute Schema

Custom fields on components:

{
  "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

Tag Schema

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

Type Schema (Read-Only)

{
  "id": "string",
  "name": "string"
}

Types are managed in the Revision UI. List via GET /api/external/types. Supports optional name query parameter for filtering.

Template Sync

Bulk sync components and diagrams in a single transaction:

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.

Filtering & Dependencies

Filtering Components

GET /api/external/components?name=...&typeId=...&tagId=...&attributeId=...&attributeValue=...&state=...

All filters optional. attributeValue requires attributeId.

Filtering Diagrams

GET /api/external/diagrams?componentId=...&tagId=...&name=...&level=...&state=...

All filters optional.

Filtering Types

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

Component Dependencies

GET /api/external/components/{id}/dependencies

Returns DependencySearchResult[] — upstream and downstream direct dependencies for a component.

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:

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

3. Create components (skip any that the user chose to reuse from step 1):

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

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

4. Create a diagram with component instances and a relation:

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

5. Verify by fetching the diagram back:

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.

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)

Error Responses

All errors return:

{ "error": "description" }

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.

Full OpenAPI Spec

For the complete OpenAPI 3.0.3 specification with all request/response schemas, see OPENAPI.md.