# openapi

KrosAI provides a complete OpenAPI 3.0 specification for the API.

## Specification URL

```
https://api.krosai.com/v1/openapi.json
```

## Using the Specification

### Generate Client Libraries

{% tabs %}
{% tab title="TypeScript" %}

```bash
npx @openapitools/openapi-generator-cli generate \
  -i https://api.krosai.com/v1/openapi.json \
  -g typescript-fetch \
  -o ./krosai-client
```

{% endtab %}

{% tab title="Python" %}

```bash
npx @openapitools/openapi-generator-cli generate \
  -i https://api.krosai.com/v1/openapi.json \
  -g python \
  -o ./krosai-python
```

{% endtab %}
{% endtabs %}

### Import into Postman

{% stepper %}
{% step %}

### Open Postman

Open the Postman application.
{% endstep %}

{% step %}

### Import

Click **Import**.
{% endstep %}

{% step %}

### Select Link

Select **Link**.
{% endstep %}

{% step %}

### Paste URL

Paste:

```
https://api.krosai.com/v1/openapi.json
```

{% endstep %}

{% step %}

### Import File

Click **Import**.
{% endstep %}
{% endstepper %}

### Import into Insomnia

{% stepper %}
{% step %}

### Open Insomnia

Open the Insomnia application.
{% endstep %}

{% step %}

### Import/Export

Click **Import/Export** → **Import Data**.
{% endstep %}

{% step %}

### From URL

Select **From URL**.
{% endstep %}

{% step %}

### Enter URL

Enter:

```
https://api.krosai.com/v1/openapi.json
```

{% endstep %}
{% endstepper %}

## Specification Structure

```yaml
openapi: "3.0.3"
info:
  title: "KrosAI API"
  version: "1.0.0"
  description: "Connect AI voice agents to phone numbers"
  
servers:
  - url: https://api.krosai.com/v1
    description: Production
    
security:
  - ApiKeyAuth: []
  - BearerAuth: []
  
paths:
  /phone-numbers:
    get:
      summary: List phone numbers
      # ...
    post:
      summary: Purchase phone number
      # ...
      
  /endpoints:
    # ...
    
  /calls:
    # ...
    
  /outbound-calls:
    # ...
    
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
    BearerAuth:
      type: http
      scheme: bearer
      
  schemas:
    PhoneNumber:
      type: object
      properties:
        id:
          type: string
        number:
          type: string
        # ...
```

## Interactive Documentation

Visit our interactive API explorer:

[API Explorer](https://api.krosai.com/docs)

Features:

* Try API calls directly
* View request/response examples
* Authenticate with your API key
* Copy code samples

## Versioning

The API follows semantic versioning:

* Major versions (v1, v2): Breaking changes
* Minor updates: Backwards-compatible additions
* Patch updates: Bug fixes

The current version is `v1`. We maintain backwards compatibility within major versions.

## Changelog

### v1.0.0 (Current)

* Initial public release
* Phone Numbers API
* Endpoints API
* Calls API
* Outbound Calls API
* Webhooks API

### Upcoming

* v1.1.0: SDK session API improvements
* v1.2.0: Enhanced analytics endpoints

## SDKs

We recommend using official SDKs rather than generating clients:

* [@krosai/voice-sdk](https://www.npmjs.com/package/@krosai/voice-sdk) - JavaScript/TypeScript
* [@krosai/voice-sdk-react](https://www.npmjs.com/package/@krosai/voice-sdk-react) - React

[SDK Documentation](file:///sdks)

## Next Steps

* [Authentication](file:///authentication) - API key setup
* [Phone Numbers API](file:///numbers/buy-numbers) - Get started
* [Rate Limits](file:///reference/rate-limits) - Usage limits


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.krosai.com/developer-docs/reference/openapi.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.