Repository API

This guide will teach you how to use the Repository API, which you'll use to retrieve basic information about your repository.

The Repository API is the gateway to your repository. When you query the Repository API, you get back some basic information about your repository, including the ID for the more recent version of your content: the master ref.

The Repository API endpoint is located on the same subdomain as your repository:

https://your-repo-name.cdn.prismic.io/api/v2

The Repository API is related to the Document API. Before you can query the Document API, you need to get a ref from the Repository API. The most important part of the API query is the refs array. A ref is an identifier for a specific version of your content, like draft, scheduled, or — most importantly — newest. Every time you publish changes, a new master ref is generated.

The current version of your content is the “master ref.” Prismic may store older refs. This ensures that a ref will work even if content has been changed since the request was initiated. However, in general, you should always use the most recent ref, as old refs will get purged eventually.

The refs array also contains a ref for each release in your repository.

Here is an example response from the Repository API:

{
  "refs": [
    {
      "id": "master",
      "ref": "ZG5h3BAAAB8AhmzJ",
      "label": "Master",
      "isMasterRef": true
    },
    {
      "id": "ZIBvwhAAACMAgx9w",
      "ref": "ZIBvwxAAACEAgx93~ZIBJVRAAACMAgmBd",
      "label": "",
      "scheduledAt": 1696633200000
    }
  ],
  "bookmarks": {},
  "experiments": {
    "draft": [],
    "running": []
  },
  "types": {
    "home": "Home",
    "pages": "Pages"
  },
  "languages": [
    {
      "id": "en-us",
      "name": "English - United States"
    },
    {
      "id": "en-gb",
      "name": "English - United Kingdom"
    }
  ],
  "forms": "// Omitted ",
  "oauth_initiate": "https://your-repo-name.prismic.io/auth",
  "oauth_token": "https://your-repo-name.prismic.io/auth/token",
  "tags": [],
  "license": "All Rights Reserved",
  "version": "482083b"
}

Here are all of the properties on the Repository API:

`refs` array	An array containing the available refs from your repository. To make a releases ref appear in your API response, provide a master+releases access token with your API query or set your repository’s API visibility to Open API. For more information, see the Access Token guide.
`refs[index]` object	An item in the `refs` array referring to a specific ref. The first item is always the master ref.
`refs[index].id` string	The unique identifier for the ref. For the master ref, this is `“master”` and for other refs, is an alphanumeric string. A release ref’s `id` is made up of two hashes separated by a hash symbol. The first hash in the ref is updated whenever a change is made in the release, such as another document being added or edited. The second hash in the ref is updated whenever a document in the repository is published.
`refs[index].label` string	A human-readable name for the ref. The master ref is always named `"Master"`, and by default, a scheduled release always has an empty label. A custom label can be set in the Page Builder.
`refs[index].isMasterRef` boolean	A boolean present if the current array item refers to the master ref.
`refs[index].scheduledAt` string	A string present if the current array item refers to a scheduled release ref. The `scheduledAt` string contains the Unix timestamp at which the release will be automatically published.
`bookmarks` object	The `bookmarks` property is deprecated. It refers to a feature that Prismic no longer supports.
`experiments` object	The `experiments` property is deprecated. It refers to a feature that Prismic no longer supports.
`types` object	A list of the repository’s type API IDs mapped to their human-readable name. For more details, see the Custom Types API technical reference.
`types[type_id]` array item	The display name for the type with the given ID.
`languages` object	A list of the repository’s locale IDs mapped to their human-readable name.
`languages[index]` object	An item in the `languages` array referring to a specific locale. The first item is always the master locale.
`languages[index].id` string	The locale ID of the language.
`languages[index].name` string	The locale display name of the language.
`forms` object	An object containing internally-used API features.
`oauth_initate` string	The URL used to begin the OAuth process for the repository when using a temporary access token. For more information, see the Access Token guide.
`oauth_token` string	The token used for the OAuth process when using a temporary access token. For more information, see the Access Token guide.
`tags` array	Will be empty as this field is deprecated. The tags field is now available inside the form fields. See “A change to how the Prismic API handles tags” for more information.
`license` string	The license for the repository content. The repository’s license can be changed with the API visibility setting. For more information, see the Access Token guide.
`version` string	The version identifier of the API. The version string is used internally for debugging purposes.