profilarr/docs/api/v1/paths/arr.yaml

instances:
  get:
    operationId: listArrInstances
    summary: List Arr Instances
    description: |
      Returns all Arr instances (Radarr/Sonarr) with secrets stripped.

      **Use cases:**
      - Dashboard widgets showing connected instances
      - Automation scripts checking instance state
      - Prerequisite checks (e.g. onboarding)

      **Behavior:**
      - Returns an empty array if no instances are connected
      - The `api_key` field is never included
    tags:
      - Arr
    responses:
      '200':
        description: List of Arr instances
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '../schemas/arr.yaml#/ArrInstance'
      '401':
        description: Not authenticated

library:
  get:
    operationId: getLibrary
    summary: Get Arr instance library
    description: |
      Fetches the full movie or series library from an Arr instance with quality profile,
      score, and progress information.

      - For Radarr: Returns movies with file quality, custom format scores, and cutoff progress
      - For Sonarr: Returns series with season summaries and episode statistics

      Results include Profilarr profile matching to indicate which items use managed profiles.
      Responses are cached server-side for 5 minutes.
    tags:
      - Arr
    parameters:
      - name: instanceId
        in: query
        required: true
        schema:
          type: integer
        description: Arr instance ID
    responses:
      '200':
        description: Library items with quality and score data
        content:
          application/json:
            schema:
              $ref: '../schemas/arr.yaml#/LibraryResponse'
      '400':
        description: Invalid or missing instanceId
        content:
          application/json:
            schema:
              $ref: '../schemas/arr.yaml#/ErrorResponse'
      '404':
        description: Instance not found
        content:
          application/json:
            schema:
              $ref: '../schemas/arr.yaml#/ErrorResponse'
      '500':
        description: Failed to fetch library
        content:
          application/json:
            schema:
              $ref: '../schemas/arr.yaml#/ErrorResponse'
  delete:
    operationId: invalidateLibraryCache
    summary: Invalidate library cache
    description: |
      Clears the server-side cache for an Arr instance's library data.
      The next GET request will fetch fresh data from the Arr instance.
    tags:
      - Arr
    parameters:
      - name: instanceId
        in: query
        required: true
        schema:
          type: integer
        description: Arr instance ID
    responses:
      '200':
        description: Cache invalidated
        content:
          application/json:
            schema:
              $ref: '../schemas/arr.yaml#/CacheInvalidatedResponse'
      '400':
        description: Invalid or missing instanceId
        content:
          application/json:
            schema:
              $ref: '../schemas/arr.yaml#/ErrorResponse'

episodes:
  get:
    operationId: getLibraryEpisodes
    summary: Get episode details for a Sonarr series
    description: |
      Lazy-loads episode-level data for a specific series in a Sonarr instance.
      Returns episodes with quality, custom format scores, and cutoff progress.

      This endpoint is designed for on-demand loading when a series row is expanded
      in the library view. Sonarr instances only.

      Results are cached server-side for 5 minutes per series.
    tags:
      - Arr
    parameters:
      - name: instanceId
        in: query
        required: true
        schema:
          type: integer
        description: Arr instance ID (must be a Sonarr instance)
      - name: seriesId
        in: query
        required: true
        schema:
          type: integer
        description: Sonarr series ID
    responses:
      '200':
        description: Episode details with quality and score data
        content:
          application/json:
            schema:
              $ref: '../schemas/arr.yaml#/EpisodesResponse'
      '400':
        description: Invalid parameters or not a Sonarr instance
        content:
          application/json:
            schema:
              $ref: '../schemas/arr.yaml#/ErrorResponse'
      '404':
        description: Instance not found
        content:
          application/json:
            schema:
              $ref: '../schemas/arr.yaml#/ErrorResponse'
      '500':
        description: Failed to fetch episode details
        content:
          application/json:
            schema:
              $ref: '../schemas/arr.yaml#/ErrorResponse'

releases:
  get:
    operationId: getReleases
    summary: Search for releases
    description: |
      Triggers an interactive search on an Arr instance and returns grouped/deduplicated results.

      For Radarr: Searches for releases for the specified movie.
      For Sonarr: Searches for season pack releases for the specified series and season.

      Results are grouped by title, combining information from multiple indexers.
    tags:
      - Arr
    parameters:
      - name: instanceId
        in: query
        required: true
        schema:
          type: integer
        description: Arr instance ID
      - name: itemId
        in: query
        required: true
        schema:
          type: integer
        description: Movie ID (Radarr) or Series ID (Sonarr)
      - name: season
        in: query
        required: false
        schema:
          type: integer
          default: 1
        description: Season number for Sonarr searches (defaults to 1)
    responses:
      '200':
        description: Release search results
        content:
          application/json:
            schema:
              $ref: '../schemas/arr.yaml#/ReleasesResponse'
      '400':
        description: Invalid or missing parameters
        content:
          application/json:
            schema:
              $ref: '../schemas/arr.yaml#/ErrorResponse'
      '404':
        description: Instance not found
        content:
          application/json:
            schema:
              $ref: '../schemas/arr.yaml#/ErrorResponse'
      '500':
        description: Failed to fetch releases
        content:
          application/json:
            schema:
              $ref: '../schemas/arr.yaml#/ErrorResponse'

sync-entity:
  post:
    operationId: syncEntity
    summary: Sync a single entity to an Arr instance
    description: |
      Pushes a single entity to an Arr instance. Runs inline and returns when complete.

      Entity types are grouped into sync sections that share cooldown and status tracking:
        - **qualityProfiles**: qualityProfile, customFormat, regularExpression
        - **delayProfiles**: delayProfile
        - **mediaManagement**: naming, qualityDefinitions, mediaSettings

      The section is derived automatically from the entity type. A 5-second cooldown
      is enforced per section per instance — entity types within the same section share
      the cooldown. Returns 409 if a sync is already in progress or the cooldown is active.
    tags:
      - Arr
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '../schemas/arr.yaml#/SyncEntityRequest'
    responses:
      '200':
        description: Entity synced successfully
        content:
          application/json:
            schema:
              $ref: '../schemas/arr.yaml#/SyncEntitySuccessResponse'
      '400':
        description: Invalid request parameters
        content:
          application/json:
            schema:
              $ref: '../schemas/arr.yaml#/ErrorResponse'
      '404':
        description: Instance not found
        content:
          application/json:
            schema:
              $ref: '../schemas/arr.yaml#/ErrorResponse'
      '409':
        description: Cooldown active or sync in progress
        content:
          application/json:
            schema:
              $ref: '../schemas/arr.yaml#/SyncEntityCooldownResponse'
      '500':
        description: Sync failed
        content:
          application/json:
            schema:
              $ref: '../schemas/arr.yaml#/ErrorResponse'