> ## Documentation Index
> Fetch the complete documentation index at: https://docs.recoupable.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Catalog

> Create a catalog.



## OpenAPI

````yaml post /api/catalogs
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
security: []
paths:
  /api/catalogs:
    post:
      description: Create a catalog.
      requestBody:
        description: >-
          Catalog to create. Provide name, snapshot, or both - at least one is
          required.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCatalogRequest'
      responses:
        '200':
          description: >-
            Catalog created, or the existing catalog returned when
            re-materializing the same snapshot (idempotent)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCatalogResponse'
        '400':
          description: >-
            Bad request - neither name nor snapshot provided, or invalid
            snapshot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogSongsErrorResponse'
        '401':
          description: Unauthorized - missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogSongsErrorResponse'
        '403':
          description: Forbidden - the snapshot belongs to a different account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogSongsErrorResponse'
        '404':
          description: Not found - no snapshot exists for the supplied snapshot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogSongsErrorResponse'
      security:
        - apiKeyAuth: []
        - bearerAuth: []
components:
  schemas:
    CreateCatalogRequest:
      type: object
      description: >-
        Request body for creating a catalog. At least one of name or snapshot
        must be supplied. The owning account is taken from the request
        credentials, never from this body.
      properties:
        name:
          type: string
          description: >-
            Optional. Display name for the catalog. If omitted when snapshot is
            supplied, a name is derived from the source run.
        snapshot:
          type: string
          format: uuid
          description: >-
            Optional. ID of a completed playcount snapshot (valuation run) owned
            by the authenticated account. Its measured ISRCs are added to the
            new catalog as catalog songs. Create one with [Create measurement
            job](/api-reference/research/measurement-jobs).
    CreateCatalogResponse:
      type: object
      description: Response returned after creating, or idempotently re-fetching, a catalog
      properties:
        status:
          type: string
          enum:
            - success
            - error
          description: Status of the request
        catalog:
          $ref: '#/components/schemas/Catalog'
        songs_added:
          type: integer
          description: >-
            Number of catalog songs materialized from the source. 0 when no
            snapshot was supplied, or when the run was already materialized
            (idempotent re-claim).
        error:
          type: string
          description: Error message (only present if status is 'error')
    CatalogSongsErrorResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - error
          description: Status of the request
        error:
          type: string
          description: Error message describing what went wrong
    Catalog:
      type: object
      description: A catalog with its metadata
      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
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Your Recoup API key. [Learn more](/quickstart#api-keys).
    bearerAuth:
      type: http
      scheme: bearer

````