# Partner API Overview

The Partner API enables whitelabel partners to manage organizations, visitors, billing, and configuration programmatically. This documentation covers authentication, endpoints, and integration patterns.

## Base URL

All Partner API requests use the following base URL:

```
https://api.app.bullseye.so/api/v1
```

## Authentication

The Partner API uses API key authentication. Include your API key in the `X-Partner-API-Key` header with every request.

```
X-Partner-API-Key: your-api-key
```

See [Authentication](/partner-api/authentication.md) for details on obtaining keys and security best practices.

## Rate Limiting

The Partner API enforces a rate limit of **1,000 requests per minute** per partner account.

Rate limit information is returned in response headers:

| Header                  | Description                               |
| ----------------------- | ----------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed per minute       |
| `X-RateLimit-Remaining` | Requests remaining in the current window  |
| `X-RateLimit-Reset`     | Unix timestamp when the rate limit resets |

If you exceed the limit, the API returns `429 Too Many Requests`.

## Error Format

Errors are returned as JSON with a consistent structure:

```json
{
  "code": "error_code",
  "message": "Human-readable error message",
  "details": {}
}
```

### Standard Error Codes

| Code            | HTTP Status | Description                        |
| --------------- | ----------- | ---------------------------------- |
| `BadRequest`    | 400         | Invalid request parameters or body |
| `Unauthorized`  | 401         | Missing or invalid API key         |
| `NotFound`      | 404         | Resource not found                 |
| `InternalError` | 500         | Server error                       |

## Response Conventions

* Successful responses use standard HTTP status codes (200, 201, 204).
* JSON responses use camelCase for property names.
* Paginated endpoints return `page`, `pageSize`, and `total` (or equivalent) for navigation.
* Timestamps are in ISO 8601 format (e.g., `2025-01-15T10:30:00Z`).

## Endpoint Groups

| Section                                            | Description                                         |
| -------------------------------------------------- | --------------------------------------------------- |
| [Partner Account](/partner-api/partner-account.md) | Partner details, branding, and script configuration |
| [API Keys](/partner-api/api-keys.md)               | Create, list, and revoke API keys                   |
| [Organizations](/partner-api/organizations.md)     | CRUD for organizations, pixel config, and visitors  |
| [ICP Configs](/partner-api/icp-configs.md)         | Ideal Customer Profile segmentation rules           |
| [Webhooks](/partner-api/webhooks.md)               | Identification and billing webhook configuration    |
| [Billing](/partner-api/billing.md)                 | Credit allocation, usage, and billing info          |
| [Branding](/partner-api/branding.md)               | Logo, colors, and company name                      |
| [Domains](/partner-api/domains.md)                 | Custom domain setup and verification                |
| [Analytics](/partner-api/analytics.md)             | Usage and analytics data                            |


---

# 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.bullseye.so/partner-api/partner-api.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.