# GrowSurf OpenAPI spec > The GrowSurf OpenAPI spec is the machine-readable OpenAPI 3.1 contract for the GrowSurf REST API, served at growsurf.com/openapi.json in JSON and YAML. - URL: https://growsurf.com/developers/openapi/ --- The machine-readable contract for the [GrowSurf REST API](https://docs.growsurf.com/developer-tools/rest-api). It is an OpenAPI 3.1 document, generated from the same source the API runs on, and served same-origin from growsurf.com so a client never has to guess a location. ## Where to fetch it Same-origin, no credential ``` https://growsurf.com/openapi.json https://growsurf.com/openapi.yaml https://growsurf.com/arazzo.yaml ``` - [openapi.json](/openapi.json) — the spec in JSON - [openapi.yaml](/openapi.yaml) — the same spec in YAML - [arazzo.yaml](/arazzo.yaml) — the Arazzo 1.1 onboarding workflow The same documents are served from the API itself at `https://api.growsurf.com/v2/openapi.json` and `https://api.growsurf.com/v2/openapi.yaml`. All of them are public: no API key is needed to read the spec. ## What it covers Every public REST v2 operation, with an `operationId`, a typed request and response schema, and a shared error schema that `4xx` and `5xx` responses reference. Each operation also lists the API-key scope it requires in `x-growsurf-required-scopes`, so a client can pick the smallest scope set before it asks a user for a credential. ## Generating a client The spec is valid input for code generators and for function-calling tool definitions. ### Prefer a published library where one exists GrowSurf maintains official TypeScript, Python, Ruby, PHP, and Java SDKs. They are hand-maintained, so they track the API more closely than a generated client will. All five are listed on [GrowSurf developer resources](/developers/). ## Versioning The API is versioned in the URL path (`/v2`). Before you build against the spec, read the [GrowSurf API lifecycle, versioning, and deprecation policy](/developers/api-lifecycle/): it says how long notice you get before a breaking removal, and which response fields signal one. ## Authentication Reading the spec needs no credential. Calling the API does. Request header ``` Authorization: Bearer ``` See [authentication](/developers/authentication/), or [auth.md](/auth.md) if you are an AI agent.