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

# API Overview

> Base URL, versioning, and the standard response format for the Broker Panel v1 API.

The Client v1 API connects your systems to Broker Panel. Use it to manage client services, process service requests, and send services or invoice reports.

## Base URL

Send production requests to this base URL:

```text theme={null}
https://brokers.newyorkcityservers.com/api/v1
```

Add the endpoint path to the base URL. For example, use this URL to list services:

```text theme={null}
https://brokers.newyorkcityservers.com/api/v1/services
```

Use HTTPS for all requests.

## Versioning

The version is part of the URL. All endpoints in this reference use `v1`.

Keep `/api/v1` in each request URL. An endpoint path in this reference starts after `/api`. For example, `GET /v1/services` maps to `GET https://brokers.newyorkcityservers.com/api/v1/services`.

## Authentication And Access

Every request needs an API key in the `Authorization` header. Use the Bearer scheme:

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

Use a Sandbox key to get simulated results without changes to business records. Read [Sandbox Mode](/api/sandbox-mode) for supported behavior.

## Request Conventions

The API uses JSON for request bodies and responses.

* Send `Content-Type: application/json` when an endpoint has a JSON body.
* Put filters and pagination values in the query string for list endpoints.
* Put service numbers and request IDs in the path when an endpoint identifies one record.
* Use the HTTP method that the endpoint page specifies. The v1 API uses `GET` for reads and `POST` for actions.

This example sends an authenticated list request:

```bash theme={null}
curl "https://brokers.newyorkcityservers.com/api/v1/services?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

## Success Responses

A successful response contains `success: true` and a `data` value.

```json theme={null}
{
  "success": true,
  "data": {
    "service_number": 971100004,
    "service_status": "active"
  }
}
```

Most successful requests return HTTP `200`. Some service and request actions return HTTP `202` when Broker Panel accepts the work for processing or review. A `202` response still uses `success: true`.

List endpoints can add a `pagination` object:

```json theme={null}
{
  "success": true,
  "data": [],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "total": 0,
    "totalPages": 0
  }
}
```

Use the HTTP status and the response body together. Check the endpoint page for its exact `data` fields.

## Error Responses

An error response contains `success: false`. The `error` object always contains a machine-readable `code` and a `message`. Some endpoint errors also contain a `details` object.

```json theme={null}
{
  "success": false,
  "error": {
    "code": "invalid_parameter",
    "message": "Invalid service number"
  }
}
```

The API uses these HTTP error statuses:

| Status | Meaning                                                                          | Common code                                                    |
| ------ | -------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `400`  | The request body, path value, or query value is not valid.                       | `invalid_request`, `missing_parameter`, or `invalid_parameter` |
| `401`  | The API key is missing, invalid, or expired.                                     | `authentication_failed`                                        |
| `403`  | The key lacks a required scope, or the request IP is not allowed.                | `insufficient_permissions`                                     |
| `404`  | The requested broker-owned record does not exist or is not available to the key. | `not_found`                                                    |
| `409`  | A manage-request action targeted a request that was already processed.           | `already_processed`                                            |
| `429`  | The API key has reached its rate limit.                                          | `rate_limit_exceeded`                                          |
| `500`  | The API could not complete the request.                                          | `server_error`                                                 |

A `429` response includes a `Retry-After` header. Its value is the number of seconds to wait before another request.

Do not retry a `400`, `401`, `403`, `404`, or `409` response without a change to the request or integration state. For a `500` response, keep the request details from your system logs and try again after a delay.