Referência da API

Documentação para desenvolvedores sobre acesso programático ao Architecto

A API do Architecto permite criar aplicações, integrações e fluxos personalizados sobre a plataforma.

Autenticação

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

Authorization: Bearer YOUR_API_KEY

Criar uma chave de API

Acesse Configurações → Desenvolvedor → Chaves de API.
Clique em Criar nova chave.
Informe nome e validade: nunca, 30 dias, 90 dias ou 1 ano.
Selecione os escopos de leitura, escrita ou administração.
Copie a chave; ela aparece apenas uma vez.

Nunca compartilhe sua chave publicamente. Trate-a como uma senha.

Revogar uma chave de API

Acesse Configurações → Desenvolvedor → Chaves de API.
Clique em Revogar ao lado da chave.
A revogação é imediata.

URL base

Todos os endpoints estão disponíveis em:

https://api.architecto.dev/v1

Endpoints comuns

Autenticação

POST /auth/login          # Login and get session
POST /auth/logout         # End session
POST /auth/refresh        # Refresh access token

Arquiteturas

GET    /architectures              # List your architectures
POST   /architectures              # Create new architecture
GET    /architectures/{id}         # Get architecture details
PUT    /architectures/{id}         # Update architecture
DELETE /architectures/{id}         # Delete architecture
GET    /architectures/{id}/versions # Get version history

Análise

POST   /architectures/{id}/analyze/cost         # Run cost analysis
POST   /architectures/{id}/analyze/scalability  # Run scalability analysis
POST   /architectures/{id}/analyze/threats      # Run threat modeling

Documentação

POST   /architectures/{id}/documents/rfc        # Generate RFC
POST   /architectures/{id}/documents/adr        # Generate ADR
POST   /architectures/{id}/documents/runbook    # Generate runbook

POST   /architectures/{id}/shares      # Create share link
GET    /shares/{token}                 # Get shared architecture
POST   /shares/{token}/comments        # Add comment to shared arch

Equipes

GET    /organizations                  # List your organizations
POST   /organizations                  # Create organization
GET    /organizations/{id}/members     # List team members
POST   /organizations/{id}/invites     # Invite team member

Tratamento de erros

A API retorna os códigos de status HTTP padrão:

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Architecture with id 'arch_123' not found",
    "details": {
      "resource_type": "architecture",
      "resource_id": "arch_123"
    }
  }
}

Códigos de status comuns

Código	Significado
200	Sucesso
400	Requisição inválida: parâmetros incorretos
401	Não autenticado: chave de API inválida
403	Proibido: permissões insuficientes
404	Não encontrado
429	Limite de requisições atingido
500	Erro do servidor

Limites de requisições

A API aplica os seguintes limites:

Plano Free: 100 requisições por hora.
Plano Pro: 1,000 requisições por hora.
Plano Ultimate: 10,000 requisições por hora.

Os cabeçalhos da resposta informam os limites:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Exemplo: criar e analisar uma arquitetura

# 1. Create architecture
curl -X POST https://api.architecto.dev/v1/architectures \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "E-commerce Platform",
    "description": "Multi-region e-commerce with real-time inventory",
    "cloud_provider": "aws"
  }'

# Response:
# {
#   "id": "arch_abc123",
#   "title": "E-commerce Platform",
#   "created_at": "2024-01-15T10:30:00Z"
# }

# 2. Run cost analysis
curl -X POST https://api.architecto.dev/v1/architectures/arch_abc123/analyze/cost \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scale_points": [1000, 10000, 100000],
    "region": "us-east-1"
  }'

# Response:
# {
#   "analysis_id": "analysis_xyz789",
#   "estimates": [
#     {
#       "users": 1000,
#       "monthly_cost": 150,
#       "breakdown": { "compute": 80, "storage": 40, "data_transfer": 30 }
#     },
#     ...
#   ]
# }

Webhooks: em breve

Assine eventos de arquitetura:

POST /webhooks
{
  "url": "https://your-app.com/webhook",
  "events": ["architecture.created", "architecture.updated", "analysis.completed"]
}

SDKs

SDKs oficiais em breve para:

Python
Node.js / TypeScript
Go
Ruby
Java

Documentação interativa da API

Experimente a API sem escrever código:

Suporte

Problemas da API: publique em GitHub Issues.
Dúvidas: pergunte no Discord da comunidade.
Empresas: entre em contato com sales@architecto.dev.

Próximos passos:

Guia de integrações
Configuração de webhooks (em breve)

Referência da API

Nesta página