# Download OpenAPI

Use this page to retrieve the latest Bead OpenAPI specification in JSON format.

The OpenAPI file is useful for:

* reviewing available endpoints, request bodies, and response models
* generating client libraries
* validating requests and responses
* aligning internal tooling with the current public schema

### What you can download

| Asset      | Purpose                                      | Format |
| ---------- | -------------------------------------------- | ------ |
| OpenAPI v1 | Full REST specification for public endpoints | JSON   |

#### Download

* **OpenAPI v1 (JSON):** <https://api.test.devs.beadpay.io/openapi/v1.json>

### Base URLs referenced by the specification

| Environment | REST API base URL                  |
| ----------- | ---------------------------------- |
| Sandbox     | `https://api.test.devs.beadpay.io` |
| Production  | `https://api.beadpay.io`           |

#### Notes

* Use Sandbox for functional testing and integration QA.
* Use Production for live merchant traffic and settlement.
* Keep Sandbox and Production credentials separate.
* Store environment-specific values in configuration so switching environments is not a code change.

### Authentication notes

Bead supports multiple authentication methods depending on the API family you are calling.

#### Payments

Payments endpoints use terminal API key authentication.

Send:

```http
X-Api-Key: {apiKey}
```

Important:

* `apiKey` is the usable secret credential
* `maskedApiKey` is not usable

#### Onboarding and related administrative APIs

Use the authentication method documented on the specific product-area page. Where onboarding and related admin/entity-management guides show API key authentication, send:

```http
X-Api-Key: {apiKey}
```

Do not assume a single authentication method applies to every Bead API. Always follow the documentation for the endpoint family you are using.

### Working with the OpenAPI file

You can use the OpenAPI specification to:

* inspect available paths and methods
* review required headers and request bodies
* confirm response models and status codes
* generate SDKs or typed clients with your preferred tooling
* import the file into internal API tools that support OpenAPI

### Versioning and updates

| Topic                  | Guidance                                                                                |
| ---------------------- | --------------------------------------------------------------------------------------- |
| Spec version           | OpenAPI v1 is the current public specification                                          |
| Backward compatibility | Breaking changes are announced on the Changelog and communicated to registered partners |
| Refresh cadence        | Re-download the OpenAPI file when you see a relevant update on the Changelog            |

### Troubleshooting

| Symptom                                          | Likely cause                                | Fix                                                                                        |
| ------------------------------------------------ | ------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Generated client does not match current behavior | Local spec file is outdated                 | Download the latest OpenAPI file again                                                     |
| 401 on API requests                              | Wrong credential type or invalid credential | Confirm the authentication method for that API family and verify the credential being sent |
| 404 on a known endpoint                          | Wrong base URL or environment               | Confirm you are using the correct Sandbox or Production host                               |
| Validation errors on request bodies              | Request shape does not match schema         | Compare your request body against the OpenAPI model and required fields                    |

### Next steps

| Action                                      | Where                                                |
| ------------------------------------------- | ---------------------------------------------------- |
| Review shared conventions and auth guidance | [Reference Guide](/reference-guide.md)               |
| Explore methods and paths                   | [Endpoint Index](/reference-guide/endpoint-index.md) |
| Review onboarding workflows                 | [Onboarding](/onboarding.md)                         |
| Review payment workflows                    | [Payments](/payments.md)                             |
| See recent API changes                      | [Changelog](/changelog.md)                           |


---

# 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://developers.bead.xyz/reference-guide/endpoint-index/download-openapi.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.