openapi: 3.0.3
info:
  title: 'Chordal Licensing API'
  description: ''
  version: 1.0.0
servers:
  -
    url: 'https://api.chordal.com'
paths:
  /v1/licensing/preclearedPrograms:
    get:
      summary: 'GET v1/licensing/preclearedPrograms'
      operationId: gETV1licensingpreclearedPrograms
      description: ''
      parameters:
        -
          in: query
          name: name
          description: 'The name of the pre-cleared program to search.'
          example: Euphoria
          required: false
          schema:
            type: string
            description: 'The name of the pre-cleared program to search.'
            example: Euphoria
            nullable: false
        -
          in: query
          name: order_by
          description: 'The field by which to order results. Supported values: `id`, `name`, `created_at`. Default: `id`.'
          example: name
          required: false
          schema:
            type: string
            description: 'The field by which to order results. Supported values: `id`, `name`, `created_at`. Default: `id`.'
            example: name
            nullable: false
        -
          in: query
          name: sort_type
          description: 'The sorting direction. Supported values: `asc`, `desc`. Default: `asc`.'
          example: asc
          required: false
          schema:
            type: string
            description: 'The sorting direction. Supported values: `asc`, `desc`. Default: `asc`.'
            example: asc
            nullable: false
        -
          in: query
          name: page
          description: 'The page number for pagination. Default: 1.'
          example: 2
          required: false
          schema:
            type: integer
            description: 'The page number for pagination. Default: 1.'
            example: 2
            nullable: false
        -
          in: query
          name: per_page
          description: 'Number of results per page. Default: 15.'
          example: 20
          required: false
          schema:
            type: integer
            description: 'Number of results per page. Default: 15.'
            example: 20
            nullable: false
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: 1
                      name: 'Program Name'
                      description: 'A brief description of the program.'
                      media: 'TV and Streaming'
                      territory: 'United States'
                      term: '1 Year'
                      duration: 'Up to 0:60'
                      subscription_starts_at: '2025-03-21T12:00:00Z'
                      subscription_ends_at: '2026-03-21T12:00:00Z'
                      usage_starts_at: '2025-03-21T12:00:00Z'
                      usage_ends_at: '2026-03-21T12:00:00Z'
                      payment_deadline_at: '2026-03-21T12:00:00Z'
                      created_at: '2025-03-21T12:00:00Z'
                  links:
                    first: 'https://api.chordal.com/v1/licensing/preclearedPrograms?page=1'
                    last: 'https://api.chordal.com/v1/licensing/preclearedPrograms?page=10'
                    prev: null
                    next: 'https://api.chordal.com/v1/licensing/preclearedPrograms?page=2'
                  meta:
                    current_page: 1
                    from: 1
                    last_page: 10
                    path: 'https://api.chordal.com/v1/licensing/preclearedPrograms'
                    per_page: 15
                    to: 15
                    total: 150
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: 1
                        name: 'Program Name'
                        description: 'A brief description of the program.'
                        media: 'TV and Streaming'
                        territory: 'United States'
                        term: '1 Year'
                        duration: 'Up to 0:60'
                        subscription_starts_at: '2025-03-21T12:00:00Z'
                        subscription_ends_at: '2026-03-21T12:00:00Z'
                        usage_starts_at: '2025-03-21T12:00:00Z'
                        usage_ends_at: '2026-03-21T12:00:00Z'
                        payment_deadline_at: '2026-03-21T12:00:00Z'
                        created_at: '2025-03-21T12:00:00Z'
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        name:
                          type: string
                          example: 'Program Name'
                        description:
                          type: string
                          example: 'A brief description of the program.'
                        media:
                          type: string
                          example: 'TV and Streaming'
                        territory:
                          type: string
                          example: 'United States'
                        term:
                          type: string
                          example: '1 Year'
                        duration:
                          type: string
                          example: 'Up to 0:60'
                        subscription_starts_at:
                          type: string
                          example: '2025-03-21T12:00:00Z'
                        subscription_ends_at:
                          type: string
                          example: '2026-03-21T12:00:00Z'
                        usage_starts_at:
                          type: string
                          example: '2025-03-21T12:00:00Z'
                        usage_ends_at:
                          type: string
                          example: '2026-03-21T12:00:00Z'
                        payment_deadline_at:
                          type: string
                          example: '2026-03-21T12:00:00Z'
                        created_at:
                          type: string
                          example: '2025-03-21T12:00:00Z'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: 'https://api.chordal.com/v1/licensing/preclearedPrograms?page=1'
                      last:
                        type: string
                        example: 'https://api.chordal.com/v1/licensing/preclearedPrograms?page=10'
                      prev:
                        type: string
                        example: null
                      next:
                        type: string
                        example: 'https://api.chordal.com/v1/licensing/preclearedPrograms?page=2'
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 10
                      path:
                        type: string
                        example: 'https://api.chordal.com/v1/licensing/preclearedPrograms'
                      per_page:
                        type: integer
                        example: 15
                      to:
                        type: integer
                        example: 15
                      total:
                        type: integer
                        example: 150
      tags:
        - 'InstantClear Templates'
  '/v1/licensing/projects/{project_id}/tracks/{track_id}/licenses':
    post:
      summary: 'POST v1/licensing/projects/{project_id/tracks/{track_id}/licenses'
      operationId: pOSTV1licensingprojectsprojectIdtrackstrackIdlicenses
      description: ''
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: SYNCHID-1.1
                    total_reported_royalties: 1000
                    external_id: EXT-12345
                    period_starts: '2024-10-01'
                    period_ends: '2024-12-31'
                    created_at: '2024-09-25T12:34:56Z'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: SYNCHID-1.1
                      total_reported_royalties:
                        type: integer
                        example: 1000
                      external_id:
                        type: string
                        example: EXT-12345
                      period_starts:
                        type: string
                        example: '2024-10-01'
                      period_ends:
                        type: string
                        example: '2024-12-31'
                      created_at:
                        type: string
                        example: '2024-09-25T12:34:56Z'
      tags:
        - Licenses
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                brief_title:
                  type: string
                  description: 'The title of the brief. If not present the default will be "Usage Report DD/MM/YYYY (Period: dd/mm/yyyy - dd/mm/yyyy)".'
                  example: 'Upbeat, emotional electronic tracks'
                  nullable: false
                links:
                  type: array
                  description: 'Must match the regex /^(https?:\/\/)?(www\.)?[a-zA-Z0-9\-]+\.[a-zA-Z]{2,}.*$/i.'
                  example:
                    - 'http://Ac.A{2,}:t$/i'
                  items:
                    type: string
                total_reported_royalties:
                  type: integer
                  description: 'The price of the license in cents (required if the InstantClear rate type is METERED).'
                  example: 1000
                  nullable: false
                period_starts:
                  type: date
                  description: 'The start date of the license usage (required if monetization program rate type is METERED).'
                  example: '2024-10-01'
                  nullable: false
                period_ends:
                  type: date
                  description: 'The end date of the license usage (must be after `period_starts`, required if monetization program rate type is METERED).'
                  example: '2024-12-31'
                  nullable: false
                external_id:
                  type: string
                  description: 'An optional external identifier for the license.'
                  example: '"EXT-12345"'
                  nullable: false
                metadata:
                  type: object
                  description: 'Additional metadata for the license.'
                  example:
                    key: value
                  nullable: false
                  properties: {  }
    parameters:
      -
        in: path
        name: project_id
        description: 'The project ID.'
        example: 1
        required: true
        schema:
          type: integer
      -
        in: path
        name: track_id
        description: 'The track ID.'
        example: 10
        required: true
        schema:
          type: integer
  /v1/licensing/projects:
    get:
      summary: 'GET v1/licensing/projects'
      operationId: gETV1licensingprojects
      description: ''
      parameters:
        -
          in: query
          name: title
          description: 'The title of the project to search.'
          example: Euphoria
          required: false
          schema:
            type: string
            description: 'The title of the project to search.'
            example: Euphoria
            nullable: false
        -
          in: query
          name: license_status
          description: 'The status of the license. Supported values: `all-active`, `pending-confirmation`, `pending-pay`, `paid`.'
          example: all-active
          required: false
          schema:
            type: string
            description: 'The status of the license. Supported values: `all-active`, `pending-confirmation`, `pending-pay`, `paid`.'
            example: all-active
            nullable: false
        -
          in: query
          name: order_by
          description: 'The field by which to order results. Supported values: `id`, `title`, `created_at`. Default: `id`.'
          example: title
          required: false
          schema:
            type: string
            description: 'The field by which to order results. Supported values: `id`, `title`, `created_at`. Default: `id`.'
            example: title
            nullable: false
        -
          in: query
          name: sort_type
          description: 'The sorting direction. Supported values: `asc`, `desc`. Default: `asc`.'
          example: asc
          required: false
          schema:
            type: string
            description: 'The sorting direction. Supported values: `asc`, `desc`. Default: `asc`.'
            example: asc
            nullable: false
        -
          in: query
          name: page
          description: 'The page number for pagination. Default: 1.'
          example: 2
          required: false
          schema:
            type: integer
            description: 'The page number for pagination. Default: 1.'
            example: 2
            nullable: false
        -
          in: query
          name: per_page
          description: 'Number of results per page. Default: 15.'
          example: 20
          required: false
          schema:
            type: integer
            description: 'Number of results per page. Default: 15.'
            example: 20
            nullable: false
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: 1
                      title: 'Project Title'
                      slug: project-title
                      short_title: 'Short Title'
                      description: 'A brief description of the project.'
                      preclearedProgram:
                        id: 1
                        name: 'Program Name'
                      tags:
                        -
                          id: 1
                          name: 'Tag Name 1'
                      image_url: 'https://cdn.chordal.com/image.jpg'
                      created_at: '2025-03-21T12:00:00Z'
                  links:
                    first: 'https://api.chordal.com/v1/licensing/projects?page=1'
                    last: 'https://api.chordal.com/v1/licensing/projects?page=10'
                    prev: null
                    next: 'https://api.chordal.com/v1/licensing/projects?page=2'
                  meta:
                    current_page: 1
                    from: 1
                    last_page: 10
                    path: 'https://api.chordal.com/v1/licensing/projects'
                    per_page: 15
                    to: 15
                    total: 150
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: 1
                        title: 'Project Title'
                        slug: project-title
                        short_title: 'Short Title'
                        description: 'A brief description of the project.'
                        preclearedProgram:
                          id: 1
                          name: 'Program Name'
                        tags:
                          -
                            id: 1
                            name: 'Tag Name 1'
                        image_url: 'https://cdn.chordal.com/image.jpg'
                        created_at: '2025-03-21T12:00:00Z'
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        title:
                          type: string
                          example: 'Project Title'
                        slug:
                          type: string
                          example: project-title
                        short_title:
                          type: string
                          example: 'Short Title'
                        description:
                          type: string
                          example: 'A brief description of the project.'
                        preclearedProgram:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: 'Program Name'
                        tags:
                          type: array
                          example:
                            -
                              id: 1
                              name: 'Tag Name 1'
                          items:
                            type: object
                            properties:
                              id:
                                type: integer
                                example: 1
                              name:
                                type: string
                                example: 'Tag Name 1'
                        image_url:
                          type: string
                          example: 'https://cdn.chordal.com/image.jpg'
                        created_at:
                          type: string
                          example: '2025-03-21T12:00:00Z'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: 'https://api.chordal.com/v1/licensing/projects?page=1'
                      last:
                        type: string
                        example: 'https://api.chordal.com/v1/licensing/projects?page=10'
                      prev:
                        type: string
                        example: null
                      next:
                        type: string
                        example: 'https://api.chordal.com/v1/licensing/projects?page=2'
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 10
                      path:
                        type: string
                        example: 'https://api.chordal.com/v1/licensing/projects'
                      per_page:
                        type: integer
                        example: 15
                      to:
                        type: integer
                        example: 15
                      total:
                        type: integer
                        example: 150
      tags:
        - Projects
    post:
      summary: 'POST v1/licensing/projects'
      operationId: pOSTV1licensingprojects
      description: ''
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: 1
                    title: 'Project Title'
                    slug: project-title
                    short_title: 'Short Title'
                    description: 'A brief description of the project.'
                    preclearedProgram:
                      id: 1
                      name: 'Program Name'
                    tags:
                      -
                        id: 1
                        name: 'Tag Name 1'
                    image_url: 'https://cdn.chordal.com/image.jpg'
                    created_at: '2025-03-21T12:00:00Z'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 1
                      title:
                        type: string
                        example: 'Project Title'
                      slug:
                        type: string
                        example: project-title
                      short_title:
                        type: string
                        example: 'Short Title'
                      description:
                        type: string
                        example: 'A brief description of the project.'
                      preclearedProgram:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 1
                          name:
                            type: string
                            example: 'Program Name'
                      tags:
                        type: array
                        example:
                          -
                            id: 1
                            name: 'Tag Name 1'
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: 'Tag Name 1'
                      image_url:
                        type: string
                        example: 'https://cdn.chordal.com/image.jpg'
                      created_at:
                        type: string
                        example: '2025-03-21T12:00:00Z'
      tags:
        - Projects
      requestBody:
        required: false
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                title:
                  type: required
                  description: 'string The title of the project to search.'
                  example: Euphoria
                  nullable: false
                description:
                  type: string
                  description: 'The description of the project.'
                  example: 'A brief description of the project.'
                  nullable: false
                short_title:
                  type: string
                  description: 'The short title of the project.'
                  example: Euphoria
                  nullable: false
                precleared_program_id:
                  type: integer
                  description: 'The ID of the pre-cleared program.'
                  example: 1
                  nullable: false
                image:
                  type: string
                  format: binary
                  description: 'The image of the project.'
                  nullable: false
                image_url:
                  type: string
                  description: 'The image URL of the project.'
                  example: 'https://cdn.chordal.com/image.jpg'
                  nullable: false
                tags:
                  type: array
                  description: 'The tags of the project.'
                  example:
                    - tag1
                    - tag2
                  items:
                    type: string
  '/v1/licensing/projects/{project_id}':
    delete:
      summary: 'DELETE v1/licensing/projects/{id}'
      operationId: dELETEV1licensingprojectsid
      description: ''
      parameters: []
      responses:
        204:
          description: ''
      tags:
        - Projects
    parameters:
      -
        in: path
        name: project_id
        description: 'The ID of the project.'
        example: 6
        required: true
        schema:
          type: integer
      -
        in: path
        name: id
        description: 'Project id.'
        example: quis
        required: true
        schema:
          type: string
  '/v1/licensing/projects/{project_id}/tracks':
    get:
      summary: 'GET v1/licensing/projects/{project_id}/tracks'
      operationId: gETV1licensingprojectsprojectIdtracks
      description: ''
      parameters:
        -
          in: query
          name: title
          description: 'The title of the track to search.'
          example: Imagine
          required: false
          schema:
            type: string
            description: 'The title of the track to search.'
            example: Imagine
            nullable: false
        -
          in: query
          name: isrc
          description: 'The ISRC code of the track.'
          example: USRC17607839
          required: false
          schema:
            type: string
            description: 'The ISRC code of the track.'
            example: USRC17607839
            nullable: false
        -
          in: query
          name: iswc
          description: 'The ISWC code of the track.'
          example: T-123.456.789-0
          required: false
          schema:
            type: string
            description: 'The ISWC code of the track.'
            example: T-123.456.789-0
            nullable: false
        -
          in: query
          name: order_by
          description: 'The field by which to order results. Supported values: `id`, `title`, `album.title`, `artist.name`. Default: `id`.'
          example: title
          required: false
          schema:
            type: string
            description: 'The field by which to order results. Supported values: `id`, `title`, `album.title`, `artist.name`. Default: `id`.'
            example: title
            nullable: false
        -
          in: query
          name: sort_type
          description: 'The sorting direction. Supported values: `asc`, `desc`. Default: `asc`.'
          example: asc
          required: false
          schema:
            type: string
            description: 'The sorting direction. Supported values: `asc`, `desc`. Default: `asc`.'
            example: asc
            nullable: false
        -
          in: query
          name: page
          description: 'The page number for pagination. Default: 1.'
          example: 2
          required: false
          schema:
            type: integer
            description: 'The page number for pagination. Default: 1.'
            example: 2
            nullable: false
        -
          in: query
          name: per_page
          description: 'Number of results per page. Default: 15.'
          example: 20
          required: false
          schema:
            type: integer
            description: 'Number of results per page. Default: 15.'
            example: 20
            nullable: false
      responses:
        200:
          description: ''
          content:
            text/plain:
              schema:
                type: string
                example: "{\n  \"data\": [\n    {\n      \"id\": 1,\n      \"isrc\": \"USRC17607839\",\n      \"iswc\": \"T-123.456.789-0\",\n      \"title\": \"Track Title\",\n      \"year\": 2020,\n      \"release_date\": \"2020-05-20\",\n      \"language_code\": \"en\",\n      \"version_type\": \"original\" | \"cover\" | \"remix\",\n      \"mix_type\": \"mixed\" | \"instrumental\" | \"acapella\" | \"clean\" | \"radio\",\n      \"structure\": \"has-build\" | \"consistent\",\n      \"key\": \"C major\" | \"C minor\",\n      \"tempo\": 120,\n      \"energy_level\": \"high\" | \"medium\" | \"low\" | \"variable\",\n      \"emotional_tone\": \"bright-uplifting\" | \"bright-focused\" | \"bright-emotional\" | \"dark-emotional\" | \"dark-focused\" | \"dark-disturbing\",\n      \"recognizability\": 0-1000,\n      \"artists\": [\n        {\n          \"id\": 1,\n          \"name\": \"Artist One\"\n        }\n      ],\n      \"albums\": [\n        {\n          \"id\": 1,\n          \"title\": \"Album One\"\n        }\n      ],\n      \"genres\": [\n        {\n          \"id\": 1,\n          \"name\": \"Pop\"\n        }\n      ],\n      \"subgenres\": [\n        {\n          \"id\": 1,\n          \"name\": \"Indie Pop\"\n        }\n      ],\n      \"moods\": [\n        {\n          \"id\": 1,\n          \"name\": \"Happy\"\n        }\n      ],\n      \"instruments\": [\n        {\n          \"id\": 1,\n          \"name\": \"Guitar\"\n        }\n      ],\n      \"creativeKeywords\": [\n        {\n          \"id\": 1,\n          \"name\": \"Uplifting\"\n        }\n      ],\n      \"lyricMoods\": [\n        {\n          \"id\": 1,\n          \"name\": \"Sad\"\n        }\n      ],\n      \"lyricThemes\": [\n        {\n          \"id\": 1,\n          \"name\": \"Ambition\"\n        }\n      ],\n      \"lyrics_summary\": \"A summary of the lyrics\",\n      \"image_url\": \"https://cdn.chordal.com/image.jpg\",\n      \"audio_url\": \"https://cdn.chordal.com/audio.mp3\",\n      \"duration\": 180,\n      \"stems\": [\n        {\n          \"id\": 101,\n          \"title\": \"Guitar Stem\",\n          \"instrument\": \"Guitar\",\n          \"audio_url\": \"https://cdn.chordal.com/stems/guitar.mp3\",\n          \"duration\": 180\n        },\n      ]\n    }\n    }\n  ],\n  \"links\": {\n    \"first\": \"https://api.chordal.com/v1/licensing/projects/1/tracks?page=1\",\n    \"last\": \"https://api.chordal.com/v1/licensing/projects/1/tracks?page=5\",\n    \"prev\": null,\n    \"next\": \"https://api.chordal.com/v1/licensing/projects/1/tracks?page=2\"\n  },\n  \"meta\": {\n    \"current_page\": 1,\n    \"from\": 1,\n    \"last_page\": 5,\n    \"path\": \"https://api.chordal.com/v1/licensing/projects/1/tracks\",\n    \"per_page\": 15,\n    \"to\": 15,\n    \"total\": 75\n  }\n}"
      tags:
        - Tracks
    parameters:
      -
        in: path
        name: project_id
        description: 'The project ID.'
        example: 1
        required: true
        schema:
          type: integer
  '/v1/licensing/projects/{project_id}/{model_type}/{model_id}/download':
    get:
      summary: 'GET v1/licensing/projects/{project_id}/{model_type}/{model_id}/download'
      operationId: gETV1licensingprojectsprojectIdmodelTypemodelIddownload
      description: ''
      parameters:
        -
          in: query
          name: track_quality
          description: 'Type of the audio to download (hi-res or mp3).'
          example: hi-res
          required: true
          schema:
            type: string
            description: 'Type of the audio to download (hi-res or mp3).'
            example: hi-res
            nullable: false
      responses:
        200:
          description: 'The file'
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
      tags:
        - Tracks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                track_quality:
                  type: string
                  description: ''
                  example: hi-res
                  nullable: false
                  enum:
                    - hi-res
                    - mp3
              required:
                - track_quality
    parameters:
      -
        in: path
        name: project_id
        description: 'The project ID.'
        example: 1
        required: true
        schema:
          type: integer
      -
        in: path
        name: model_type
        description: 'tracks or stems.'
        example: tracks
        required: true
        schema:
          type: string
      -
        in: path
        name: model_id
        description: 'Track or Toolkit id to download.'
        example: 10
        required: true
        schema:
          type: integer
tags:
  -
    name: 'InstantClear Templates'
    description: 'List all of the InstantClear templates associated to my company’s account.'
  -
    name: Licenses
    description: 'Deliver license confirmations back to Chordal. If your InstantClear program is using the FLAT rate type, this will be delivering individual usage confirmations at the per-license rate specified in precleared_program_per_use_fee_id. If your InstantClear program is using the METERED rate type, this will be delivering usage confirmations based on a variable rate determined in each accounting period, or the: total_reported_royalties. The rate type for your InstantClear program is configured by a Chordal account manager before integrating with the Licensing API.'
  -
    name: Projects
    description: 'List all of the projects currently associated to an InstantClear template inside my company’s account.'
  -
    name: Tracks
    description: 'List all the tracks associated to a project.'
components:
  securitySchemes:
    default:
      type: http
      scheme: bearer
      description: 'Clients are provided with signed [JSON Web Tokens](https://jwt.io/introduction/) that the platform verify for every request that a client makes.'
security:
  -
    default: []
