{
  "openapi": "3.1.0",
  "info": {
    "title": "MomentIQ API",
    "version": "2026-06-09-beta",
    "summary": "AI-ready video and audio APIs for finding the moments that matter.",
    "description": "Starter OpenAPI spec for live-safe MomentIQ beta flows. Use this with AI agents, SDK generators, Replit, Lovable, Cursor, or backend app builders. Long-running media processing is job-based: upload or provide a media_url, create a job, then poll until completed or failed."
  },
  "servers": [
    {
      "url": "https://api.momentiq.dev",
      "description": "Canonical API domain"
    },
    {
      "url": "https://momentiq-production-7fdd.up.railway.app",
      "description": "Railway fallback API domain"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Check API health",
        "security": [],
        "responses": {
          "200": {
            "description": "API health payload",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/catalog": {
      "get": {
        "operationId": "listCatalog",
        "summary": "List endpoint catalog and pricing",
        "description": "Public endpoint catalog. Use this to discover current endpoint ids, groups, pricing units, and beta prices.",
        "security": [],
        "responses": {
          "200": {
            "description": "Endpoint catalog",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/v1/uploads/presign": {
      "post": {
        "operationId": "createUpload",
        "summary": "Create a signed direct-upload URL",
        "description": "Create a short-lived signed PUT URL for local media. Upload the file to upload.upload_url, then pass upload.media_url to /v1/jobs.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateUploadRequest"
              },
              "examples": {
                "video": {
                  "value": {
                    "filename": "podcast.webm",
                    "bytes": 10485760,
                    "content_type": "video/webm"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Signed upload instructions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateUploadResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "413": {
            "$ref": "#/components/responses/Error"
          },
          "415": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/jobs": {
      "post": {
        "operationId": "createJob",
        "summary": "Create a media processing job",
        "description": "Create a worker-backed job. Safe beta endpoints are video/clip-window, video/clip-near, audio/detect-silence, and audio/detect-energy.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateJobRequest"
              },
              "examples": {
                "detectEnergy": {
                  "value": {
                    "endpoint": "audio/detect-energy",
                    "media_url": "https://example.com/video.mp4",
                    "settings": {
                      "threshold": 0.75,
                      "quiet_threshold": 0.12
                    }
                  }
                },
                "clipWindow": {
                  "value": {
                    "endpoint": "video/clip-window",
                    "media_url": "https://example.com/video.mp4",
                    "start": 60,
                    "end": 120,
                    "settings": {
                      "format": "mp4"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Created or completed job response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobEnvelope"
                }
              }
            }
          },
          "202": {
            "description": "Queued job response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobEnvelope"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "402": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/jobs/{job_id}": {
      "get": {
        "operationId": "getJob",
        "summary": "Poll job status and result",
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^job_[a-zA-Z0-9]+$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current job status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobEnvelope"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "operationId": "callMcp",
        "summary": "Call the remote MomentIQ MCP server",
        "description": "JSON-RPC MCP endpoint for tool-capable agents. Most paid tools require the same Bearer API key as the HTTP API.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "MomentIQ API key"
      }
    },
    "schemas": {
      "HealthResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "storage": {
            "type": "object",
            "additionalProperties": true
          },
          "jobs": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "required": ["ok"]
      },
      "CreateUploadRequest": {
        "type": "object",
        "properties": {
          "filename": {
            "type": "string",
            "description": "Original filename. Supported extensions include mp4, mov, webm, m4v, mp3, wav, m4a, aac, and ogg."
          },
          "bytes": {
            "type": "integer",
            "minimum": 0,
            "description": "Optional file size in bytes."
          },
          "content_type": {
            "type": "string",
            "description": "Optional MIME type. If omitted, MomentIQ infers it from the extension."
          }
        },
        "required": ["filename"]
      },
      "CreateUploadResponse": {
        "type": "object",
        "properties": {
          "request_id": {
            "type": "string"
          },
          "upload": {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "upload_url": { "type": "string", "format": "uri" },
              "upload_method": { "type": "string", "const": "PUT" },
              "upload_headers": {
                "type": "object",
                "additionalProperties": { "type": "string" }
              },
              "media_url": { "type": "string", "format": "uri" },
              "content_type": { "type": "string" },
              "expires_in_seconds": { "type": "integer" }
            },
            "required": ["id", "upload_url", "upload_method", "upload_headers", "media_url"]
          }
        },
        "required": ["request_id", "upload"]
      },
      "CreateJobRequest": {
        "type": "object",
        "properties": {
          "endpoint": {
            "type": "string",
            "enum": [
              "video/clip-window",
              "video/clip-near",
              "audio/detect-silence",
              "audio/detect-energy"
            ]
          },
          "media_url": {
            "type": "string",
            "format": "uri",
            "description": "Public or signed source media URL. For local files, call /v1/uploads/presign first."
          },
          "start": {
            "type": ["number", "string"],
            "description": "Optional start timestamp. Numbers are seconds; strings may be HH:MM:SS."
          },
          "end": {
            "type": ["number", "string"],
            "description": "Optional end timestamp. Blank or omitted means end of media when the endpoint supports it."
          },
          "settings": {
            "type": "object",
            "additionalProperties": true,
            "description": "Endpoint-specific settings."
          }
        },
        "required": ["endpoint"]
      },
      "JobEnvelope": {
        "type": "object",
        "properties": {
          "request_id": { "type": "string" },
          "job_id": { "type": "string" },
          "job": {
            "$ref": "#/components/schemas/Job"
          }
        },
        "required": ["request_id"]
      },
      "Job": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "endpoint": { "type": "string" },
          "status": {
            "type": "string",
            "enum": ["queued", "running", "completed", "succeeded", "failed"]
          },
          "media_seconds": { "type": "number" },
          "estimated_price_usd": { "type": "number" },
          "final_price_usd": { "type": "number" },
          "result": {
            "type": "object",
            "additionalProperties": true
          },
          "error": {
            "$ref": "#/components/schemas/ErrorBody"
          }
        },
        "required": ["id", "endpoint", "status"]
      },
      "ErrorBody": {
        "type": "object",
        "properties": {
          "code": { "type": "string" },
          "message": { "type": "string" },
          "request_id": { "type": "string" },
          "docs_url": { "type": "string", "format": "uri" }
        },
        "required": ["code", "message", "request_id"]
      },
      "ErrorEnvelope": {
        "type": "object",
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ErrorBody"
          }
        },
        "required": ["error"]
      }
    },
    "responses": {
      "Error": {
        "description": "Standard MomentIQ error envelope",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      }
    }
  },
  "externalDocs": {
    "description": "MomentIQ setup hub",
    "url": "https://momentiq.dev/docs-setup.html"
  }
}