Panoramica API

Archyl fornisce un'API completa che ti permette di integrare la documentazione architetturale nei tuoi flussi di lavoro, strumenti e pipeline di automazione.

Endpoint API

Archyl offre due interfacce API:

API REST

L'API REST fornisce accesso completo a tutte le funzionalità di Archyl:

Creare e gestire progetti
Aggiungere, aggiornare ed eliminare elementi architetturali
Gestire le relazioni
Gestire ADR e documentazione
Esportare diagrammi
Avviare, guidare e pianificare agenti gestiti

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

Server MCP

Il server Model Context Protocol (MCP) consente agli assistenti AI di interagire con la tua architettura:

Claude Code, Claude Desktop
Cursor
VS Code con Copilot
Altri strumenti compatibili con MCP

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

Autenticazione

Tutte le richieste API richiedono l'autenticazione tramite una chiave API:

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

Creazione Chiavi API

Vai su Profilo → Chiavi API
Clicca su "Crea Chiave API"
Scegli i permessi (sola lettura o lettura-scrittura)
Copia e conserva la chiave in modo sicuro

Permessi delle Chiavi

Permesso	Descrizione
Lettura	Visualizzare progetti, elementi e documentazione
Scrittura	Creare e modificare progetti, elementi, relazioni

Guida Rapida

Elenco dei Tuoi Progetti

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

Creare un Sistema

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

Creare una Relazione

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

Agenti Gestiti

Questi endpoint ti permettono di avviare, seguire e pianificare le esecuzioni gestite degli agenti dai tuoi strumenti. I percorsi sono relativi all'URL base.

Profili e Skill

Metodo	Percorso	Descrizione
`GET`	`/agents/skills`	Elencare le skill integrate che un profilo può attivare
`GET`	`/agents/profiles`	Elencare i profili degli agenti (se non ce n'è nessuno viene creato un profilo predefinito)
`POST`	`/agents/profiles`	Creare un profilo
`PUT`	`/agents/profiles/{id}`	Aggiornare un profilo
`DELETE`	`/agents/profiles/{id}`	Eliminare un profilo e mettere in pausa le pianificazioni che lo usano

Esecuzioni

Metodo	Percorso	Descrizione
`POST`	`/projects/{projectId}/agents/runs`	Avviare un'esecuzione su un progetto
`GET`	`/agents/runs`	Elencare le esecuzioni, filtrate per `projectId`, `status` o `parentRunId` e paginate con `page` e `pageSize`
`GET`	`/agents/runs/{id}`	Ottenere un'esecuzione
`GET`	`/agents/runs/{id}/events`	Elencare gli eventi dell'esecuzione successivi al numero di sequenza `since`
`POST`	`/agents/runs/{id}/cancel`	Annullare un'esecuzione
`POST`	`/agents/runs/{id}/steer`	Inviare un messaggio all'agente, facoltativamente ancorato a una riga del suo diff
`POST`	`/agents/runs/{id}/respond`	Approvare o rifiutare il piano dell'agente, oppure rispondere alla sua domanda
`POST`	`/agents/runs/{id}/approve`	Avviare un'esecuzione che il gate di preflight trattiene in `awaiting_approval`
`POST`	`/agents/runs/{id}/continue`	Avviare una nuova esecuzione che prosegue un'esecuzione terminata sullo stesso branch e sulla stessa pull request

Per commentare una riga del diff dell'agente, aggiungi un anchor al messaggio. side è new per una riga del file così come è scritto o old per una riga rimossa, e changeSeq è il numero di sequenza dell'evento file_change di cui commenti il diff:

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

Pianificazioni

Metodo	Percorso	Descrizione
`GET`	`/agents/schedules`	Elencare le pianificazioni, facoltativamente filtrate per `projectId`
`POST`	`/agents/schedules`	Creare una pianificazione (espressione cron a 5 campi, valutata in UTC)
`PUT`	`/agents/schedules/{id}`	Aggiornare una pianificazione
`POST`	`/agents/schedules/{id}/toggle`	Attivare o disattivare una pianificazione
`POST`	`/agents/schedules/{id}/trigger`	Avviare subito un'esecuzione dalla pianificazione
`DELETE`	`/agents/schedules/{id}`	Eliminare una pianificazione

Connettori MCP

Metodo	Percorso	Descrizione
`GET`	`/agents/connectors`	Elencare i connettori
`POST`	`/agents/connectors`	Creare un connettore
`PUT`	`/agents/connectors/{id}`	Aggiornare un connettore
`POST`	`/agents/connectors/{id}/toggle`	Attivare o disattivare un connettore
`DELETE`	`/agents/connectors/{id}`	Eliminare un connettore
`POST`	`/agents/connectors/test`	Testare una connessione ed elencare gli strumenti del server

Oltre ai codici descritti in Gestione degli Errori, questi endpoint restituiscono 409 quando lo stato di un'esecuzione non consente l'azione o il gate di preflight la rifiuta, 422 quando il provider o il modello di IA della tua organizzazione non può eseguire agenti gestiti, e 429 quando non c'è nessuno slot di concorrenza libero. Gli schemi di richiesta e risposta sono nel riferimento OpenAPI.

Gestione degli Errori

Gli errori API restituiscono codici di stato HTTP standard:

Codice	Descrizione
400	Bad Request - Parametri non validi
401	Unauthorized - Chiave API non valida o mancante
403	Forbidden - Permessi insufficienti
404	Not Found - Risorsa inesistente
500	Internal Server Error

Le risposte di errore includono dettagli:

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

SDK e Librerie

In arrivo:

SDK JavaScript/TypeScript
SDK Python
SDK Go

Casi d'Uso

Integrazione CI/CD

Aggiorna automaticamente l'architettura dopo i deploy:

- 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

Strumenti Personalizzati

Costruisci strumenti interni che interagiscono con la tua architettura:

Validazione architetturale
Verifica di conformità
Generazione di documentazione

Assistenti AI

Usa MCP per permettere agli assistenti AI di comprendere e aggiornare la tua architettura:

Fare domande sulla tua architettura
Creare elementi tramite linguaggio naturale
Generare documentazione automaticamente

Documentazione API

La documentazione API interattiva completa è disponibile su:

https://api.archyl.com/docs

Questa documentazione OpenAPI include:

Tutti gli endpoint disponibili
Schemi di richiesta/risposta
Funzionalità di prova
Esempi di autenticazione

Prossimi Passi

Autenticazione - Guida dettagliata all'autenticazione
Server MCP - Configurare l'integrazione con assistenti AI