API Overview

Archyl provides a comprehensive API that allows you to integrate architecture documentation into your workflows, tools, and automation pipelines.

API Endpoints

Archyl offers two API interfaces:

REST API

The REST API provides full access to all Archyl features:

• Create and manage projects
• Add, update, and delete architecture elements
• Manage relationships
• Handle ADRs and documentation
• Export diagrams

Base URL: https://api.archyl.com/api/v1

MCP Server

The Model Context Protocol (MCP) server enables AI assistants to interact with your architecture:

• Claude Code, Claude Desktop
• Cursor
• VS Code with Copilot
• Other MCP-compatible tools

SSE Endpoint: https://api.archyl.com/sse HTTP Endpoint: https://api.archyl.com/mcp

Authentication

All API requests require authentication using an API key:

curl -H "X-API-Key: your-api-key" \
  https://api.archyl.com/api/v1/projects

Creating API Keys

1. Go to your Profile → API Keys
2. Click "Create API Key"
3. Choose permissions (read-only or read-write)
4. Copy and securely store your key

Key Permissions

Quick Start

List Your Projects

curl -X GET \
  -H "X-API-Key: your-api-key" \
  https://api.archyl.com/api/v1/projects

Create a System

curl -X POST \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "E-commerce Platform",
    "description": "Main e-commerce system",
    "type": "internal"
  }' \
  https://api.archyl.com/api/v1/projects/{projectId}/systems

Create a Relationship

curl -X POST \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceId": "system-1",
    "targetId": "system-2",
    "label": "Sends orders to",
    "technology": "REST/HTTPS"
  }' \
  https://api.archyl.com/api/v1/projects/{projectId}/relationships

Error Handling

API errors return standard HTTP status codes:

Error responses include details:

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Name is required",
    "field": "name"
  }
}

SDKs & Libraries

Coming soon:

• JavaScript/TypeScript SDK
• Python SDK
• Go SDK

Use Cases

CI/CD Integration

Automatically update architecture after deployments:

- name: Update Architecture
  run: |
    curl -X POST \
      -H "X-API-Key: ${{ secrets.ARCHYL_API_KEY }}" \
      https://api.archyl.com/api/v1/projects/$PROJECT_ID/discover

Custom Tooling

Build internal tools that interact with your architecture:

• Architecture validation
• Compliance checking
• Documentation generation

AI Assistants

Use MCP to let AI assistants understand and update your architecture:

• Ask questions about your architecture
• Create elements through natural language
• Generate documentation automatically

API Documentation

The full interactive API documentation is available at:

https://api.archyl.com/docs

This OpenAPI documentation includes:

• All available endpoints
• Request/response schemas
• Try-it-out functionality
• Authentication examples

Next Steps

• Authentication - Detailed authentication guide
• MCP Server - Set up AI assistant integration