---
title: "OpenAPI Specification (OAS) API Documentation Sync"
description: "Overview"
canonical_url: "https://help.brainfi.sh/articles/openapi-specification-oas-api-documentation-sync-44eThAIs7j"
md_url: "https://help.brainfi.sh/articles/openapi-specification-oas-api-documentation-sync-44eThAIs7j.md"
---
# OpenAPI Specification (OAS) API Documentation Sync
## Overview
This guide will help you set up the OpenAPI Specification (OAS) integration with Brainfish to import your API documentation and make it available for AI-powered assistance. The integration allows you to upload OpenAPI/Swagger specification files and automatically generate detailed usage scenarios for each API endpoint.
## Prerequisites
Before you begin, ensure you have:
1. **OpenAPI Specification File**: A valid OpenAPI 3.0 or Swagger 2.0 specification file (JSON or YAML format)
2. **Brainfish Account**: A Brainfish account with appropriate permissions
3. **File Access**: The ability to upload files to your Brainfish workspace
4. **API Documentation**: Well-documented API endpoints with summaries and descriptions
## Step 1: Prepare Your OpenAPI Specification File
### 1. Validate Your OAS File
1. **Check File Format**
* Ensure your file is in JSON or YAML format
* Supported extensions: `.json`, `.yaml`, `.yml`
* Maximum file size: 50MB
2. **Verify OAS Version**
* OpenAPI 3.0.x (recommended)
* Swagger 2.0 (supported)
* Check the `openapi` or `swagger` field in your specification
3. **Review API Documentation**
* Ensure each endpoint has a `summary` field
* Add detailed `description` fields where possible
* Include request/response examples for better AI context
### 2. Optimize Your Specification
1. **Add Meaningful Summaries**
```yaml
/users/{id}:
get:
summary: "Retrieve user information by ID"
description: "Fetches detailed user information including profile data, preferences, and account status"
```
2. **Include Request Examples**
```yaml
/users:
post:
summary: "Create a new user"
requestBody:
content:
application/json:
example:
name: "John Doe"
email: "john@example.com"
```
3. **Document Response Schemas**
```yaml
responses:
200:
description: "User created successfully"
content:
application/json:
schema:
$ref: "#/components/schemas/User"
```
## Step 2: Set Up Integration in Brainfish
### 1. Access Knowledge Section
1. **Log into Brainfish**
* Go to your Brainfish dashboard
* Navigate to the **"Knowledge"** section in the left sidebar
2. **Create New Source**
* Click **"Add Source"** or **"New Source"**
* This opens the source configuration dialog
### 2. Select OpenAPI Specification
1. **Choose Source Type**
* In the source type selector, choose **"OpenAPI Specification"**
* You'll see the OAS configuration panel
### 3. Upload Your Specification File
1. **Select File**
* Click **"Choose File"** or drag and drop your OAS file
* Supported formats: `.json`, `.yaml`, `.yml`
* Maximum size: 50MB
2. **File Validation**
* The system will automatically validate your file format
* Ensure the file contains valid OpenAPI/Swagger specification
* Check for any validation errors in the interface
3. **Upload Process**
* The file will be uploaded to secure cloud storage
* You'll see a progress indicator during upload
* Wait for the upload to complete before proceeding
### 4. Configure Sync Settings
1. **Enable Daily Sync** (Recommended)
* Toggle **"Enable daily sync"** to automatically keep your API documentation up-to-date
* This will re-process your OAS file daily at 2:00 AM UTC
2. **Save Configuration**
* Click **"Save"** to create your OAS integration
* The system will begin processing your specification file
## Step 3: Monitor Processing and Verification
### 1. Initial Processing
1. **Background Processing**
* After saving, the system processes your OAS file in the background
* This may take several minutes depending on the number of endpoints
* You can monitor progress in the Knowledge section
2. **AI Context Generation**
* For each API endpoint, the system generates detailed usage scenarios
* This includes user/system context, goals, parameters, expected behavior, and examples
* The AI analyzes your specification to create realistic documentation
### 2. Verify Content Import
1. **Check Imported Endpoints**
* Once processing is complete, your API endpoints will appear in Brainfish
* Each endpoint will have generated documentation and usage scenarios
* You can search for specific endpoints or API functionality
2. **Review Generated Content**
* Navigate to the Knowledge section to see your imported API documentation
* Each endpoint will include:
* Original API path and method
* Generated usage scenarios
* Parameter descriptions
* Request/response examples
## Step 4: Enable for AI Agents
### 1. Configure Agent Access
1. **Access Agent Settings**
* Go to the **"Agents"** section in Brainfish
* Select the agent you want to enable for API documentation
2. **Enable OAS Source**
* In the agent's knowledge sources, enable your OAS integration
* This allows the agent to reference your API documentation when answering questions
### 2. Test AI Integration
1. **Ask API Questions**
* Use the chat interface to ask questions about your API
* Example questions:
* "How do I create a new user?"
* "What parameters are required for the authentication endpoint?"
* "Show me an example of the user update request"
2. **Verify Responses**
* The AI should provide detailed, contextual answers based on your API specification
* Responses should include code examples and usage scenarios
## Troubleshooting
### Common Issues
#### 1. "Invalid OAS File Format" Error
**Possible Causes:**
* File is not a valid OpenAPI/Swagger specification
* Incorrect file format (not JSON or YAML)
* Malformed JSON or YAML syntax
**Solutions:**
* Validate your OAS file using online tools like [Swagger Editor](https://editor.swagger.io/)
* Check for syntax errors in your JSON or YAML
* Ensure the file contains `openapi` or `swagger` field
#### 2. "File Size Exceeds Limit" Error
**Possible Causes:**
* OAS file is larger than 50MB
* File contains excessive examples or documentation
**Solutions:**
* Remove unnecessary examples or detailed descriptions
* Split large APIs into multiple specification files
* Use references to external files for large schemas
#### 3. "No Endpoints Found" Error
**Possible Causes:**
* OAS file doesn't contain any paths
* All endpoints are missing required fields
* File structure is incorrect
**Solutions:**
* Ensure your OAS file has a `paths` section with endpoint definitions
* Add `summary` fields to all endpoints
* Verify the file structure follows OpenAPI specification
#### 4. "Processing Failed" Error
**Possible Causes:**
* Large number of endpoints causing timeout
* Network connectivity issues
* AI service temporarily unavailable
**Solutions:**
* The system will automatically retry processing
* For large APIs, processing may take longer
* Check system status and try again later
#### 5. "AI Context Generation Failed" Error
**Possible Causes:**
* Endpoints lack sufficient documentation
* AI service rate limits
* Complex endpoint structures
**Solutions:**
* Add more detailed descriptions to your endpoints
* Include request/response examples
* The system will fall back to basic endpoint information
### File Requirements
Your OAS file must meet these requirements:
* **Format**: JSON or YAML
* **Size**: Maximum 50MB
* **Version**: OpenAPI 3.0.x or Swagger 2.0
* **Structure**: Must contain valid `paths` section
* **Content**: At least one endpoint with `summary` field
### Processing Limitations
The OAS integration has the following limitations:
* **File Size**: Maximum 50MB per file
* **Endpoints**: No limit on number of endpoints
* **Processing Time**: Varies based on file size and endpoint count
* **AI Context**: Generated for each endpoint with sufficient documentation
## Best Practices
### 1. API Documentation Quality
* **Write clear summaries**: Each endpoint should have a descriptive summary
* **Include examples**: Add request/response examples for better AI understanding
* **Document parameters**: Provide detailed parameter descriptions
* **Use consistent naming**: Follow consistent naming conventions across your API
### 2. File Organization
* **Keep files focused**: Split large APIs into domain-specific files
* **Use references**: Reference external schema files to reduce file size
* **Version control**: Keep your OAS files in version control
* **Regular updates**: Update your specification when APIs change
### 3. Integration Management
* **Monitor sync status**: Check sync status regularly in the Knowledge section
* **Update specifications**: Upload new versions when APIs are updated
* **Test AI responses**: Regularly test AI responses to ensure accuracy
* **Review generated content**: Verify that generated usage scenarios are accurate
### 4. Security Considerations
* **Remove sensitive data**: Ensure your OAS file doesn't contain API keys or secrets
* **Use examples carefully**: Avoid including real user data in examples
* **Review before upload**: Double-check your specification before uploading
## Advanced Configuration
### 1. Custom AI Prompts
The system uses AI to generate detailed usage scenarios for each endpoint. The generated content includes:
* **User/System Context**: Who or what is using the API
* **Goal**: What the user aims to achieve
* **Data/Parameters**: Required information and parameters
* **Expected Behavior**: How the endpoint should behave
* **Business Value**: Benefits provided by the endpoint
* **Payload Examples**: Sample request payloads
### 2. Sync Scheduling
* **Daily Sync**: Automatically processes your OAS file daily at 2:00 AM UTC
* **Manual Sync**: Trigger manual sync from the Knowledge section
* **Real-time Updates**: Upload new versions anytime to update content
### 3. Content Management
* **Automatic Updates**: New endpoints are automatically added
* **Removed Endpoints**: Endpoints removed from the specification are automatically removed from Brainfish
* **Content Versioning**: Previous versions are maintained for reference
## Support and Resources
### Getting Help
If you encounter issues with the OAS integration:
1. **Check Documentation**: Review this guide for common solutions
2. **Validate Your File**: Use [Swagger Editor](https://editor.swagger.io/) to validate your OAS file
3. **Contact Support**: Reach out to the Brainfish support team
### Useful Resources
* **OpenAPI Specification**:
* **Swagger Editor**:
* **OpenAPI Examples**:
### Contact Information
For technical support or questions about the OAS integration:
* **Email**: [support@brainfi.sh](mailto:support@brainfi.sh)
* **Documentation**:
* **Status Page**: