> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hirepanda.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Introduction

> Build powerful integrations with HirePanda's REST API

## Overview

The HirePanda API enables you to integrate our AI-powered hiring platform into your applications and workflows. Build custom integrations, automate workflows, and access your hiring data programmatically.

<Info>
  **Base URL**: `https://api.hirepanda.com/api/v1`\
  **Current Version**: v1\
  **Protocol**: HTTPS only
</Info>

## Quick Start

<Steps>
  <Step title="Get Your API Key">
    Generate an API key from your [dashboard settings](https://valley.hirepanda.com/settings/api)
  </Step>

  <Step title="Make Your First Request">
    ```bash theme={null}
    curl -H "Authorization: Bearer YOUR_API_KEY" \
      https://api.hirepanda.com/api/v1/jobs
    ```
  </Step>

  <Step title="Explore Endpoints">
    Use our interactive API explorer or check the endpoint documentation
  </Step>
</Steps>

## Authentication

All API requests require authentication using a Bearer token in the Authorization header:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

<Warning>
  Keep your API keys secure and never expose them in client-side code. Use environment variables and rotate keys regularly.
</Warning>

### API Key Management

**Key Features:**

* Multiple keys per account
* Granular permissions
* Usage tracking
* Key rotation support

**Best Practices:**

* Use different keys for different environments
* Implement key rotation every 90 days
* Monitor key usage in analytics
* Revoke unused keys immediately

## Rate Limiting

To ensure fair usage and platform stability:

<CardGroup cols={2}>
  <Card title="Standard Limits" icon="gauge">
    * **1,000** requests per hour
    * **10,000** requests per day
    * **100** concurrent requests
  </Card>

  <Card title="Enterprise Limits" icon="rocket">
    * **10,000** requests per hour
    * **100,000** requests per day
    * **1,000** concurrent requests
  </Card>
</CardGroup>

**Rate Limit Headers:**

```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
```

## Request Format

### Headers

Required headers for all requests:

```http theme={null}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json
```

### Request Body

All POST/PUT requests should send JSON:

```json theme={null}
{
  "job": {
    "title": "Senior Software Engineer",
    "department": "Engineering",
    "location": "Remote"
  }
}
```

## Response Format

### Successful Response

```json theme={null}
{
  "data": {
    "id": "job_123",
    "title": "Senior Software Engineer",
    "created_at": "2024-01-01T00:00:00Z"
  },
  "meta": {
    "request_id": "req_abc123"
  }
}
```

### Error Response

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "Invalid request parameters",
    "details": {
      "title": "Title is required"
    }
  },
  "meta": {
    "request_id": "req_abc123"
  }
}
```

## Common Patterns

### Pagination

List endpoints support pagination:

```bash theme={null}
GET /api/v1/jobs?page=2&per_page=50
```

**Pagination Response:**

```json theme={null}
{
  "data": [...],
  "meta": {
    "current_page": 2,
    "per_page": 50,
    "total_pages": 10,
    "total_count": 500
  }
}
```

### Filtering

Use query parameters for filtering:

```bash theme={null}
GET /api/v1/candidates?status=active&score_min=80
```

### Sorting

Sort results using the `sort` parameter:

```bash theme={null}
GET /api/v1/jobs?sort=-created_at,title
```

Use `-` prefix for descending order.

### Field Selection

Request specific fields only:

```bash theme={null}
GET /api/v1/jobs?fields=id,title,status
```

## Data Types

### Common Fields

| Field        | Type     | Description              |
| ------------ | -------- | ------------------------ |
| `id`         | string   | Unique identifier (UUID) |
| `created_at` | datetime | ISO 8601 timestamp       |
| `updated_at` | datetime | ISO 8601 timestamp       |
| `status`     | enum     | Object status            |

### Enumerations

**Job Status:**

* `draft` - Not yet published
* `active` - Accepting applications
* `paused` - Temporarily inactive
* `closed` - No longer accepting

**Candidate Status:**

* `new` - Just applied
* `screening` - Taking assessment
* `review` - Under review
* `interview` - Interview stage
* `offer` - Offer extended
* `hired` - Offer accepted
* `rejected` - Not moving forward

## Webhooks

Set up webhooks to receive real-time updates:

```json theme={null}
POST /api/v1/webhooks
{
  "url": "https://your-app.com/webhook",
  "events": ["application.created", "assessment.completed"],
  "secret": "your_webhook_secret"
}
```

[Learn more about webhooks →](/api-reference/webhooks/overview)

## SDKs & Libraries

Official SDKs for popular languages:

<CodeGroup>
  ```bash npm theme={null}
  npm install @hirepanda/sdk
  ```

  ```bash pip theme={null}
  pip install hirepanda
  ```

  ```bash gem theme={null}
  gem install hirepanda
  ```

  ```bash composer theme={null}
  composer require hirepanda/sdk
  ```
</CodeGroup>

## API Explorer

Try out API endpoints directly in your browser:

<Card title="Interactive API Explorer" icon="code" href="https://api.hirepanda.com/explorer" horizontal>
  Test endpoints with your API key in a safe environment
</Card>

## Environments

| Environment | Base URL                                   | Purpose   |
| ----------- | ------------------------------------------ | --------- |
| Production  | `https://api.hirepanda.com/api/v1`         | Live data |
| Sandbox     | `https://sandbox-api.hirepanda.com/api/v1` | Testing   |

<Tip>
  Use the sandbox environment for development and testing. It provides full API functionality with test data that resets daily.
</Tip>

## Versioning

API versions are included in the URL path:

* Current: `/api/v1/`
* Legacy: `/api/v0/` (deprecated)

**Version Policy:**

* New versions for breaking changes only
* Minimum 6-month deprecation notice
* Version sunset after 12 months
* Clear migration guides provided

## Support

<CardGroup cols={3}>
  <Card title="API Status" icon="signal" href="https://status.hirepanda.com">
    Real-time API health
  </Card>

  <Card title="Changelog" icon="clock-rotate-left" href="/api-reference/changelog">
    Latest updates
  </Card>

  <Card title="Support" icon="headset" href="mailto:api@hirepanda.com">
    Technical assistance
  </Card>
</CardGroup>

## Next Steps

<Steps>
  <Step title="Authentication">
    [Set up authentication](/api-reference/authentication) and get your API key
  </Step>

  <Step title="Create a Job">
    [Post your first job](/api-reference/jobs/create) via the API
  </Step>

  <Step title="Manage Candidates">
    [Track candidates](/api-reference/candidates/list) through your pipeline
  </Step>

  <Step title="Set Up Webhooks">
    [Configure webhooks](/api-reference/webhooks/overview) for real-time updates
  </Step>
</Steps>