--- title: "List the published template catalog" method: POST path: "/catalog/list" tags: ["Catalog"] --- # List the published template catalog `POST /catalog/list` ## Request - Base URL: `https://api.reportingninja.com/v1` - URL: `https://api.reportingninja.com/v1/catalog/list` - Auth: HTTP bearer Returns the published templates a report can be created from with /v1/reports/create-from-template, and whose sections a composition can copy. The catalog is the same for every account. With include_sections the entry also carries the 0-based position and the name of each of its sections -- what a catalog section of a composition names -- and the parameters a parameterized entry asks a value for. A parameterized entry can be materialized whole and cannot be used as a single section of a composition. ## Request body - CatalogListRequest: Which catalog to read and how much of it. - `language` 'en' | 'es': Language of the names and descriptions. Default en. - `include_sections` boolean: Add the sections and the parameters of every entry. Off by default because it costs a full read of each published version; turn it on when you are about to compose with a catalog section, because that is where its position comes from. ## Response `200` The call succeeded. This endpoint reports its errors with a real HTTP status, so a 200 always carries status=ok. - CatalogListResponse - `status` 'ok', required - `data` CatalogListData, required: The published catalog. It is global: every account sees the same entries. - `templates` CatalogTemplate[], required - `slug` string, required: The id a report is created from. - `version` integer, required: The published version of that entry. It is not sent when a section of it is used in a composition: the version published today is always the one taken. - `name` string, nullable, required: In the requested language. - `description` string, nullable, required: In the requested language. - `type` 'essential' | 'advanced' | 'reference', nullable, required: How complete the entry is. These are the three kinds this version names; an entry of a kind added later is published with the value it is stored under, outside this list. - `category` string, nullable, required: Lower case token of the category, spaces turned into underscores. - `required_integrations` object[], required: The integrations the entry cannot be materialized without. - `integration_id` string, nullable: Public id of the integration, or null when this source has no public id and cannot be addressed through the API. - `integration` string: Internal name of the source. Present only when integration_id is null. - `optional_integrations` object[], required: The integrations whose sections are skipped when they are not bound. - `integration_id` string, nullable: Public id of the integration, or null when this source has no public id and cannot be addressed through the API. - `integration` string: Internal name of the source. Present only when integration_id is null. - `parameterized` boolean, required: True when the entry asks for values before it can be materialized. A parameterized entry cannot be used as a section of a composition. - `sections` object[]: Present only when include_sections was true. - `position` integer, required: 0-based position, which is what a catalog section of a composition names. - `name` string, nullable, required - `integrations` object[], required - `integration_id` string, nullable: Public id of the integration, or null when this source has no public id and cannot be addressed through the API. - `integration` string: Internal name of the source. Present only when integration_id is null. - `required` boolean, required - `parameters` object[]: Present only when include_sections was true. The values a parameterized entry asks for. - `id` string, nullable, required - `type` string, nullable, required - `integrations` object[], required - `integration_id` string, nullable: Public id of the integration, or null when this source has no public id and cannot be addressed through the API. - `integration` string: Internal name of the source. Present only when integration_id is null. - `required` boolean, required - `count` integer, required - `meta` Meta, required - `request_id` string, required: Id of this request, useful when reporting an incident. - `timestamp` string, date-time, required: When the answer was built, in UTC. ## Other responses - `400`: The request was refused before anything was written. INVALID_REQUEST covers the framework refusals of every endpoint (the Content-Type is not application/json, the body could not be read, the body is not valid JSON). The report endpoints add their own: VALIDATION_FAILED with details.problems, UNKNOWN_PARAM with the path of the field the endpoint does not read, and the single-field refusals MISSING_REQUIRED_FIELD, INVALID_VALUE and APPEND_NOT_ALLOWED. The description of each operation lists the ones it emits. Everything else a body can get wrong arrives as an entry of details.problems rather than as the code of the envelope. - `401`: Invalid or missing Bearer token. - `413`: The request body is over 1 MB. The cap is applied before authentication, so this answer is refused without the key being read, and it carries the usual error envelope. - `429`: A budget was spent. RATE_LIMITED is the per-key read budget (300/minute, 5000/day) or the per-account write budget (60/minute, 1000/day). EMAIL_QUOTA_REACHED is the separate budget of 50 calls per account per day that send email, and its Retry-After points at the next UTC midnight. The Retry-After header gives the seconds until the more restrictive window resets. The X-RateLimit-* headers report the read budget, except on the 429 of a write, where they report the write budget. - `500`: Internal server error. --- [API](https://skmtc.dev/reportingninja/apis/reporting-ninja-api.md) · [All operations](https://skmtc.dev/reportingninja/apis/reporting-ninja-api/llms.txt) · [OpenAPI document](https://skmtc.dev/reportingninja/apis/reporting-ninja-api/revisions/13876c71be34?raw)