Repository API

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:

Copy

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:

Copy

{
  "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.

Was this article helpful?

Not really

Yes, Thanks

Can't find what you're looking for? Spot an error in the documentation? Get in touch with us on our Community Forum or using the feedback form above.