# 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 **"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 **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 scopes system to control what 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 information about voice agents
* `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

#### Example Use of Scopes

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 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 necessary 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 (recommended every 90 days)
* Immediately delete keys that are unused or compromised
* Assign only the necessary scopes (principle of least privilege)
* Create different API keys for different integrations or purposes
* Monitor the usage of your API keys regularly
* Create separate keys for different environments (development, staging, production)
* Use read-only keys when you only need to retrieve data

### Manage 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 value of the key cannot be retrieved again

## Rate Limiting

### Summary

To ensure fair use 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 per 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 over time instead of sending bursts
* Monitor your usage to stay within 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 our integration examples


---

# 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.salescaling.com/en/api/introduction.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.