API 개요

Archyl은 아키텍처 문서를 워크플로우, 도구 및 자동화 파이프라인에 통합할 수 있는 종합적인 API를 제공합니다.

API 엔드포인트

Archyl은 두 가지 API 인터페이스를 제공합니다:

REST API

REST API는 모든 Archyl 기능에 대한 완전한 접근을 제공합니다:

• 프로젝트 생성 및 관리
• 아키텍처 요소 추가, 수정, 삭제
• 관계 관리
• ADR 및 문서 처리
• 다이어그램 내보내기
• 관리형 에이전트 실행, 지시 및 스케줄 설정

기본 URL: https://api.archyl.com/api/v1

MCP 서버

Model Context Protocol (MCP) 서버는 AI 어시스턴트가 아키텍처와 상호작용할 수 있도록 합니다:

• Claude Code, Claude Desktop
• Cursor
• VS Code (Copilot 연동)
• 기타 MCP 호환 도구

HTTP 엔드포인트: https://api.archyl.com/mcp

인증

모든 API 요청은 API 키를 사용한 인증이 필요합니다:

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

API 키 생성

1. 프로필 → API 키로 이동합니다
2. "API 키 생성"을 클릭합니다
3. 권한을 선택합니다 (읽기 전용 또는 읽기-쓰기)
4. 키를 복사하여 안전하게 보관합니다

키 권한

빠른 시작

프로젝트 목록 조회

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

시스템 생성

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

관계 생성

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

관리형 에이전트

이 엔드포인트로 관리형 에이전트 실행을 자체 도구에서 시작하고, 추적하고, 스케줄링할 수 있습니다. 경로는 기본 URL 기준 상대 경로입니다.

프로필 및 스킬

실행

에이전트 diff의 특정 줄에 코멘트를 달려면 메시지에 anchor를 추가합니다. side는 작성된 파일의 줄이면 new, 삭제된 줄이면 old이고, changeSeq는 코멘트할 diff가 담긴 file_change 이벤트의 시퀀스 번호입니다:

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

스케줄

MCP 커넥터

이 엔드포인트는 오류 처리에 나열된 코드 외에도, 실행 상태가 해당 작업을 허용하지 않거나 프리플라이트 게이트가 거부하면 409, 조직의 AI 제공자나 모델로 관리형 에이전트를 실행할 수 없으면 422, 비어 있는 동시 실행 슬롯이 없으면 429를 반환합니다. 요청 및 응답 스키마는 OpenAPI 레퍼런스에서 확인하세요.

오류 처리

API 오류는 표준 HTTP 상태 코드를 반환합니다:

오류 응답에는 상세 정보가 포함됩니다:

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

SDK 및 라이브러리

출시 예정:

• JavaScript/TypeScript SDK
• Python SDK
• Go SDK

활용 사례

CI/CD 통합

배포 후 자동으로 아키텍처를 업데이트합니다:

- 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

커스텀 도구

아키텍처와 상호작용하는 내부 도구를 구축합니다:

• 아키텍처 검증
• 규정 준수 확인
• 문서 생성

AI 어시스턴트

MCP를 사용하여 AI 어시스턴트가 아키텍처를 이해하고 업데이트할 수 있게 합니다:

• 아키텍처에 대한 질문
• 자연어로 요소 생성
• 자동 문서 생성

API 문서

전체 대화형 API 문서는 다음에서 확인할 수 있습니다:

https://api.archyl.com/docs

이 OpenAPI 문서에는 다음이 포함됩니다:

• 사용 가능한 모든 엔드포인트
• 요청/응답 스키마
• 직접 실행 기능
• 인증 예시

다음 단계

• 인증 - 상세 인증 가이드
• MCP 서버 - AI 어시스턴트 통합 설정