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

MCP Tools

list_external_schemas

List all uploaded schemas with their status and entry counts.

search_external_schemas

Semantic search across uploaded schemas. Use natural language:

search_external_schemas(query: "create customer order")
search_external_schemas(query: "authentication token", category: "ENDPOINT")
search_external_schemas(query: "product inventory fields", schema_id: "exs_...")

describe_external_schema

Get details and category breakdown for a specific schema:

describe_external_schema(schema_id: "exs_...")

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)