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

# Introduction

> Welcome to SpecCheck's API documentation

## Getting Started

To get started, make sure you are using the correct `client_id` and `client_secret` for the environment you are using.

## Staging Environment

For testing and development purposes, please use the staging API at `https://api-staging.speccheckrx.com`.

## Production Environment

For live deployments, access the production API at `https://api.speccheckrx.com`.

## Idempotent Requests

The API supports [idempotency](https://en.wikipedia.org/wiki/Idempotence) for safely retrying requests without accidentally performing the same operation twice. When creating or updating an object, send an idempotency key. If a connection error occurs, you can repeat the request without creating a duplicate object or applying the same update twice.

To perform an idempotent request, include an `Idempotency-Key` header.

The API saves the status code and body of the first request for each idempotency key. Subsequent requests with the same key return the same result.

Generate a unique idempotency key for each distinct operation. V4 UUIDs work well. Keys may be up to 255 characters. Do not use sensitive data (for example, email addresses or patient identifiers) as idempotency keys.

The idempotency layer compares incoming parameters to those of the original request and returns an error if they differ, to prevent accidental misuse.

All `POST` requests accept idempotency keys. Do not send idempotency keys on `GET` requests; they have no effect because those requests are idempotent by definition.

```bash theme={null}
curl -X POST "https://api.speccheckrx.com/v1/orders" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}" \
  -H "User-Email: {{USER_EMAIL}}" \
  -H "Idempotency-Key: KG5LxwFBepaKHyUD" \
  -d @order.json
```

## Error Handling

Errors return a JSON response with an error object describing what went wrong. Failed requests return HTTP 4xx or 5xx status codes.

The error object always includes type and message. When present, code is a stable, machine-readable string (for example, invalid\_request), and param identifies the related input field or header.

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "message": "Example message from the API.",
    "code": "invalid_request",
    "param": "User-Email"
  }
}
```

`code` and `param` are omitted when not applicable.

### Error Types

| `type`                  | Typical HTTP status | Meaning                       |
| ----------------------- | ------------------- | ----------------------------- |
| `invalid_request_error` | 400 (or other 4xx)  | Missing or invalid parameters |
| `authentication_error`  | 401                 | Authentication failed         |
| `permission_error`      | 403                 | Authenticated but not allowed |
| `api_error`             | 500                 | Internal server error         |

Error messages and status codes may vary by endpoint. Always use the **`error`** object together with the HTTP status when handling failures.