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

mutation UploadSchema($input: UpsertExternalSchemaInput!) {
  upsertExternalSchema(input: $input) {
    externalSchema {
      id name format status entryCount
    }
    errors { path message }
  }
}

Variables:

{
  "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:

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:

{
  "input": {
    "id": "exs_...",
    "name": "Shopify Admin API v2",
    "format": "OPENAPI_3",
    "sourceText": "{ ... updated schema ... }"
  }
}

Deleting a Schema

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)