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

# Versioning

> What may change within v1, how breaking changes and deprecations are announced, and how to write a client that keeps working.

The version is in the path: `https://api.pinakelai.com/v1`. There is no version header.

## What can change within v1

v1 only grows. These changes can happen at any time, announced in the [changelog](https://docs.pinakelai.com/changelog.md):

* new endpoints;
* new optional query parameters and `include` values;
* new fields in responses, including inside nested objects;
* new values in open enumerations, such as `status.value`, `mark.feature`, `mark.kind`, the feed's `type`, and error `code`s;
* new problem `type`s and new response headers;
* reworded `title` and `detail` texts in errors.

Anything else, such as removing or renaming a field, changing a field's type or meaning, or making an optional parameter required, is a breaking change and ships as `/v2`.

## Deprecation

Before a version or an endpoint is retired, its responses carry:

| Header | Standard | Meaning |
| - | - | - |
| `Deprecation: @1811808000` | [RFC 9745](https://www.rfc-editor.org/rfc/rfc9745) | The resource is deprecated as of this time, in seconds since 1970 (here 1 June 2027) |
| `Sunset: Wed, 01 Dec 2027 00:00:00 GMT` | [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594) | When it stops working |
| `Link: <https://docs.pinakelai.com/changelog>; rel="deprecation"` | [RFC 9745](https://www.rfc-editor.org/rfc/rfc9745) | Where the replacement is described |

The `Sunset` date is at least six months after the deprecation is announced. Log these headers when you see them; they are exposed to browsers too.

## Outside the stability guarantee

* **`source_record`** (`include=source_record`): the stored source document, whose structure can change without notice.
* **`RateLimit` and `RateLimit-Policy` header syntax**, until the IETF draft is final.
* **`name_key` values**, which change when name normalization improves. The field itself is stable.
* **The format of cursors and of the uid part of ids.** Both are opaque: store and send them, never parse them. The `tm_` prefix and register code of an id are stable.
* **The order of keys in JSON objects** and of records with equal sort values beyond the documented tie-break.

## Writing a client that keeps working

* Ignore fields you do not know.
* Treat an unknown enumeration value as `other`, and an unknown feed `type` as something to skip.
* Branch on error `type`, never on `title` or `detail`.
* If you generate types from [`/v1/openapi.json`](https://api.pinakelai.com/v1/openapi.json), allow additional properties. Response enumerations there are marked `x-extensible-enum`: generate them as open strings, not closed enums.
* Follow the changelog. It names every change that could matter to you.

## Earlier paths

Pinakel's earlier record API at `/data/v1` has been retired.

| Path | Response |
| - | - |
| `/data`, `/data/docs` | 301 to this site |
| `/data/v1/health` | The same response as `/v1/health`, for now |
| Other `/data/*` paths | 410 [`removed`](https://docs.pinakelai.com/errors/removed), with a pointer to `/v1` |
| `/openapi.json` | 301 to `/v1/openapi.json` |
| `/docs`, `/products` | 302 to this site |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.