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

# Refresh cached response

> Unified endpoint to refresh a response by its identifier, invalidating the cached entry so that the next media request triggers a fresh scrape.




## OpenAPI

````yaml https://raw.githubusercontent.com/omss-spec/omss-spec/refs/heads/main/spec/v1.1/omss-v1.1.yml post /v1/refresh/{id}
openapi: 3.1.0
info:
  title: Open Media Streaming Specification (OMSS)
  description: >
    OMSS (Open Media Streaming Specification) v1.1 defines a unified REST API

    standard for streaming media backends. It enables any frontend application

    to work with any OMSS-compliant backend through standardized endpoints for

    retrieving streaming sources and subtitles for TMDB media identifiers.


    **Key Features:**

    - Standardized endpoints for movies and TV episodes

    - Multi-language and multi-quality source support

    - Subtitle support with multiple formats

    - Diagnostic reporting for partial scrapes


    **OMSS Framework:**
    [github.com/omss-spec/framework](https://github.com/omss-spec/framework)


    **OMSS Template:**
    [github.com/omss-spec/template](https://github.com/omss-spec/template)


    **OMSS SDK:** [github.com/omss-spec/sdk](https://github.com/omss-spec/sdk)
  version: 1.1.0
  license:
    name: MIT License
    url: https://github.com/omss-spec/omss-spec/blob/main/LICENSE
  contact:
    name: OMSS Community
    url: https://github.com/omss-spec/omss-spec
servers:
  - url: http://localhost:{port}
    description: Development server (localhost only)
    variables:
      port:
        default: '3000'
        description: Port
  - url: https://{domain}
    description: Production server
    variables:
      domain:
        default: api.example.com
        description: Your hosted OMSS server
security: []
tags:
  - name: Home
    description: General backend information and capabilities
  - name: Movies
    description: Movie streaming sources
  - name: TV
    description: TV episode streaming sources
  - name: Refresh
    description: Refresh cached source responses
paths:
  /v1/refresh/{id}:
    post:
      tags:
        - Refresh
      summary: Refresh cached response
      description: >
        Unified endpoint to refresh a response by its identifier, invalidating
        the cached entry so that the next media request triggers a fresh scrape.
      operationId: refreshResponse
      parameters:
        - $ref: '#/components/parameters/ResponseId'
      responses:
        '200':
          description: Refresh request accepted and cache invalidated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefreshResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    ResponseId:
      name: id
      in: path
      required: true
      description: >
        Response identifier used by the refresh endpoint. Alphanumeric with
        hyphens/underscores, max 128 characters.
      schema:
        type: string
        pattern: ^[A-Za-z0-9_-]{1,128}$
        maxLength: 128
  schemas:
    RefreshResponse:
      type: object
      description: Response object for the refresh endpoint.
      required:
        - status
      properties:
        status:
          type: string
          description: Refresh status string; MUST be "OK" on success.
          enum:
            - OK
    ErrorResponse:
      type: object
      description: Standard error response format for all non-2xx responses.
      required:
        - error
        - traceId
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
        traceId:
          type: string
          description: Unique identifier for error tracking and debugging.
    ErrorObject:
      type: object
      description: Error details container.
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Machine-readable error code.
          enum:
            - INVALID_TMDB_ID
            - INVALID_PARAMETER
            - MISSING_PARAMETER
            - INVALID_SEASON
            - INVALID_EPISODE
            - INVALID_RESPONSE_ID
            - PROVIDER_NOT_FOUND
            - RESPONSE_ID_NOT_FOUND
            - NO_SOURCES_AVAILABLE
            - ENDPOINT_NOT_FOUND
            - METHOD_NOT_ALLOWED
            - INTERNAL_ERROR
            - UNSUPPORTED_MEDIA_TYPE
            - NOT_ACCEPTABLE
        message:
          type: string
          description: Human-readable error description.
        details:
          description: >
            Optional additional context about the error. Frontends should not
            display this field directly.
  responses:
    BadRequest:
      description: >
        Bad request due to invalid or missing parameters, or invalid TMDB ID
        format.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: >
        Resource not found, including media that does not exist for the given
        TMDB ID or media that exists but has no available sources.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotAcceptable:
      description: >
        The requested Accept header is not supported. OMSS supports JSON
        responses only.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnsupportedMediaType:
      description: Unsupported Content-Type in the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

````