Archyl의 API와 도구 및 워크플로우에 통합하는 방법을 알아보세요

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 호환 도구

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

인증

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

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

API 키 생성

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

키 권한

권한	설명
읽기	프로젝트, 요소 및 문서 조회
쓰기	프로젝트, 요소, 관계 생성 및 수정

빠른 시작

프로젝트 목록 조회

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

오류 처리

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

코드	설명
400	Bad Request - 잘못된 파라미터
401	Unauthorized - 유효하지 않거나 누락된 API 키
403	Forbidden - 권한 부족
404	Not Found - 리소스가 존재하지 않음
500	Internal Server Error

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

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

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 어시스턴트 통합 설정

API 개요 - Archyl Docs