# Get Catalogs

Source: https://recoupable.dev/docs/api-reference/songs/catalogs

Retrieve the catalogs visible to a specific account. Returns the catalogs the account owns directly, plus the catalogs owned by any organization the account belongs to - so every member of an organization sees that organization's catalogs without passing the organization's id. A catalog owned both directly and through an organization is returned once. An account that belongs to no organization receives only its own catalogs. Create an organization-owned catalog with [Create catalog](/api-reference/songs/catalogs-create) or [Run valuation](/api-reference/songs/valuation-run).

## GET /api/accounts/{id}/catalogs

Full OpenAPI specification: https://recoupable.dev/docs/spec/releases.json

## Authentication

The supplied specification does not declare an OpenAPI security object for this operation. Its declared headers and parameters still apply. Consult the authentication guide and the full specification before calling it.

[Authentication guide](https://recoupable.dev/docs/authentication)

## Operation and referenced schemas

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Recoup API - Releases",
    "description": "API documentation for the Recoup platform - an AI agent platform for the music industry",
    "license": {
      "name": "MIT"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.recoupable.dev"
    }
  ],
  "paths": {
    "/api/accounts/{id}/catalogs": {
      "get": {
        "description": "Retrieve the catalogs visible to a specific account. Returns the catalogs the account owns directly, plus the catalogs owned by any organization the account belongs to - so every member of an organization sees that organization's catalogs without passing the organization's id. A catalog owned both directly and through an organization is returned once. An account that belongs to no organization receives only its own catalogs. Create an organization-owned catalog with [Create catalog](/api-reference/songs/catalogs-create) or [Run valuation](/api-reference/songs/valuation-run).\n\nEach catalog carries its estimated value band and its owner, so a list of catalogs can be ranked by worth and a member can tell an organization's catalog from their own. `valuation` is null for a catalog with no measured songs; `owner.image` is null when the owner account has no avatar.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "The unique identifier of the account to query. The catalogs of every organization this account belongs to are included in the response.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Catalogs retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing or invalid account id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogsErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogsErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - caller lacks access to the target account",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogsErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Account not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogsErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogsErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CatalogsResponse": {
        "type": "object",
        "description": "Response containing catalogs data",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "success",
              "error"
            ],
            "description": "Status of the request"
          },
          "catalogs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CatalogListItem"
            },
            "description": "Array of catalog objects, each with its estimated value and its owner"
          },
          "error": {
            "type": "string",
            "description": "Error message (only present if status is 'error')"
          }
        }
      },
      "CatalogsErrorResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "error"
            ],
            "description": "Status of the request"
          },
          "error": {
            "type": "string",
            "description": "Error message describing what went wrong"
          }
        }
      },
      "CatalogListItem": {
        "type": "object",
        "description": "A catalog as returned by [Get catalogs](/api-reference/songs/catalogs): the catalog plus its estimated value and its owner. Only this list carries those two fields - the create and rename responses return the bare catalog.",
        "required": [
          "id",
          "name",
          "created_at",
          "updated_at",
          "measured_song_count",
          "valuation",
          "owner"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for the catalog"
          },
          "name": {
            "type": "string",
            "description": "Name of the catalog"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO timestamp of when the catalog was created"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO timestamp of when the catalog was last updated"
          },
          "measured_song_count": {
            "type": "integer",
            "description": "Songs in the catalog with at least one play-count measurement. 0 for a catalog that was never measured, in which case valuation is null."
          },
          "valuation": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ValuationBand"
              },
              {
                "type": "null"
              }
            ],
            "description": "Estimated value band - the same schema and model as [Get catalog measurements](/api-reference/songs/catalog-measurements) returns, so a list and the report it opens cannot disagree. Null when nothing in the catalog has been measured; clients should say so rather than render $0."
          },
          "owner": {
            "$ref": "#/components/schemas/CatalogOwner"
          }
        }
      },
      "ValuationBand": {
        "type": "object",
        "description": "Estimated catalog value in USD, derived at read time from the latest measurements - the same model as the recoupable.dev valuation card. Annual run-rate = lifetime streams / catalog age (lifetime-average proxy), converted to net label share (all-DSP gross-up 1.25/1.4/1.6, 15% distribution fee, 25% royalty share, $0.0035 per Spotify stream) and multiplied by a 10x/13x/16x master-catalog market multiple.",
        "properties": {
          "low": {
            "type": "number",
            "description": "Low estimate in USD (1.25x gross-up, 10x multiple)"
          },
          "mid": {
            "type": "number",
            "description": "Central estimate in USD (1.4x gross-up, 13x multiple)"
          },
          "high": {
            "type": "number",
            "description": "High estimate in USD (1.6x gross-up, 16x multiple)"
          }
        }
      },
      "CatalogOwner": {
        "type": "object",
        "description": "The account a catalog belongs to. A catalog owned both directly and through an organization reports the organization - that is the ownership worth surfacing to a member.",
        "required": [
          "id",
          "name",
          "image",
          "is_organization"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Owner account id"
          },
          "name": {
            "type": "string",
            "nullable": true,
            "description": "Owner display name, null when the account has none"
          },
          "image": {
            "type": "string",
            "nullable": true,
            "description": "Owner avatar URL from account_info, null when the account has no image. Clients should fall back to initials rather than render a broken image."
          },
          "is_organization": {
            "type": "boolean",
            "description": "True when the owner is an organization the caller belongs to, false when it is a personal account"
          }
        }
      }
    }
  }
}
```