> For the complete documentation index, see [llms.txt](https://developerdocs.instructure.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developerdocs.instructure.com/services/catalog.md).

# Catalog

So, you want to develop some tooling around the Catalog API - perhaps some custom reports? Great! This API gives you everything that Catalog has to offer.

## Authentication

Visit Catalog Admin API page to create an API key. Once you've received your key, **treat it like a password**.

Use SSL for all requests to the API. Non-SSL requests will result in redirects, and your API key will be sent in the clear.

To authenticate, send the API key as a request header. Here's an example using cURL:

```
curl https://[URL]/api/v1/products -H 'Authorization: Token token="my-api-key"'
```

## API key scope.

Every API key belongs to one catalog. That catalog sets what the key can see and change.

* **Root-account key.** The key belongs to your root catalog. It's unrestricted: it covers the root catalog and every subcatalog under it. "Unrestricted" is its own state. It doesn't mean "an empty list of catalogs".
* **Sub-account key.** The key belongs to a subcatalog. It covers that subcatalog and every subcatalog below it (its *subtree*). It never covers the parent catalog, the root catalog, or sibling subcatalogs.

Read-only keys follow the same scope rules, and they can't write. A write request usually returns `401`. Some checks run first, though. A read-only sub-account key gets `403` from an endpoint that only a root-account key can use (account admins, `PUT /api/v1/email_domain_sets/{id}`, tag writes, and `DELETE /api/v1/users/{id}`). It also gets `422` for a course or program body with an `account_id` outside its subtree. A course or program body with `tag_names` still returns `401` for a read-only key, because the permission check runs first there.

### How a sub-account key is limited.

A sub-account key meets its scope in one of three ways:

1. **Filtered.** List endpoints return only records inside the subtree. Records outside it are left out without an error.
2. **Not found or invalid.** A request for a single record outside the subtree returns `404`. A request body or query parameter that points at a catalog, listing, or user outside the subtree usually returns `422`. The certificate and completed certificate endpoints return `404` instead.
3. **Rejected.** Some endpoints and fields need a root-account key. A sub-account key gets `403 Forbidden` with this body:

   ```
    {
      "errors": [
        { "message": "This endpoint requires a root-account API key" }
      ]
    }
   ```

   When the request is rejected because of a field, the message names the field, for example `"Only a root-account API key may set tag_names"`.

### Endpoints that need a root-account key.

| Endpoint                                                                                                                               | What a sub-account key gets                    |
| -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| `GET`, `POST /api/v1/account_admins`, `DELETE /api/v1/account_admins/{id}`, `DELETE /api/v1/account_admins/{id}/accounts/{account_id}` | `403`                                          |
| `PUT /api/v1/email_domain_sets/{id}`                                                                                                   | `403`                                          |
| `POST /api/v1/tags`, `PUT /api/v1/tags/{id}`, `DELETE /api/v1/tags/{id}`, `DELETE /api/v1/tags/bulk`                                   | `403`                                          |
| `DELETE /api/v1/users/{id}`                                                                                                            | `403`                                          |
| `POST /api/v1/courses`, `PUT /api/v1/courses/{id}`, `POST /api/v1/programs`, `PUT /api/v1/programs/{id}` with `tag_names` in the body  | `403`, even when `tag_names` is `[]` or `null` |

**Why can't a sub-account key delete users?** A user's enrollments and orders can span sibling subcatalogs. Deleting the user would reach records outside the key's subtree, so the delete can't be limited to one subcatalog. Use a root-account key.

### Tags: sub-account keys can read them but not write them.

This looks contradictory at first, so here it is plainly:

* A sub-account key **can read** tags through `GET /api/v1/tags` and `GET /api/v1/tags/{id}`.
* A sub-account key **can't create, edit, or delete** tags. It also **can't send `tag_names`** when it creates or updates a course or program.

Tags belong to the root catalog, not to a subcatalog. That's why tag reads are tenant-wide. A tag's `assigned_listings` can include listings from sibling subcatalogs (their id, title, type, Canvas course id, and `archived_at`), even though `GET /api/v1/courses/{id}` returns `404` for those same listings. A tag's `assigned_categories` can include categories from sibling subcatalogs, so their `account_id` values show which sibling subcatalogs exist. The `product_ids` and `name` filters on `GET /api/v1/tags` can target those sibling listings directly. Tag payloads never include enrollment or order data.

**Watch out for read-modify-write.** `GET /api/v1/courses/{id}` and `GET /api/v1/programs/{id}` always return `tag_names`. If a sub-account key sends that payload back unchanged in a `PUT`, the request fails with `403`. Remove `tag_names` from the body before you send it.

`associated_account_ids` works differently. A sub-account key can't **add or remove** a catalog outside its subtree, but it can send one back unchanged. So a fetched payload that lists a sibling catalog is fine as is. Dropping that catalog from the list returns `422`.

### Users.

* `GET /api/v1/users` returns only users registered in the key's subtree. Users without a registered catalog don't appear for a sub-account key. That's expected.
* `GET /api/v1/users/{id}` returns `404` for a user registered outside the subtree, or a user with no registered catalog.
* `PUT /api/v1/users/{id}` returns `404` for a user outside the subtree, and `422` when `registered_account_id` points outside the subtree.
* `POST /api/v1/users` always registers the user in the key's own catalog. The API ignores any `registered_account_id` that a sub-account key sends.

### Analytics.

`POST /api/v1/analytics/{type}` limits results to the key's scope:

* When `account_ids` is missing or empty, you get everything the key can see. For a root-account key, that's the whole root catalog. For a sub-account key, that's its subtree. An empty `account_ids` never means "no results".
* When `account_ids` includes a catalog outside the subtree, the request fails with `403`. This response comes from a different service, so the body looks different: `{ "error": "...", "details": ... }`.
* Send at least one filter field in the body, such as `timezone`. A request with an empty body returns `400 "No request body provided"`.

### Orders.

* `GET /api/v1/orders` and `GET /api/v1/orders/{id}` return an order when the key's subtree sold it, or when the order includes a listing that belongs to the subtree. That covers a sibling catalog selling one of your listings.
* You get the whole order, not only your own line items: every listing in it (including other catalogs' listings), the order total, its payments, and the purchaser's name and email. `catalog` is the catalog that sold it.
* A deleted order item doesn't count toward this. A listing deleted later still does: orders keep showing listings after they're deleted.

### Every endpoint at a glance.

| Endpoint                                                                | Sub-account key behavior                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/v1/account_admins*`                                               | Rejected (`403`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `/api/v1/analytics/{type}`                                              | Filtered; `403` for `account_ids` outside the subtree                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `/api/v1/applicants`, `/api/v1/applicants/{id}`                         | Filtered; `404` outside the subtree; `DELETE` for an outside listing returns `304`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `/api/v1/catalogs`, `/api/v1/catalogs/{id}`                             | Filtered to the key's catalog and its subcatalogs; `404` outside                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `/api/v1/certificates`, `/api/v1/certificates/revoke_users_certificate` | `404` when the listing is outside the subtree                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `/api/v1/completed_certificates`                                        | Filtered to listings in the subtree; a `canvas_course_id` outside the subtree returns `404`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `/api/v1/courses`, `/api/v1/programs`                                   | `GET`: filtered; `422` for an `account_id` outside the subtree. `POST`: `403` with `tag_names`; `422` for an `account_id` outside the subtree, or for adding or removing an `associated_account_ids` entry outside it. Programs only: `422` for a `requirement_ids` entry that is not an integer listing id, or that adds or removes a listing outside the subtree                                                                                                                                                                                                                                                                     |
| `/api/v1/courses/{id}`, `/api/v1/programs/{id}`                         | `GET`, `DELETE`: `404` outside the subtree. `PUT`: `422` for an `account_id` outside the subtree, `403` for `tag_names`, and `404` for a listing outside the subtree. When a body has more than one of these problems, which error comes back isn't guaranteed. An `associated_account_ids` entry that can't be read as an integer id returns `422`, and so does adding or removing an entry outside the subtree. Programs only: `requirement_ids` follows the same rule as on `POST`. A sub-account key can resubmit a requirement that is already on the program, even when it sits outside the subtree, but can't add or remove one |
| `/api/v1/courses/archived`, `/api/v1/programs/archived`                 | Filtered: ids outside the subtree are skipped                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `/api/v1/courses/update_skus`                                           | Filtered: only courses in the subtree are updated                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `/api/v1/email_domain_sets*`                                            | `GET`: allowed for `account` and `account_readonly` keys, and covers the whole tenant, not only the subtree. `PUT`: needs a root-account key, otherwise `403`                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `/api/v1/enrollments`, `/api/v1/enrollments/{id}`                       | Filtered; `404` outside the subtree; `POST` returns `422` for a listing outside the subtree                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `/api/v1/order_items/history/bulk_enrollments*`                         | `410 Gone` (unified checkout). Removed November 2, 2026; see "Removed endpoints"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `/api/v1/orders`, `/api/v1/orders/{id}`                                 | Orders the subtree sold, plus orders that include a listing the subtree owns; `404` otherwise. See "Orders" above                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `/api/v1/progresses/{id}`                                               | `404` outside the subtree                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `/api/v1/promotions/bulk`                                               | `422` for an `account_id` or `listing_id` outside the subtree                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `/api/v1/tags`, `/api/v1/tags/{id}`                                     | `GET`: allowed, tenant-wide. Writes: rejected (`403`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `/api/v1/tags/bulk`                                                     | Rejected (`403`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `/api/v1/users`, `/api/v1/users/{id}`                                   | See the Users section above. `DELETE`: rejected (`403`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

## Pagination

All index endpoints support pagination. Specifically, we implement [RFC5988](http://tools.ietf.org/html/rfc5988).

#### Pagination Options

You can use `?page=` to set the page of data you want to retrieve. If no items exist for that page, the response will be a root key with an empty array.

```
curl https://[URL]/api/v1/courses?page=2

{
  "courses": []
}
```

To change the number of items returned for each page, you can use `?per_page=`. This defaults to 20 and has a max of 100.

```
curl https://[URL]/api/v1/courses?per_page=40&page=2
```

#### Link Headers

Information about pagination is provided in the Link header. Here is an example of what the header could look like

```
curl -I https://[URL]/api/v1/courses?page=3

Link: <https://[URL]/api/v1/courses?page=4>; rel="next",  
      <https://[URL]/api/v1/courses?page=15>; rel="last",
      <https://[URL]/api/v1/courses?page=1>; rel="first",
      <https://[URL]/api/v1/courses?page=2>; rel="prev"
```

Let's talk about what each link means. `rel="next"` lets us know that the next page of data is `page=4`. This make sense given that we requested page 3. `rel="prev"` lets us know that the page previous to the one we requested is `page=2`. `rel="next"` indicates the next page of data to request. `rel="last"` tells us the last and total number of pages of data that currently exist.

Not all `rel=` links will exist on every response. For instance, the response for the first page of data will not have `rel="first"` or `rel="prev"`. The same is true for the last page of data. This means that you can programmatically traverse all pages of data by requesting the first page and continuing to request the `rel="next"` until the response does not contain a `rel="next"`.

It's important to note that altering the `per_page=` will change the total number of pages.

#### Listing Image

Listing image uploads must be JPG, JPEG, PNG, or GIF files. Other file types are rejected.

```
curl https://[URL]/api/v1/products -F "course[listing_image]=@somefile.png"
```

## Removed endpoints

These endpoints were removed on November 2, 2026. They now return `410 Gone`.

* `GET /api/v1/order_items/history/bulk_enrollments`
* `GET /api/v1/order_items/history/bulk_enrollments/{id}`

Bulk purchase and purchase order orders are listed by `GET /api/v1/orders?source=bulk_purchase` and `?source=purchase_order`. Redeemed seats are returned in `bulk_enrollments` by `POST /api/v1/analytics/orders`. Pending invitations have no API replacement.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developerdocs.instructure.com/services/catalog.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
