# 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`, `write`, or `admin`
   - `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 **Import**.
4. Wait for the job to complete (status: `pending` -> `processing` -> `done`).
5. Review the endpoint table:
   - Edit `access_type` if the AI misclassified sensitivity.
   - Edit `agent_group` to reassign an endpoint to a different agent.
6. Click **Approve & Save** 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:
```json
{
  "success": true,
  "data": { "job_id": "abc123", "status": "pending" }
}
```

### Poll job status

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

### Get job results

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

### Approve job

```http
POST /api/openapi/jobs/{job_id}/approve
Content-Type: application/json

{
  "endpoints": [
    {
      "path": "/orders/{order_id}",
      "method": "get",
      "access_type": "read",
      "agent_group": "order_agent"
    }
  ]
}
```

## Access Type Classification

| Access Type | Description | Interrupt Required |
|-------------|-------------|-------------------|
| `read` | GET operations, no side effects | No |
| `write` | POST/PUT/PATCH that modify data | Yes |
| `admin` | DELETE, bulk operations, sensitive writes | Yes |

## SSRF Protection

All import requests are validated against an allowlist:
- Private IP ranges are blocked (10.x, 172.16.x, 192.168.x, 127.x)
- Localhost and metadata service URLs are blocked
- Only `http://` and `https://` schemes are permitted

To allow internal URLs (e.g., in development), set `SSRF_ALLOWLIST_HOSTS` in your environment.

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