> For the complete documentation index, see [llms.txt](https://docs.salescaling.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.salescaling.com/en/api/introduction.md).

# Introduction

The Salescaling Public API provides programmatic access to manage your calls, meetings, users, contacts, and other data. This guide will help you get started with authentication and understand rate limiting policies.

## Authentication

### What is an API Key?

API keys are secure tokens that authenticate your requests to the Public API. Each key is unique and tied to your account, allowing you to access your data programmatically.

### How to Create an API Key

1. Go to **Settings > API Keys** in your Salescaling dashboard
2. Click the button **"Create New API Key"**
3. Enter a name for your key (e.g., "Production Integration", "Development")
4. Optionally, set an expiration date for added security
5. Click on **Create**
6. **Important**: Copy the key immediately - it will only be shown once
7. Store it securely (we recommend using environment variables or a secrets manager)

### Using Your API Key

* Include the API key in the header `x-api-key` for all requests
* All Public API endpoints are available at: `https://api.salescaling.com/api/v1/`
* Example request header: `x-api-key: your-api-key-here`

### Scopes (Permissions)

API keys use a scope system to control which actions they can perform. When creating an API key, you must select at least one scope:

#### Available Scopes

**Voice Agents:**

* `voice-agents:webhook` - Allows initiating calls via webhook
* `voice-agents:read` - Allows reading voice agent information
* `voice-agents:write` - Allows creating and modifying voice agents

**Contacts:**

* `contacts:read` - Allows reading contact information
* `contacts:write` - Allows creating and modifying contacts

**Companies:**

* `companies:read` - Allows reading company information
* `companies:write` - Allows creating and modifying companies

**Calls:**

* `calls:read` - Allows reading call information
* `calls:write` - Allows creating and modifying calls

**Meetings:**

* `meetings:read` - Allows reading meeting information
* `meetings:write` - Allows creating and modifying meetings

**Opportunities:**

* `opportunities:read` - Allows reading opportunity information
* `opportunities:write` - Allows creating and modifying opportunities

**Calendar:**

* `calendar:read` - Allows reading calendar information
* `calendar:write` - Allows creating and modifying calendar events

**Users:**

* `users:read` - Allows reading user information

#### Scopes Usage Example

If you only need to initiate calls via webhook, select only the scope `voice-agents:webhook`. This follows the principle of least privilege, granting only the necessary permissions.

### Permissions and Ownership

* API keys act on behalf of the user who created them
* Scopes limit what actions the API key can perform
* Any action performed using an API key will appear as if it were performed by the creating user
* For example, if you create a call using an API key, you will appear as the owner of that call
* Only create API keys for users with appropriate access levels
* Assign only the scopes needed for each API key

### Security Best Practices

* Never share your API keys or include them in version control
* Store keys in environment variables or a secure secrets manager
* Rotate keys regularly (every 90 days is recommended)
* Immediately delete unused or compromised keys
* Assign only the necessary scopes (least privilege principle)
* Create different API keys for different integrations or purposes
* Monitor your API key usage regularly
* Create separate keys for different environments (development, staging, production)
* Use read-only keys when you only need to retrieve data

### Managing Your API Keys

* View all your keys in **Settings > API Keys**
* Update key names or expiration dates at any time
* Delete keys you no longer need
* Note: Once created, the full key value cannot be retrieved again

## Rate Limiting

### Overview

To ensure fair usage and system stability, the API implements rate limiting on all endpoints.

### Rate Limits

Three concurrent limits apply to your requests:

* **Short term**: 20 requests per second
* **Medium term**: 200 requests per 10 seconds
* **Long term**: 1,000 requests per minute

### How It Works

* Limits are tracked by API key
* All three limits are active simultaneously
* If you exceed any limit, you will receive a 429 error response

### Handling Rate Limits

When you receive a 429 (Too Many Requests) response:

* Check the header `Retry-After` to know when to retry
* Wait the specified time before making another request
* Implement exponential backoff in your retry logic
* Example: wait 1s, then 2s, then 4s, etc. between retries

### Best Practices

* Cache API responses when possible to reduce requests
* Use webhooks instead of polling for real-time updates
* Batch operations when the API supports it
* Spread requests out over time instead of sending bursts
* Monitor your usage to stay within the limits
* If you need higher limits, contact support

## Quick Start Examples

### cURL

```bash
curl -X GET \\
  'https://api.salescaling.com/api/v1/users' \\
  -H 'x-api-key: your-api-key-here'
```

### JavaScript/TypeScript

```typescript
const response = await fetch("https://api.salescaling.com/api/v1/users", {
  headers: {
    "x-api-key": "your-api-key-here",
    "Content-Type": "application/json",
  },
});

const data = await response.json();
console.log(data);
```

### Python

```python
import requests

headers = {
    'x-api-key': 'your-api-key-here',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.salescaling.com/api/v1/users',
    headers=headers
)

data = response.json()
print(data)
```

### Node.js with axios

```javascript
const axios = require("axios");

const config = {
  headers: {
    "x-api-key": "your-api-key-here",
  },
};

axios
  .get("https://api.salescaling.com/api/v1/users", config)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.error("Error:", error.message);
  });
```

## Next Steps

* Explore the available endpoints in the API reference
* Learn about [Webhooks](/en/api/webhooks.md) for real-time notifications
* Check out our integration examples


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.salescaling.com/en/api/introduction.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.