Visão Geral da API - Archyl Docs

Conheça a API do Archyl e saiba como integrá-la com suas ferramentas e fluxos de trabalho

Visão Geral da API

O Archyl oferece uma API abrangente que permite integrar a documentação de arquitetura nos seus fluxos de trabalho, ferramentas e pipelines de automação.

Endpoints da API

O Archyl oferece duas interfaces de API:

API REST

A API REST fornece acesso completo a todas as funcionalidades do Archyl:

  • Criar e gerenciar projetos
  • Adicionar, atualizar e excluir elementos de arquitetura
  • Gerenciar relacionamentos
  • Lidar com ADRs e documentação
  • Exportar diagramas

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

Servidor MCP

O servidor Model Context Protocol (MCP) permite que assistentes de IA interajam com sua arquitetura:

  • Claude Code, Claude Desktop
  • Cursor
  • VS Code com Copilot
  • Outras ferramentas compatíveis com MCP

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

Autenticação

Todas as requisições à API exigem autenticação usando uma chave de API:

curl -H "X-API-Key: sua-chave-de-api" \
  https://api.archyl.com/api/v1/projects

Criando Chaves de API

  1. Vá para Perfil > Chaves de API
  2. Clique em "Criar Chave de API"
  3. Escolha as permissões (somente leitura ou leitura e escrita)
  4. Copie e armazene sua chave com segurança

Permissões de Chave

Permissão Descrição
Leitura Visualizar projetos, elementos e documentação
Escrita Criar e modificar projetos, elementos e relacionamentos

Início Rápido

Listar Seus Projetos

curl -X GET \
  -H "X-API-Key: sua-chave-de-api" \
  https://api.archyl.com/api/v1/projects

Criar um Sistema

curl -X POST \
  -H "X-API-Key: sua-chave-de-api" \
  -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

Criar um Relacionamento

curl -X POST \
  -H "X-API-Key: sua-chave-de-api" \
  -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

Tratamento de Erros

Erros da API retornam códigos de status HTTP padrão:

Código Descrição
400 Bad Request - Parâmetros inválidos
401 Unauthorized - Chave de API inválida ou ausente
403 Forbidden - Permissões insuficientes
404 Not Found - Recurso não existe
500 Internal Server Error

Respostas de erro incluem detalhes:

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

SDKs & Bibliotecas

Em breve:

  • SDK JavaScript/TypeScript
  • SDK Python
  • SDK Go

Casos de Uso

Integração CI/CD

Atualize a arquitetura automaticamente após deploys:

- 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

Ferramentas Personalizadas

Construa ferramentas internas que interajam com sua arquitetura:

  • Validação de arquitetura
  • Verificação de conformidade
  • Geração de documentação

Assistentes de IA

Use MCP para permitir que assistentes de IA entendam e atualizem sua arquitetura:

  • Faça perguntas sobre sua arquitetura
  • Crie elementos usando linguagem natural
  • Gere documentação automaticamente

Documentação da API

A documentação interativa completa da API está disponível em:

https://api.archyl.com/docs

Esta documentação OpenAPI inclui:

  • Todos os endpoints disponíveis
  • Schemas de requisição/resposta
  • Funcionalidade de teste
  • Exemplos de autenticação

Próximos Passos