# 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

1. **Import** -- Provide a URL to an OpenAPI 3.0 spec (JSON or YAML).
2. **Parse** -- The system downloads and parses the spec.
3. **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
4. **Review** -- You inspect and edit the classifications in the UI.
5. **Approve** -- Approved endpoints are registered as tools on the appropriate agents.

## Using the UI

1. Navigate to the **API Review** tab.
2. Paste your OpenAPI spec URL into the import form.
3. Click **Scan Tools**.
4. Wait for the job to complete (status: `pending` -> `processing` -> `done`).
5. 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.
6. Click **Save Configuration** when satisfied.

## Using the REST API

### Submit an import job

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

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

Response (202):
```json
{
  "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

```http
GET /api/openapi/jobs/{job_id}
```

### Get classifications

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

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

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

### Approve job

```http
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:
```json
{
  "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