openapi: 3.0.0
info:
  title: Overview
  version: ''
  description: >
    The **Status Service** provides progress tracking for asynchronous requests.
    This functionality is supported exclusively for **V2 endpoints**.


    ### Workflow

    1. Submit a request with `sync=false` (default behavior).

    2. The API returns a `status_url` and a `request_id`.

    3. Continuously poll the `status_url` (or use the `/status/{request_id}`
    endpoint) until the `status` field indicates a terminal state.


    ### Status Values

    - **`IN_PROGRESS`** – The request has been accepted and is currently being
    processed.  
      Continue polling until the status changes to either `COMPLETED` or an error state.

    - **`COMPLETED`** – The request was successfully processed.  
      The response includes the `result.image_url` containing the generated image.  
      For some endpoints, additional optional fields (`seed`, `prompt`, `refined_prompt`) may be included.

    - **`ERROR`** – A processing error occurred in the pipeline.  
      The response includes an `error` object with details about the failure. Polling should be stopped.

    - **`UNKNOWN`** – An unexpected internal error occurred (equivalent to an
    HTTP `500` in asynchronous workflows).  
      This status should not occur under normal circumstances. If it does, contact [Support](mailto:support@bria.ai). and provide the `request_id`.
tags:
  - name: Endpoints
externalDocs:
  description: Register and get API Access
  url: https://platform.bria.ai/console/account/api-keys
servers:
  - url: https://engine.prod.bria-api.com/v2
paths:
  /status/{request_id}:
    get:
      tags:
        - Endpoints
      servers:
        - url: https://engine.prod.bria-api.com/v2
      summary: Get Request Status
      description: >
        Retrieves the current status of an asynchronous request.

          **Behavior**
        - Under normal operation, this endpoint returns **`200 OK`**, regardless
        of whether the request is in progress, completed, or has failed at the
        job level.  

        - The `status` field in the response (`IN_PROGRESS`, `COMPLETED`,
        `ERROR`, `UNKNOWN`) indicates the state of the job.  

        - When the job fails (status=`ERROR`), details of the failure are
        provided in the `error` object, but the HTTP status remains `200`.


        **Other Possible Responses**

        - **`404 NOT_FOUND`** – Returned when the specified `request_id` does
        not exist or has expired.  

        - **`5XX`** – Returned when the Status Service itself experiences an
        internal error.
          For real-time updates, check [Bria's Status Page](https://status.bria.ai). You can also contact our [Support](mailto:support@bria.ai).

        - When `status=COMPLETED`, `result` may also include:
          - `seed` – Deterministic seed used for generation (if supported by the endpoint).
          - `prompt` – Original prompt provided by the user (if applicable).
          - `refined_prompt` – System-enhanced version of the input prompt (if applicable).
      operationId: get_status
      parameters:
        - name: request_id
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the request.
      responses:
        '200':
          description: >-
            The `status` field indicates whether the request completed
            successfully or failed.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/StatusSuccessResponse'
                  - $ref: '#/components/schemas/StatusErrorResponse'
              examples:
                completed:
                  summary: Completed Request (minimal)
                  value:
                    status: COMPLETED
                    result:
                      image_url: https://example.com/generated_image.png
                    request_id: '123456'
                completed_with_seed:
                  summary: Completed Request (with seed)
                  value:
                    status: COMPLETED
                    result:
                      image_url: https://example.com/generated_image.png
                      seed: '42'
                    request_id: '123456'
                completed_with_prompt:
                  summary: Completed Request (with prompt)
                  value:
                    status: COMPLETED
                    result:
                      image_url: https://example.com/generated_image.png
                      seed: '42'
                      prompt: A fantasy landscape with mountains
                    request_id: '123456'
                completed_with_refined_prompt:
                  summary: Completed Request (with refined prompt)
                  value:
                    status: COMPLETED
                    result:
                      image_url: https://example.com/generated_image.png
                      seed: '42'
                      refined_prompt: High-detail fantasy landscape with dramatic mountains
                    request_id: '123456'
                error:
                  summary: Error Response
                  value:
                    status: ERROR
                    error:
                      code: 500
                      message: Internal Server Error
                      details: Unexpected error occurred.
                    request_id: '123456'
        '404':
          description: |
            The provided `request_id` does not exist or has expired.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - NOT_FOUND
                required:
                  - status
              examples:
                not_found_example:
                  summary: Request ID Not Found
                  value:
                    status: NOT_FOUND
        5XX:
          description: >
            **Internal Server Error** – A critical failure occurred in Bria's
            infrastructure, preventing the Status Service from responding.  

            - This response indicates a service outage or unexpected runtime
            failure.  

            - Check [Bria's Status Page](https://status.bria.ai) for real-time
            updates. 

            - Contact [Support](mailto:support@bria.ai).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal_error:
                  summary: Service Outage
                  value:
                    error:
                      code: 503
                      message: Service Unavailable
                      details: >-
                        Bria's Status Service is temporarily unavailable. Please
                        try again later.
components:
  schemas:
    ErrorObject:
      type: object
      properties:
        code:
          type: integer
          example: 123
        message:
          type: string
        details:
          type: string
      required:
        - code
        - message
        - details
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
        request_id:
          type: string
      required:
        - error
        - request_id
    StatusSuccessResponse:
      type: object
      properties:
        result:
          type: object
          properties:
            image_url:
              type: string
            seed:
              type: integer
              description: >-
                Deterministic generation seed (returned only for endpoints that
                support reproducible outputs).
            prompt:
              type: string
              description: Original prompt sent by the user (returned only if applicable).
            refined_prompt:
              type: string
              description: >-
                Refined version of the input prompt (returned only if applicable
                and supported by the endpoint).
          required:
            - image_url
        status:
          type: string
          enum:
            - COMPLETED
        request_id:
          type: string
      required:
        - result
        - status
        - request_id
    StatusErrorResponse:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          properties:
            status:
              type: string
              enum:
                - ERROR
                - UNKNOWN
          required:
            - status
