# External Schemas Guide

Upload third-party API schemas (OpenAPI 3.x, Swagger 2.0, JSON Schema) and search them
using natural language. This enables AI-assisted integration development by making external
API documentation semantically searchable.

## Supported Formats

- **OpenAPI 3.x** — endpoints, models, fields, parameters, responses
- **Swagger 2.0** — endpoints, definitions, parameters, responses
- **JSON Schema** — models and fields

## Upload via GraphQL

```graphql
mutation UploadSchema($input: UpsertExternalSchemaInput!) {
  upsertExternalSchema(input: $input) {
    externalSchema {
      id name format status entryCount
    }
    errors { path message }
  }
}
```
Variables:
```json
{
  "input": {
    "name": "Shopify Admin API",
    "description": "Shopify Admin REST API v2024-01",
    "format": "OPENAPI_3",
    "sourceText": "{ ... full OpenAPI JSON or YAML ... }"
  }
}
```

Processing happens asynchronously. The schema status transitions:
`PENDING` → `PROCESSING` → `READY` (or `FAILED`)

Check status:
```graphql
query { getExternalSchema(id: "exs_...") { id status entryCount errorMessage } }
```

## Entry Categories

Uploaded schemas are broken down into searchable entries:
- **endpoint** — API endpoints (e.g. `GET /orders`, `POST /customers`)
- **model** — Data models/schemas (e.g. `Order`, `Customer`)
- **field** — Individual fields within models (e.g. `Order.totalPrice`)
- **parameter** — Reusable API parameters
- **response** — Reusable response definitions

## Typical Workflow

1. Upload the external API schema via `upsertExternalSchema` mutation
2. Wait for processing (`status: READY`)
3. Use `search_external_schemas` to find relevant endpoints and models
4. Use the discovered information to build integrations

## Updating a Schema

To update, include the `id` field in the upsert input. This re-processes the schema:
```json
{
  "input": {
    "id": "exs_...",
    "name": "Shopify Admin API v2",
    "format": "OPENAPI_3",
    "sourceText": "{ ... updated schema ... }"
  }
}
```

## Deleting a Schema

```graphql
mutation { deleteExternalSchema(id: "exs_...") { success errors { path message } } }
```
This removes the schema and all its indexed entries.

## Size Limits

- Maximum schema document size: 5 MB
- Schemas are stored in the database as text
- Large schemas may take longer to process (embedding each entry)