Public REST API

Caplo provides a workspace-scoped REST API for integrating scripts, ETL jobs, and other HTTP clients with your architecture repository.

Use this API when you want standard HTTP CRUD for entities and relations. For AI coding agents, prefer MCP connections.

Base URL

https://app.caplo.ai/api/v1

Interactive docs (Swagger UI): /api/v1/docs
OpenAPI document: /api/v1/openapi.json

Authentication

1. Sign in to Caplo as a workspace admin.
2. Open Settings → API keys.
3. Create a key (optionally set an expiration) and copy the secret immediately (caplo_sk_...). Caplo only shows it once.
4. Send it on every request:

Authorization: Bearer caplo_sk_<prefix>_<secret>

The key is bound to one workspace. Do not send a workspace_id in the request body or query string.

Resources

Entities

Method	Path	Description
GET	/entities	List/search (type, q, approved, limit, offset)
POST	/entities	Create
GET	/entities/{id}	Get by id (includes unapproved and soft-deleted)
PATCH	/entities/{id}	Update name, properties, and/or approved
DELETE	/entities/{id}	Soft-delete (cascades connected relations)

Example create:

curl -sS -X POST "https://app.caplo.ai/api/v1/entities" \
  -H "Authorization: Bearer $CAPLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"application","name":"CRM","properties":{"description":"Customer system"}}'

Relations

Method	Path	Description
GET	/relations	List/search (from, to, type, q, approved, limit, offset)
POST	/relations	Create
GET	/relations/{id}	Get by id (includes unapproved and soft-deleted)
PATCH	/relations/{id}	Update name, properties, and/or approved
DELETE	/relations/{id}	Soft-delete

Example create:

curl -sS -X POST "https://app.caplo.ai/api/v1/relations" \
  -H "Authorization: Bearer $CAPLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"<entity-uuid>","to":"<entity-uuid>","type":"flows","name":"orders"}'

Metamodel discovery

Method	Path	Description
GET	/entity-types	Enabled entity types + writable property schemas
GET	/entity-types/{type}/properties	Property schema for one entity type
GET	/relation-types	Relation types + property schemas
GET	/relation-types/{type}/properties	Property schema for one relation type

Errors

Errors use a consistent JSON shape:

{
    "error": {
        "code": "validation_error",
        "message": "Provide at least one of name, properties, or approved."
    }
}

Common status codes:

• 401 — missing/invalid/revoked/expired API key
• 403 — missing scope or workspace role permission
• 404 — resource not found (for PATCH/DELETE, also when already soft-deleted)
• 409 — uniqueness conflict (for example duplicate entity name+type)

Limits and notes

• Pagination uses limit (max 100) and offset.
• Deletes are soft deletes; they do not permanently erase rows.
• Diagrams, reports, and live canvas sync are not part of this API version yet.