{
  "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",
    "x-service-info": {
      "categories": [
        "AI Presentation Platform",
        "Autonomous Agents",
        "Developer Tools"
      ]
    }
  },
  "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."
              }
            }
          }
        }
      },
      "WebhookSubscription": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid", "description": "Unique subscription UUID" },
          "url": { "type": "string", "format": "uri", "description": "Destination HTTPS endpoint for event delivery" },
          "events": { 
            "type": "array", 
            "items": { "type": "string" },
            "description": "Subscribed event topics (session.completed, attendee.cta_clicked, lead.captured)" 
          },
          "is_active": { "type": "boolean", "description": "Whether webhook delivery is active" },
          "description": { "type": "string", "nullable": true, "description": "Optional human-readable label (e.g. HubSpot CRM Sync)" },
          "created_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time", "nullable": true }
        }
      },
      "WebhookSubscriptionWithSecret": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "url": { "type": "string", "format": "uri" },
          "secret": { 
            "type": "string", 
            "example": "whsec_...", 
            "description": "HMAC SHA-256 webhook signing secret for signature verification (returned only once at creation time)." 
          },
          "events": { "type": "array", "items": { "type": "string" } },
          "is_active": { "type": "boolean" },
          "description": { "type": "string", "nullable": true },
          "created_at": { "type": "string", "format": "date-time" }
        }
      }
    }
  },
  "paths": {
    "/api/v1/auth/register": {
      "post": {
        "summary": "Dynamic Agent & Key Self-Registration (RFC 7591)",
        "operationId": "registerAgent",
        "description": "Instant self-serve API key generation for autonomous AI coding agents. Issues an ephemeral Bearer token with session provisioning and analytics scopes without human intervention. Sensitive scopes such as leads:read and checkout:write require account claiming via claim_uri.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "client_name": { "type": "string", "example": "Autonomous Agent" }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Agent successfully registered with issued Bearer access token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "registered" },
                    "client_name": { "type": "string", "example": "Autonomous Agent" },
                    "token_type": { "type": "string", "example": "Bearer" },
                    "access_token": { "type": "string", "example": "ag_live_086ca81a41394c1b..." },
                    "expires_in": { "type": "integer", "example": 86400 },
                    "scope": { "type": "string", "example": "sessions:read sessions:write analytics:read" },
                    "claim_uri": { "type": "string", "example": "https://seminara.online/api/v1/auth/claim" },
                    "revocation_uri": { "type": "string", "example": "https://seminara.online/api/v1/auth/revoke" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/sandbox": {
      "get": {
        "summary": "Interactive Live Presentation Sandbox & Test Environment",
        "operationId": "getSandboxDemo",
        "description": "Live interactive test environment and sandbox room demonstrating real-time slide transitions, interruptible voice narration, and high-intent attendee CTAs.",
        "responses": {
          "200": {
            "description": "Interactive presentation test room rendered successfully",
            "content": {
              "text/html": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "/ask": {
      "post": {
        "summary": "Natural Language Site Q&A (NLWeb Protocol)",
        "operationId": "askQuestion",
        "description": "NLWeb-conformant natural language Q&A endpoint supporting direct JSON answers and Server-Sent Events (SSE) streaming.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": { "type": "string", "example": "What is Seminara?" }
                },
                "required": ["query"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "NLWeb answer response or SSE stream",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "query": { "type": "string" },
                    "answer": { "type": "string" },
                    "sources": { "type": "array", "items": { "type": "object" } }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/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.",
        "x-payment-info": {
          "intent": "session",
          "method": "card",
          "amount": 19900,
          "currency": "USD",
          "description": "Seminara Core Host monthly plan upgrade or presentation quota refill via integrated billing engine"
        },
        "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" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/webhooks": {
      "get": {
        "summary": "List Webhook Subscriptions",
        "operationId": "listWebhooks",
        "description": "Lists all active outbound webhook subscriptions configured for CRM sync (HubSpot, Salesforce, Zapier, Make).",
        "security": [
          { "ApiKeyAuth": [] }
        ],
        "responses": {
          "200": {
            "description": "List of webhook subscriptions retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "subscriptions": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/WebhookSubscription" }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create Webhook Subscription",
        "operationId": "createWebhook",
        "description": "Creates a new outbound webhook endpoint with SSRF protection and generates an HMAC SHA-256 secret (whsec_...) for payload verification.",
        "security": [
          { "ApiKeyAuth": [] }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url"],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "The destination URL to receive HTTPS POST event payloads."
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": ["session.completed", "attendee.cta_clicked", "lead.captured"]
                    },
                    "default": ["session.completed", "attendee.cta_clicked", "lead.captured"],
                    "description": "List of event types to subscribe to."
                  },
                  "description": {
                    "type": "string",
                    "description": "Optional human-readable label for this subscription (e.g. HubSpot Sync)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Webhook subscription created successfully. Contains the raw signing secret (shown only once).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "subscription": { "$ref": "#/components/schemas/WebhookSubscriptionWithSecret" },
                    "message": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request (e.g. invalid URL or private/SSRF restricted host).",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete Webhook Subscription",
        "operationId": "deleteWebhook",
        "description": "Deactivates and deletes an existing webhook subscription by ID.",
        "security": [
          { "ApiKeyAuth": [] }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "description": "UUID of the webhook subscription to delete."
          }
        ],
        "responses": {
          "200": {
            "description": "Webhook subscription deleted successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": { "type": "string" }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    }
  }
}