{
  "openapi": "3.1.0",
  "info": {
    "title": "seminara.online OpenAPI 3.1 Specification & REST API Reference",
    "version": "1.2.0",
    "description": "Official OpenAPI 3.1 specification for seminara.online developer resources, AI agents, session creation, slide generation, and lead export.",
    "x-category": "AI Presentation Platform & Developer Tools",
    "x-product-category": "Autonomous AI Agents"
  },
  "servers": [
    {
      "url": "https://seminara.online",
      "description": "Production server"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Host Bearer API Key. Format: Bearer sk_live_..."
      },
      "OAuth2": {
        "type": "oauth2",
        "description": "OAuth 2.0 Device Authorization Flow for autonomous agents and CLI clients.",
        "flows": {
          "device": {
            "deviceAuthorizationUrl": "https://seminara.online/api/v1/oauth/device/code",
            "tokenUrl": "https://seminara.online/api/v1/oauth/device/token",
            "scopes": {
              "sessions:read": "Read presentation sessions and slide contents",
              "sessions:write": "Create and modify interactive presentation sessions",
              "analytics:read": "Read attendee engagement metrics and analytics",
              "leads:read": "Export attendee contact details and intent signals",
              "checkout:write": "Initiate autonomous subscription upgrades and credit purchases"
            }
          }
        }
      }
    },
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "schema": { "type": "string" },
        "description": "Unique key to ensure idempotent request execution against network retries."
      }
    },
    "headers": {
      "RateLimit-Limit": {
        "description": "The maximum number of requests allowed in the current time window.",
        "schema": { "type": "integer", "example": 100 }
      },
      "RateLimit-Remaining": {
        "description": "The number of remaining requests allowed in the current time window.",
        "schema": { "type": "integer", "example": 99 }
      },
      "RateLimit-Reset": {
        "description": "The number of seconds remaining until the rate limit window resets.",
        "schema": { "type": "integer", "example": 60 }
      },
      "Retry-After": {
        "description": "The number of seconds to wait before retrying after a 429 rate limit breach.",
        "schema": { "type": "integer", "example": 60 }
      },
      "Location": {
        "description": "URL to poll for asynchronous job results.",
        "schema": { "type": "string", "format": "uri" }
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message", "status", "resolution"],
            "properties": {
              "code": {
                "type": "string",
                "example": "UNAUTHORIZED",
                "description": "Machine-readable error code."
              },
              "message": {
                "type": "string",
                "example": "Unauthorized: Invalid or missing Bearer API key.",
                "description": "Human-readable description of what went wrong."
              },
              "status": {
                "type": "integer",
                "example": 401,
                "description": "HTTP status code."
              },
              "resolution": {
                "type": "string",
                "example": "Provide your API key in header 'Authorization: Bearer sk_live_...'. Generate key at https://seminara.online/dashboard/settings.",
                "description": "Actionable instructions for AI agents to self-heal and resolve the failure."
              }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/api/pricing": {
      "get": {
        "summary": "Retrieve Machine-Readable Subscription Pricing & Quotas",
        "operationId": "getPricing",
        "description": "Returns current subscription tiers (Free, Pro, Scale), monthly and annual pricing (10% discount), presentation quotas, minute pools, and overrun policies.",
        "responses": {
          "200": {
            "description": "Pricing information retrieved successfully",
            "headers": {
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "currency": { "type": "string", "example": "USD" },
                    "annual_discount_percentage": { "type": "number", "example": 10 },
                    "plans": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "tier": { "type": "string", "enum": ["free", "pro", "scale"] },
                          "name": { "type": "string" },
                          "pricing": {
                            "type": "object",
                            "properties": {
                              "monthly": { "type": "number" },
                              "annual_billed_monthly": { "type": "number" },
                              "annual_total": { "type": "number" }
                            }
                          },
                          "quotas": {
                            "type": "object",
                            "properties": {
                              "agents_limit": { "type": "integer" },
                              "max_session_duration_minutes": { "type": "integer" },
                              "minute_pool_limit": { "type": "integer" },
                              "storage_mb": { "type": "integer" }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests.",
            "headers": {
              "Retry-After": { "$ref": "#/components/headers/Retry-After" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/v1/agent/sessions": {
      "get": {
        "summary": "List Presentation Sessions",
        "operationId": "listSessions",
        "description": "Returns a paginated list of presentation sessions for the authenticated account with cursor pagination.",
        "security": [
          { "ApiKeyAuth": [] },
          { "OAuth2": ["sessions:read"] }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 20 },
            "description": "Number of sessions to return."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "Pagination cursor."
          }
        ],
        "responses": {
          "200": {
            "description": "List of sessions retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sessions": { "type": "array", "items": { "type": "object" } },
                    "next_cursor": { "type": "string", "nullable": true },
                    "has_more": { "type": "boolean" }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create Presentation Session",
        "operationId": "createSession",
        "description": "Generates a new interactive presentation session with custom slides, conversion CTA, and knowledge base context.",
        "security": [
          { "ApiKeyAuth": [] },
          { "OAuth2": ["sessions:write"] }
        ],
        "parameters": [
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["title"],
                "properties": {
                  "title": { "type": "string" },
                  "description": { "type": "string" },
                  "isLive": { "type": "boolean" },
                  "ctaText": { "type": "string" },
                  "ctaUrl": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sessionId": { "type": "string" },
                    "shareLink": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/v1/agent/sessions/batch": {
      "post": {
        "summary": "Batch Create Presentation Sessions",
        "operationId": "batchCreateSessions",
        "description": "Create multiple presentation sessions in bulk. Returns 201 for immediate creation or 202 Accepted with a Location header for asynchronous jobs.",
        "security": [
          { "ApiKeyAuth": [] },
          { "OAuth2": ["sessions:write"] }
        ],
        "parameters": [
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["sessions"],
                "properties": {
                  "sessions": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": ["title"],
                      "properties": {
                        "title": { "type": "string" },
                        "isLive": { "type": "boolean" }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Batch sessions created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string" },
                    "processed": { "type": "integer" },
                    "results": { "type": "array", "items": { "type": "object" } }
                  }
                }
              }
            }
          },
          "202": {
            "description": "Batch creation accepted for asynchronous processing.",
            "headers": {
              "Location": { "$ref": "#/components/headers/Location" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "job_id": { "type": "string" },
                    "status": { "type": "string", "example": "queued" },
                    "poll_url": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/jobs/{id}": {
      "get": {
        "summary": "Poll Asynchronous Job Status",
        "operationId": "getJobStatus",
        "description": "Poll the progress and result of a long-running asynchronous batch operation.",
        "security": [
          { "ApiKeyAuth": [] }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "The asynchronous job identifier."
          }
        ],
        "responses": {
          "200": {
            "description": "Job status retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "job_id": { "type": "string" },
                    "status": { "type": "string", "enum": ["queued", "processing", "completed", "failed"] },
                    "progress": { "type": "number" },
                    "result": { "type": "object" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/agent/checkout": {
      "post": {
        "summary": "Autonomous Agent Plan Upgrade & Refill",
        "operationId": "agentCheckout",
        "description": "Allows an AI agent to initiate a plan upgrade or credit refill.",
        "security": [
          { "ApiKeyAuth": [] },
          { "OAuth2": ["checkout:write"] }
        ],
        "parameters": [
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "planId": { "type": "string", "enum": ["pro", "scale"] }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Checkout session created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "checkout_id": { "type": "string" },
                    "payment_url": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}