{
  "openapi": "3.0.3",
  "info": {
    "title": "QwikVid Order & Media Read API",
    "version": "2026-10-25",
    "description": "The documented existing order-read operations. Authentication uses the required key form field, not Bearer headers. Coordinate credentials, test access and request cadence with QwikVid. Does not describe a self-service booking or webhook API.",
    "contact": {
      "name": "QwikVid integration support",
      "email": "support@qwikvid.com",
      "url": "https://www.qwikvid.com/developer/"
    }
  },
  "servers": [
    {
      "url": "https://www.qwikvid.com",
      "description": "Production. Arrange separate test access with the team."
    }
  ],
  "paths": {
    "/api/v2/utilities/order/list/": {
      "post": {
        "operationId": "listOrders",
        "summary": "List orders visible to the API user",
        "description": "Requires action=getOrders. Returns an error/data envelope. No documented page or cursor parameter. Some text fields are HTML-encoded.",
        "parameters": [
          {
            "name": "view_range",
            "in": "query",
            "required": false,
            "description": "Appointment-date filter, not an updated-since cursor. Omit for all dates.",
            "schema": {
              "type": "string",
              "enum": [
                "30days",
                "60days",
                "6months",
                "12months",
                "24months"
              ]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "key",
                  "action"
                ],
                "properties": {
                  "key": {
                    "type": "string",
                    "format": "password",
                    "writeOnly": true,
                    "description": "Approved QwikVid API key. Keep it on your server. A test-named key does not select a separate environment."
                  },
                  "action": {
                    "type": "string",
                    "enum": [
                      "getOrders"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Order list; empty array is valid.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "data"
                  ],
                  "properties": {
                    "error": {
                      "nullable": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "order_no": {
                            "type": "integer"
                          },
                          "ticket_id": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string"
                          },
                          "project_title": {
                            "type": "string"
                          },
                          "event_date": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          },
                          "approximate_eta": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          }
                        },
                        "additionalProperties": true
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid action.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "401": {
            "description": "Authentication or account access denied.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/utilities/order/detail/": {
      "post": {
        "operationId": "getOrderDetails",
        "summary": "Read order details and available media",
        "description": "Success is a root object. Historical errors can return HTTP 200 with an error envelope; inspect JSON. Enforce can_download_deliverables before presenting downloads. Fields described here are a subset; additional fields may be returned.",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "key",
                  "ticket_id"
                ],
                "properties": {
                  "key": {
                    "type": "string",
                    "format": "password",
                    "writeOnly": true,
                    "description": "Approved QwikVid API key. Keep it on your server. A test-named key does not select a separate environment."
                  },
                  "ticket_id": {
                    "type": "string",
                    "description": "Ticket ID from listOrders, not the numeric order number."
                  },
                  "include_photos": {
                    "type": "string",
                    "enum": [
                      "true",
                      "false",
                      "1",
                      "0"
                    ],
                    "default": "true",
                    "description": "false or 0 omits individual photo records."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Order details OR an error envelope. HTTP 200 alone does not establish success.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/OrderDetails"
                    },
                    {
                      "$ref": "#/components/schemas/ErrorEnvelope"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorEnvelope": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string"
              },
              "exception": {
                "nullable": true
              }
            }
          },
          "data": {
            "nullable": true
          }
        }
      },
      "OrderDetails": {
        "type": "object",
        "required": [
          "order_no",
          "ticket_id"
        ],
        "properties": {
          "order_no": {
            "type": "integer"
          },
          "ticket_id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "can_download_deliverables": {
            "type": "boolean"
          },
          "download_deliverables_available": {
            "type": "boolean"
          },
          "standard_photos_url": {
            "type": "string",
            "description": "May be empty."
          },
          "hi_res_photos_url": {
            "type": "string",
            "description": "May be empty."
          },
          "video_url": {
            "type": "string"
          },
          "mls_video_url": {
            "type": "string"
          },
          "matterport_url": {
            "type": "string"
          },
          "schematic_floor_plan_url": {
            "type": "string"
          },
          "photo_package_progress": {
            "type": "object",
            "properties": {
              "standard": {
                "type": "object",
                "properties": {
                  "ready": {
                    "type": "boolean"
                  },
                  "job_status": {
                    "type": "string"
                  }
                }
              },
              "high_resolution": {
                "type": "object",
                "properties": {
                  "entitled": {
                    "type": "boolean"
                  },
                  "ready": {
                    "type": "boolean"
                  },
                  "job_status": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "additionalProperties": true
      }
    }
  }
}