Add OpenAPI and Swagger documentation

fern/api-reference/openapi.md

@@ -0,0 +1,53 @@
+---
+title: OpenAPI
+slug: api-reference/openapi
+---
+
+# OpenAPI
+
+Vapi provides an OpenAPI specification that describes our REST API endpoints. This allows developers to easily integrate Vapi's voice AI capabilities into their applications.
+
+## Accessing the OpenAPI Specification
+
+The OpenAPI specification for Vapi's API can be accessed at:
+
+```
+https://api.vapi.ai/openapi.json
+```
+
+You can use this URL to import the API definition into API development tools and documentation generators.
+
+## Key Endpoints
+
+Some of the key endpoints described in the OpenAPI specification include:
+
+- `/v1/assistants` - Manage AI assistants
+- `/v1/calls` - Initiate and manage voice calls  
+- `/v1/phone-numbers` - Provision and configure phone numbers
+- `/v1/tools` - Define custom tools for assistants to use
+
+Refer to the full OpenAPI specification for complete details on all available endpoints, request/response schemas, and authentication requirements.
+
+## Using with Swagger UI
+
+You can explore and test the API interactively using Swagger UI:
+
+1. Go to [https://editor.swagger.io](https://editor.swagger.io)
+2. Click File > Import URL
+3. Enter `https://api.vapi.ai/openapi.json`
+4. Click on any endpoint to see details and try it out
+
+## SDKs
+
+Vapi provides official SDKs generated from the OpenAPI spec for easy integration:
+
+- [JavaScript/TypeScript SDK](https://www.npmjs.com/package/@vapi-ai/web)
+- [Python SDK](https://pypi.org/project/vapi-ai/)
+
+The SDKs offer type-safe access to all API functionality.
+
+## Versioning 
+
+The OpenAPI specification is versioned along with the API. Be sure to check for any breaking changes when updating to a new API version.
+
+For questions or issues related to the OpenAPI specification, please [contact Vapi support](/support).

fern/api-reference/swagger.md

@@ -0,0 +1,48 @@
+---
+title: Swagger
+slug: api-reference/swagger
+---
+
+# Swagger
+
+Vapi provides a Swagger UI interface for exploring and testing our API endpoints. The Swagger documentation is generated from our OpenAPI specification.
+
+To access the Swagger UI, visit:
+
+[https://api.vapi.ai/swagger](https://api.vapi.ai/swagger)
+
+## Key Features
+
+- Interactive API documentation
+- Try out API requests directly from the browser
+- Automatically generated request samples
+- Detailed information on request parameters and response schemas
+
+## Using Swagger UI
+
+1. Navigate to the Swagger UI page
+2. Browse the available endpoints grouped by resource
+3. Click on an endpoint to expand its details
+4. Use the "Try it out" button to make test API calls
+5. Provide any required parameters
+6. Execute the request and view the response
+
+## Authentication
+
+To use the Swagger UI for testing authenticated endpoints:
+
+1. Click the "Authorize" button at the top of the page
+2. Enter your API key in the value field
+3. Click "Authorize" to apply the authentication
+
+Your API key will then be included in subsequent test requests.
+
+## OpenAPI Specification
+
+The full OpenAPI specification that powers our Swagger documentation is available at:
+
+[https://api.vapi.ai/openapi.json](https://api.vapi.ai/openapi.json)
+
+This specification can be used to generate API clients in various programming languages.
+
+For more details on our OpenAPI implementation, see the [OpenAPI documentation](/api-reference/openapi).