Openapi Schema

OpenAPI Schema Creator for OpenAI Actions

Create OpenAPI 3.1.0 schemas that enable Custom GPTs to call external REST APIs via the Actions protocol.

Quick Start

To create a schema, you need:

1. API endpoint(s) - URL, method, parameters
2. Authentication type - None, API Key, or OAuth 2.0
3. Request/response structure - JSON models

Core Requirements

• OpenAPI Version: Must use 3.1.0 (not 3.0.x or 2.0)
• File Formats: YAML (preferred) or JSON - both fully supported
• Max File Size: 1 MB
• Max Endpoints: 30 per action slot, 10 slots per GPT

Schema Structure

Minimal Valid Schema

openapi: 3.1.0
info:
  title: My API
  description: What this API does
  version: 1.0.0
servers:
  - url: https://api.example.com
paths:
  /endpoint:
    get:
      operationId: uniqueOperationName
      summary: Brief description
      description: Detailed description for GPT
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object

Critical Elements for GPT Actions

Authentication Patterns

No Authentication

# Simply omit security sections
paths:
  /public/data:
    get:
      operationId: getPublicData
      security: []  # Explicitly no auth

API Key

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header  # or query
      name: X-API-Key

security:
  - ApiKeyAuth: []

paths:
  /private/data:
    get:
      operationId: getPrivateData
      security:
        - ApiKeyAuth: []

OAuth 2.0

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/authorize
          tokenUrl: https://auth.example.com/token
          scopes:
            read: Read access
            write: Write access

OAuth Requirements:

• Must use Authorization Code Grant with PKCE
• Redirect URLs to register: https://chat.openai.com/aip/{g-YOUR-GPT-ID}/oauth/callback and https://chatgpt.com/aip/{g-YOUR-GPT-ID}/oauth/callback
• TLS 1.2+ required on port 443

Common Patterns

GET with Query Parameters

paths:
  /search:
    get:
      operationId: searchItems
      parameters:
        - name: query
          in: query
          required: true
          schema:
            type: string
          description: Search term
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
          description: Max results to return
      responses:
        '200':
          description: Search results

POST with JSON Body

paths:
  /items:
    post:
      operationId: createItem
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                description:
                  type: string
                tags:
                  type: array
                  items:
                    type: string
      responses:
        '201':
          description: Item created

File Upload

paths:
  /upload:
    post:
      operationId: uploadFile
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                description:
                  type: string
      responses:
        '200':
          description: Upload successful

Returning Files to GPT

paths:
  /documents/{id}:
    get:
      operationId: getDocument
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Document data
          content:
            application/json:
              schema:
                type: object
                properties:
                  openaiFileResponse:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        mime_type:
                          type: string
                        content:
                          type: string
                          format: byte  # Base64-encoded

Best Practices

1. Description Writing

Descriptions are critical - GPT uses them to decide when to call actions:

# Good - specific and actionable
description: Fetches current weather conditions for a given city. Use when the user asks about temperature, precipitation, or weather forecasts.

# Bad - vague
description: Gets weather data

2. Response Design

Return raw data, NOT natural language:

# Good - structured data
{
  "temperature": 72,
  "condition": "sunny",
  "humidity": 45
}

# Bad - pre-formatted text
{
  "message": "The weather is sunny with 72 degrees and 45% humidity"
}

3. Use Enums for Fixed Values

parameters:
  - name: unit
    in: query
    schema:
      type: string
      enum: ["celsius", "fahrenheit", "kelvin"]
    description: Temperature unit

4. Consequential Actions

Control confirmation behavior with extension:

paths:
  /delete-account:
    post:
      operationId: deleteAccount
      x-openai-isConsequential: true  # Always prompts

Default behavior:

• GET: false (shows "Always allow")
• POST/PUT/DELETE: true (always prompts)

Limitations & Constraints

Data Types & Formats

OpenAPI 3.1.0 supports these formats:

type: string
format: date-time  # ISO 8601
type: string
format: date       # YYYY-MM-DD
type: string
format: email
type: string
format: uri
type: string
format: uuid
type: number
format: float
type: number
format: double
type: integer
format: int32
type: integer
format: int64

Complex Schema Examples

See references/examples.md for complete working examples of:

• Weather API with nested endpoints
• CRUD operations with authentication
• File upload/download
• Pagination patterns
• Error response handling

Validation Checklist

Before using a schema:

• Uses openapi: 3.1.0
• All operationId values are unique
• All path parameters have required: true
• Descriptions are specific and actionable
• Authentication is properly configured
• Response schemas match actual API responses
• File size is under 1 MB

Testing

Test schemas before deployment:

1. Validate syntax with Swagger Editor or similar
2. Test API calls in Postman/Insomnia
3. Use OpenAI's "Actions GPT" to help validate
4. Test each endpoint individually in GPT editor