# Gracenote GN IDS API

**Canonical:** https://apis.io/apis/gracenote/gn-ids-api/  
**Provider:** Gracenote — https://apis.io/providers/gracenote/  
**Base URL:** https://gnids.gracenote.com/api/v1  
**Documentation:** https://devportal.gracenote.com/video/gn-ids-api/about-gn-ids-api

Gracenote GN IDS API is one of 21 APIs that [Gracenote](https://apis.io/providers/gracenote/) publishes on the [APIs.io](https://apis.io/) network, described by a machine-readable OpenAPI specification. Tagged areas include Content Distribution, Content Metadata, Identifiers, Publishing, and Video Metadata. The published artifact set on APIs.io includes an OpenAPI specification, an API reference, and a changelog.

The GN IDS API is the only write surface Gracenote publishes. It lets content providers create, retrieve, update, delete and publish programs into Gracenote-licensed datasets across 85+ countries using Gracenote's video IDs — movie roots, versions and presentations, show roots, versions, presentations, seasons and episodes, plus images, catalogs, bulk batches and exports. 45 of its 74 operations mutate state.

## Operations (60 of 74)

| Method | Path | Summary |
|---|---|---|
| GET | `/bulk/movies/batches` | Retrieve bulk movie batches. |
| POST | `/bulk/movies/batches` | Create a new bulk movies batch. |
| GET | `/bulk/movies/batches/{gnID}` | Search for movie batch using its GnID. |
| GET | `/bulk/programs/exports` | Returns a paginated collection of exports in a source's catalog. |
| POST | `/bulk/programs/exports` | creates a new export with user provided filters |
| GET | `/bulk/programs/exports/{gnID}` | — |
| GET | `/bulk/programs/exports/{gnID}/results` | Fetches the results for an export by its GNID |
| POST | `/bulk/publish` | Submit multiple presentations for publish. |
| GET | `/bulk/shows/batches` | Retrieve bulk show batches. |
| POST | `/bulk/shows/batches` | Create a new bulk shows batch. |
| GET | `/bulk/shows/batches/{gnID}` | Search for show batch using its GnID. |
| POST | `/catalogPrograms` | Adds presentations to a catalog. |
| PATCH | `/catalogPrograms` | Remove presentation(s) from a Catalog. |
| GET | `/catalogs` | Query Catalogs. |
| PUT | `/catalogs` | Update a Catalog. |
| POST | `/catalogs` | Create a new Catalog. |
| GET | `/catalogs/{gnID}` | Query Catalog using gnID. |
| DELETE | `/catalogs/{gnID}` | Delete Catalog. |
| GET | `/gnvocabulary` | Retrieve the Gracenote Vocabulary. |
| GET | `/images` | — |
| POST | `/images` | Create a new image. |
| GET | `/images/{gnID}` | Query an image using its gnID. |
| PUT | `/images/{gnID}` | Update an existing image. |
| DELETE | `/images/{gnID}` | Delete an image using its gnID. |
| POST | `/movies` | Create a movie root. |
| GET | `/movies/{gnID}` | Query for a movie's root with the provided gnID. |
| PUT | `/movies/{gnID}` | Update a movie root identified by the provided gnID. |
| DELETE | `/movies/{gnID}` | Delete a movie's root with the provided gnID. |
| POST | `/movies/{rootGnID}/versions` | Create a movie version under a movie root given the root's gnID. |
| GET | `/movies/versions` | Query for movie versions which match the provided search criteria. |
| GET | `/movies/versions/{gnID}` | Query for a version of a movie with the provided gnID. |
| PUT | `/movies/versions/{gnID}` | Update a movie version identified by the provided gnID. |
| DELETE | `/movies/versions/{gnID}` | Delete a movie's version with the provided gnID. |
| POST | `/movies/versions/{versionGnID}/presentations` | Create a movie presentation under a movie version given the version's gnID. |
| PATCH | `/movies/versions/presentationRelationships` | Map movie presentations to versions. |
| DELETE | `/movies/versions/presentationRelationships/{gnID}` | Delete version mapping from a movie presentation. |
| GET | `/movies/versions/presentations` | Query for movie presentations associated with the provided filter criteria. |
| POST | `/movies/versions/presentations` | Create a new movie presentation without a movie version. |
| GET | `/movies/versions/presentations/{gnID}` | Query for a movie presentation with the provided gnID. |
| PUT | `/movies/versions/presentations/{gnID}` | Update a movie presentation identified by the provided gnID. |
| DELETE | `/movies/versions/presentations/{gnID}` | Delete a presentation of a movie with the provided gnID. |
| GET | `/programImages` | Search for program-image mappings. |
| POST | `/programImages` | Map an image to a presentation (movie, show, season or episode) using their gnIDs. |
| PATCH | `/programImages` | Delete a mapping between an image and a presentation (movie, show, season or episode) using their gnIDs. |
| GET | `/programSummaries` | Returns a paginated collection of program summaries in a source's catalog. The query supports optional filtering and sorting. |
| GET | `/publications` | Retrieve presentations' publish status. |
| POST | `/publish` | Submit a presentation for publish. |
| POST | `/shows` | Create a show root. |
| GET | `/shows/{gnID}` | Query for the root of a show with the provided gnID. |
| PUT | `/shows/{gnID}` | Update a show root identified by the provided gnID. |
| DELETE | `/shows/{gnID}` | Delete a show's root with the provided gnID. |
| POST | `/shows/{gnID}/versions` | Create a show version under a show root given the root's gnID. |
| GET | `/shows/versions` | Query for show versions which match the provided search criteria. |
| GET | `/shows/versions/{gnID}` | Query for a show's version with the provided gnID. |
| PUT | `/shows/versions/{gnID}` | Update a show version identified by the provided gnID. |
| DELETE | `/shows/versions/{gnID}` | Delete a show's version with the provided gnID. |
| POST | `/shows/versions/{gnID}/presentations` | Create a show presentation under a show version given the version's gnID. |
| PATCH | `/shows/versions/presentationRelationships` | Map show presentations to versions. |
| DELETE | `/shows/versions/presentationRelationships/{gnID}` | Delete version mapping from a show presentation. |
| GET | `/shows/versions/presentations` | Query for show presentations associated with the provided filter criteria. |

…and 14 more operations. They are listed in full on the page.

## Machine-readable artifacts (5)

- **OpenAPI** — https://raw.githubusercontent.com/api-evangelist/gracenote/refs/heads/main/openapi/gracenote-gn-ids-api-openapi.json
- **Overlay** — https://raw.githubusercontent.com/api-evangelist/gracenote/refs/heads/main/overlays/gracenote-gn-ids-api-overlay.yaml
- **APIReference** — https://devportal.gracenote.com/catalog/gnids
- **ChangeLog** — https://devportal.gracenote.com/video/gn-ids-api/release-notes
- **AgentSkill** — https://raw.githubusercontent.com/api-evangelist/gracenote/refs/heads/main/skills/gracenote-publish-a-movie-to-gn-ids.md

## Other Gracenote APIs (12)

- [Gracenote OnConnect API](https://apis.io/apis/gracenote/onconnect-api/)
- [Gracenote OnConnect Data API](https://apis.io/apis/gracenote/onconnect-data-api/)
- [Gracenote Celebrities API](https://apis.io/apis/gracenote/gracenote-celebrities-api/)
- [Gracenote Lineups API](https://apis.io/apis/gracenote/gracenote-lineups-api/)
- [Gracenote Movies API](https://apis.io/apis/gracenote/gracenote-movies-api/)
- [Gracenote Programs API](https://apis.io/apis/gracenote/gracenote-programs-api/)
- [Gracenote Series API](https://apis.io/apis/gracenote/gracenote-series-api/)
- [Gracenote Sports API](https://apis.io/apis/gracenote/gracenote-sports-api/)
- [Gracenote Stations API](https://apis.io/apis/gracenote/gracenote-stations-api/)
- [Gracenote On API](https://apis.io/apis/gracenote/on-api/)
- [Gracenote OnConnect Lookup APIs](https://apis.io/apis/gracenote/onconnect-lookup-apis/)
- [Gracenote GVD API](https://apis.io/apis/gracenote/gvd-api/)

## Tags

Content Distribution, Content Metadata, Identifiers, Publishing, Video Metadata

---

Profiled by [API Evangelist](https://apievangelist.com) and published on [APIs.io](https://apis.io/apis/gracenote/gn-ids-api/). The API's provider profile, Kin Score and agent-readiness rating are at https://apis.io/providers/gracenote/.