Files

Yaojia Wang f0699436c5 refactor: engineering improvements -- API versioning, structured logging, Alembic, error standardization, test coverage

- API versioning: all REST endpoints prefixed with /api/v1/
- Structured logging: replaced stdlib logging with structlog (console/JSON modes)
- Alembic migrations: versioned DB schema with initial migration
- Error standardization: global exception handlers for consistent envelope format
- Interrupt cleanup: asyncio background task for expired interrupt removal
- Integration tests: +30 tests (analytics, replay, openapi, error, session APIs)
- Frontend tests: +57 tests (all components, pages, useWebSocket hook)
- Backend: 557 tests, 89.75% coverage | Frontend: 80 tests, 16 test files

2026-04-06 23:19:29 +02:00

3.3 KiB

Raw Blame History

OpenAPI Auto-Discovery Guide

Overview

Smart Support can automatically generate AI agents from any OpenAPI 3.0 specification. Import a URL, review the AI-classified endpoints, approve, and your agents are live.

How It Works

Import -- Provide a URL to an OpenAPI 3.0 spec (JSON or YAML).
Parse -- The system downloads and parses the spec.
Classify -- An LLM classifies each endpoint's:
- access_type: read or write
- needs_interrupt: whether human approval is required
- agent_group: which specialist agent should handle this endpoint
Review -- You inspect and edit the classifications in the UI.
Approve -- Approved endpoints are registered as tools on the appropriate agents.

Using the UI

Navigate to the API Review tab.
Paste your OpenAPI spec URL into the import form.
Click Scan Tools.
Wait for the job to complete (status: pending -> processing -> done).
Review the endpoint cards grouped by agent:
- Edit access_type (Read Only / Write) if the AI misclassified sensitivity.
- Edit the agent assignment to reassign an endpoint to a different agent.
Click Save Configuration when satisfied.

Using the REST API

Submit an import job

POST /api/openapi/import
Content-Type: application/json

{
  "url": "https://api.example.com/openapi.yaml"
}

Response (202):

{
  "job_id": "abc123",
  "status": "pending",
  "spec_url": "https://api.example.com/openapi.yaml",
  "total_endpoints": 0,
  "classified_count": 0,
  "error_message": null
}

Poll job status

GET /api/openapi/jobs/{job_id}

Get classifications

GET /api/openapi/jobs/{job_id}/classifications

Response: array of classification objects with index, access_type, needs_interrupt, agent_group, confidence, customer_params, and endpoint.

Update a classification

PUT /api/openapi/jobs/{job_id}/classifications/{index}
Content-Type: application/json

{
  "access_type": "write",
  "needs_interrupt": true,
  "agent_group": "order_actions"
}

Approve job

POST /api/openapi/jobs/{job_id}/approve

No request body. Generates tool code for each classified endpoint and produces an agent YAML configuration. Response includes generated_tools_count.

Response:

{
  "job_id": "abc123",
  "status": "approved",
  "spec_url": "https://api.example.com/openapi.yaml",
  "total_endpoints": 5,
  "classified_count": 5,
  "error_message": null,
  "generated_tools_count": 5
}

Access Type Classification

Access Type	Description	Interrupt Required
`read`	GET operations, no side effects	No
`write`	POST/PUT/PATCH/DELETE that modify data	Yes (by default)

The needs_interrupt flag can be overridden per-endpoint during review.

SSRF Protection

All import requests are validated:

Private IP ranges are blocked (10.x, 172.16.x, 192.168.x, 127.x)
Localhost and cloud metadata service URLs are blocked
Only http:// and https:// schemes are permitted

Supported Spec Formats

OpenAPI 3.0.x (JSON or YAML)
Swagger 2.0 is not supported

Limitations

Maximum spec file size: 1 MB
Maximum endpoints per spec: 200
Specs requiring authentication headers are not yet supported for import

3.3 KiB Raw Blame History