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
• Executar, orientar e agendar agentes gerenciados

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 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

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

Agentes Gerenciados

Estes endpoints permitem iniciar, acompanhar e agendar execuções gerenciadas de agentes a partir das suas próprias ferramentas. Os caminhos são relativos à URL base.

Perfis e Skills

Execuções

Para comentar uma linha do diff do agente, adicione um anchor à mensagem. side é new para uma linha do arquivo como está escrito ou old para uma linha removida, e changeSeq é o número de sequência do evento file_change cujo diff você comenta:

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

Agendamentos

Conectores MCP

Além dos códigos descritos em Tratamento de Erros, estes endpoints retornam 409 quando o estado de uma execução não permite a ação ou o gate de preflight a recusa, 422 quando o provedor ou o modelo de IA da sua organização não consegue executar agentes gerenciados, e 429 quando não há nenhuma vaga de concorrência livre. Os esquemas de requisição e resposta estão na referência OpenAPI.

Tratamento de Erros

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

Respostas de erro incluem detalhes:

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

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

• Autenticação - Guia detalhado de autenticação
• Servidor MCP - Configure a integração com assistentes de IA