Validating OpenAI API Implementations

What this skill does

# OpenAI API Expert

This skill provides comprehensive knowledge of the official OpenAI API specification for validating implementations, answering API questions, and reviewing code that integrates with OpenAI services.

## When to Use This Skill

Invoke this skill when:
- Reviewing pull requests that use OpenAI APIs
- Answering questions about OpenAI API endpoints, parameters, or capabilities
- Validating whether a feature or parameter is part of the official OpenAI API
- Determining correct usage patterns for OpenAI integrations
- Checking authentication and request formatting
- Verifying API endpoint structures and response formats

## Official API Specification

**Authoritative Source**: https://app.stainless.com/api/spec/documented/openai/openapi.documented.yml

This OpenAPI specification is the single source of truth for all OpenAI API details. Always check the version number in the specification to ensure you're working with current information.

## Core API Structure

**Base URL**: `https://api.openai.com/v1`

**Authentication**: API Key-based (Bearer token) using the `ApiKeyAuth` security scheme

## Main Endpoint Categories

### 1. Chat Completions
- Core conversational AI capabilities
- Supports streaming responses
- Multiple model options
- Token counting and usage tracking

### 2. Embeddings
- Text embedding generation
- Vector representations for semantic search
- Multiple embedding models available

### 3. Models
- List and retrieve model information
- Model capabilities and specifications
- Model availability and access

### 4. Audio
- **Speech Generation**: Text-to-speech capabilities
- **Transcription**: Speech-to-text with advanced options
- **Translation**: Audio translation services
- Supports diarization and word-level timestamps
- Streaming capabilities

### 5. Assistants
- Create, modify, list, and delete AI assistants
- Persistent assistant configurations
- Custom behavior and capabilities

### 6. Batch Processing
- Create and manage batch API requests
- Asynchronous processing
- Cost-effective for large-scale operations

### 7. Moderations
- Content moderation capabilities
- Safety and policy compliance

## Key Validation Points

When reviewing OpenAI API implementations, verify:

1. **Endpoint Correctness**: All endpoints match the official specification paths
2. **Authentication**: Proper use of API key with Bearer token scheme
3. **Parameters**: Only official parameters are used; no undocumented features
4. **Model Names**: Valid model identifiers from the models endpoint
5. **Request Format**: Proper JSON structure and content types
6. **Response Handling**: Correct parsing of API responses
7. **Streaming**: Proper implementation when using streaming features
8. **Error Handling**: Appropriate handling of API error responses

## Common Implementation Patterns

### Authentication Header
```
Authorization: Bearer {API_KEY}
```

### Endpoint Structure
All endpoints follow the pattern: `https://api.openai.com/v1/{category}/{action}`

### Streaming Responses
Multiple endpoints support streaming for real-time data delivery

## Referencing the Specification

For detailed validation:
1. Fetch the specification from the official URL
2. Search for the specific endpoint or parameter in question
3. Verify exact schema requirements, data types, and constraints
4. Check for version-specific features or deprecations

## Searching the Specification Effectively

The OpenAPI YAML specification is the authoritative source. The most effective approach is to download it locally and search it directly.

### Recommended Approach: Download and Search Locally

**This is the MOST EFFECTIVE method for searching the OpenAI API spec:**

1. **Download the spec locally**:
   ```bash
   curl -o openai-spec.yml https://app.stainless.com/api/spec/documented/openai/openapi.documented.yml
   ```

2. **Use Grep to find all occurrences** of relevant terms:
   ```bash
   # Case-insensitive search with line numbers and context
   Grep pattern="MCP" path="openai-spec.yml" output_mode="content" -i=true
   ```

3. **Read specific sections** using line numbers from Grep results:
   ```bash
   Read file_path="openai-spec.yml" offset=42619 limit=100
   ```

4. **Iteratively refine searches** as needed without network overhead

**Why this works better:**
- ✅ No WebFetch limitations or timeouts
- ✅ Can search multiple times instantly (local file)
- ✅ Grep finds ALL occurrences, not just what WebFetch extracts
- ✅ Can examine exact line numbers and surrounding context
- ✅ No reliance on AI summarization of spec content
- ✅ Can verify findings by reading exact schema definitions

**When to use this approach:**
- Searching for specific schemas (e.g., MCPTool, ChatCompletion)
- Finding all references to a feature (e.g., all "authorization" occurrences)
- Examining exact field definitions and types
- Any detailed technical investigation of the API

### Alternative: WebFetch (Less Reliable)

If you cannot download the spec locally, WebFetch can be used but has limitations:

#### Specification Organization

The spec uses standard OpenAPI structure:
- **`components/schemas/`**: All type definitions (e.g., `MCPTool`, `ChatCompletion`)
- **`paths/`**: Endpoint definitions and operations
- **Request/response schemas**: Referenced via `$ref` to components

#### WebFetch Search Strategy

1. **Use precise technical terms** in prompts:
   - Schema names: "MCPTool schema definition", "ChatCompletion schema"
   - Exact field names: "authorization field", "server_url parameter"
   - Component paths: "components/schemas/MCPTool"

2. **Try multiple targeted prompts** on the SAME spec URL:
   - If first prompt fails, refine the search terms
   - Try variations: "find all schema definitions", "search for MCP"
   - Don't immediately jump to secondary sources

3. **Trust the authoritative source**:
   - The official spec has the answer
   - Secondary docs (cookbooks, blogs) may be outdated or incomplete
   - Web searches are useful for context, but verify against the spec

### What Doesn't Work

**Avoid these ineffective patterns:**
- ❌ Multiple WebFetch attempts when local download would work better
- ❌ Vague prompts: "search for OAuth token handling"
- ❌ Jumping to web searches when spec search doesn't work
- ❌ Relying on secondary documentation without spec verification
- ❌ Using general terms instead of schema/component names

**Use these effective patterns:**
- ✅ **Download spec locally and use Grep** (BEST approach)
- ✅ Specific prompts if using WebFetch: "find MCPTool schema definition with authorization field"
- ✅ Read exact line numbers from Grep results
- ✅ Verify findings against the authoritative spec

### Example: Finding MCPTool Schema

**Ineffective approach:**
1. Use WebFetch with vague prompt: "search for OAuth tokens and MCP"
2. When that fails, try different WebFetch prompts
3. When that fails, search web for "OpenAI MCP OAuth"
4. Find outdated blog posts with incomplete information

**Effective approach:**
1. Download spec: `curl -o openai-spec.yml https://app.stainless.com/api/spec/documented/openai/openapi.documented.yml`
2. Search for all MCP references: `Grep pattern="MCP" path="openai-spec.yml" output_mode="content" -i=true`
3. Identify relevant line numbers (e.g., line 42619 for MCPTool schema)
4. Read exact schema: `Read file_path="openai-spec.yml" offset=42619 limit=100`
5. Examine complete field definitions including `authorization`, `headers`, `server_url`, etc.

## Usage in Code Reviews

When reviewing OpenAI integration code:
1. Identify which endpoints are being used
2. Fetch the official spec to validate endpoint paths and parameters
3. Check that all parameters match the specification exactly
4. Verify authentication implementation
5. Confirm error handling covers API response codes
6. Validate that streaming is implemented correctly if used

## Critical Security Considerations

- **API Keys**: Must never be hardcoded or committed to version control
- **B