OpenAPI Import

Import an OpenAPI 3.x specification and Nolxy automatically creates all matching routes, converting OpenAPI path parameters to Nolxy format. One API call — your entire gateway configured.

Quickstart

Send a POST request to the import endpoint with your OpenAPI 3.x specification and the target base URL. Requires a valid JWT management API token.

curl -X POST https://api.nolxy.com/api/v1/openapi/import \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": { ...your OpenAPI 3.x spec object... },
    "baseUrl": "https://api.example.com"
  }'

Reference

API Endpoint

POST/api/v1/openapi/import

Request Body (JSON)

specobject (required) — OpenAPI 3.x spec body
baseUrlstring (required) — Upstream base URL for all routes

Capabilities

Supported versionOpenAPI 3.x only (not Swagger 2.x)
Max routes per import100
Path param conversion{id} → :id (automatic)
Duplicate handlingImport aborted if any route already exists
Format supportJSON only (YAML not yet supported)

Route Naming Priority

  1. operationId — used as-is if present (e.g., listUsers). Recommended.
  2. summary — truncated to 100 characters if no operationId.
  3. method + path — auto-generated fallback (e.g., GET users id).

After Import

Imported routes behave identically to manually created routes. You can then configure plugins (caching, timeouts, circuit breakers) per route inside the dashboard or via API.

Examples

Input Spec

{
  "openapi": "3.0.0",
  "info": { "title": "My API", "version": "1.0.0" },
  "servers": [{ "url": "https://api.example.com" }],
  "paths": {
    "/users": {
      "get": {
        "operationId": "listUsers",
        "summary": "List all users"
      },
      "post": {
        "operationId": "createUser",
        "summary": "Create a user"
      }
    },
    "/users/{id}": {
      "get": { "operationId": "getUser", "summary": "Get user by ID" },
      "put": { "operationId": "updateUser", "summary": "Update user" },
      "delete": { "operationId": "deleteUser", "summary": "Delete user" }
    }
  }
}

Successful Response

{
  "status": "Success",
  "data": {
    "imported": 5,
    "skipped": 0,
    "routes": [
      { "name": "listUsers",   "path": "/users",      "method": "GET"    },
      { "name": "createUser",  "path": "/users",      "method": "POST"   },
      { "name": "getUser",     "path": "/users/:id",  "method": "GET"    },
      { "name": "updateUser",  "path": "/users/:id",  "method": "PUT"    },
      { "name": "deleteUser",  "path": "/users/:id",  "method": "DELETE" }
    ],
    "errors": []
  }
}

Common Errors

400 Bad Request: Validation Failed

Invalid OpenAPI Spec or Format

Fix: Ensure your payload is strictly valid JSON (not YAML) and that the spec object conforms to OpenAPI 3.x standards. The baseUrl must also be a valid absolute HTTP/HTTPS URL.

409 Conflict: Route Exists

Atomic Import Aborted

Fix: If any single route derived from your spec matches the path/method of an existing route in your workspace, the entire import is aborted. Remove the conflicting route manually or update your spec.

Plan Requirements

OpenAPI Import is available on paid plans.

WebhooksResponse Compression