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
Run, steer, and schedule managed agents

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

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

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

Key Permissions

Permission	Description
Read	View projects, elements, and documentation
Write	Create and modify projects, elements, relationships

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

Managed Agents

These endpoints let you start, follow, and schedule managed agent runs from your own tools. Paths are relative to the base URL.

Profiles and Skills

Method	Path	Description
`GET`	`/agents/skills`	List the built-in skills a profile can enable
`GET`	`/agents/profiles`	List agent profiles (a default profile is created if there is none)
`POST`	`/agents/profiles`	Create a profile
`PUT`	`/agents/profiles/{id}`	Update a profile
`DELETE`	`/agents/profiles/{id}`	Delete a profile and pause the schedules that use it

Runs

Method	Path	Description
`POST`	`/projects/{projectId}/agents/runs`	Start a run on a project
`GET`	`/agents/runs`	List runs, filtered by `projectId`, `status` or `parentRunId` and paginated with `page` and `pageSize`
`GET`	`/agents/runs/{id}`	Get a run
`GET`	`/agents/runs/{id}/events`	List the run's events after the `since` sequence number
`POST`	`/agents/runs/{id}/cancel`	Cancel a run
`POST`	`/agents/runs/{id}/steer`	Send a message to the agent, optionally anchored to a line of its diff
`POST`	`/agents/runs/{id}/respond`	Approve or reject the agent's plan, or answer its question
`POST`	`/agents/runs/{id}/approve`	Start a run the preflight gate holds in `awaiting_approval`
`POST`	`/agents/runs/{id}/continue`	Start a new run that continues an ended run on the same branch and pull request

To comment a line of the agent's diff, add an anchor to the steering message. side is new for a line of the file as written or old for a removed line, and changeSeq is the sequence number of the file_change event whose diff you comment on:

curl -X POST \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Reuse the existing retry helper here",
    "anchor": {"path": "internal/billing/client.go", "line": 42, "side": "new", "changeSeq": 17}
  }' \
  https://api.archyl.com/api/v1/agents/runs/{runId}/steer

Schedules

Method	Path	Description
`GET`	`/agents/schedules`	List schedules, optionally filtered by `projectId`
`POST`	`/agents/schedules`	Create a schedule (5-field cron expression, evaluated in UTC)
`PUT`	`/agents/schedules/{id}`	Update a schedule
`POST`	`/agents/schedules/{id}/toggle`	Enable or disable a schedule
`POST`	`/agents/schedules/{id}/trigger`	Start a run from the schedule now
`DELETE`	`/agents/schedules/{id}`	Delete a schedule

MCP Connectors

Method	Path	Description
`GET`	`/agents/connectors`	List connectors
`POST`	`/agents/connectors`	Create a connector
`PUT`	`/agents/connectors/{id}`	Update a connector
`POST`	`/agents/connectors/{id}/toggle`	Enable or disable a connector
`DELETE`	`/agents/connectors/{id}`	Delete a connector
`POST`	`/agents/connectors/test`	Test a connection and list the server's tools

On top of the codes listed under Error Handling, these endpoints return 409 when a run is not in a state that allows the action or the preflight gate refuses it, 422 when your organization's AI provider or model cannot run managed agents, and 429 when no concurrency seat is free. Request and response schemas are in the OpenAPI reference.

Error Handling

API errors return standard HTTP status codes:

Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
500	Internal Server Error

Error responses include details:

{
  "error": true,
  "message": "instructions are required to continue a run"
}

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