> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/reference-guide/endpoint-index/download-openapi.md). # 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 schema ### What you can download | Asset | Purpose | Format | | ---------- | ------------------------------------------------ | ------ | | OpenAPI v1 | Full REST specification for documented endpoints | JSON | #### Download * **OpenAPI v1 (JSON):** {% hint style="info" %} **A Bead login is required.** The OpenAPI file is available to registered partners only. Opening the link prompts you to sign in. If you do not have a login, contact [Integration Support](/reference-guide/support-and-contacts/integration-support.md) and request OpenAPI access. {% endhint %} #### Request access Email with the subject line `OpenAPI access request` and include: * your company name * the name and email address of each person who needs access * the environment you are integrating against (Sandbox, Production, or both) Integration Support sets up the login and replies with sign in details. ### 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 The login used to download the OpenAPI file is separate from your API credentials. It does not authenticate API requests. 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 or 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 Because the file requires a login, tools and coding agents usually cannot fetch the URL directly. Download the file while signed in, then import or attach the local copy. ### Versioning and updates | Topic | Guidance | | ---------------------- | --------------------------------------------------------------------------------------- | | Spec version | OpenAPI v1 is the current 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 | | ------------------------------------------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------- | | Prompted to sign in when opening the OpenAPI link | The file requires a Bead login | Sign in with your Bead login. If you do not have one, request access from Integration Support | | Tool or coding agent cannot fetch the OpenAPI URL | The URL requires a signed in session | Download the file while signed in and import or attach the local copy | | 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 | | ------------------------------------------- | ----------------------------------------------------------------------------------- | | Request OpenAPI access | [Integration Support](/reference-guide/support-and-contacts/integration-support.md) | | 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 This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://developers.bead.xyz/reference-guide/endpoint-index/download-openapi.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.