{ "components": { "responses": { "AuthorizationException": { "content": { "application/json": { "schema": { "properties": { "message": { "description": "Error overview.", "type": "string" } }, "required": [ "message" ], "type": "object" } } }, "description": "Authorization error" }, "ModelNotFoundException": { "content": { "application/json": { "schema": { "properties": { "message": { "description": "Error overview.", "type": "string" } }, "required": [ "message" ], "type": "object" } } }, "description": "Not found" }, "ValidationException": { "content": { "application/json": { "schema": { "properties": { "errors": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "description": "A detailed description of each field that failed validation.", "type": "object" }, "message": { "description": "Errors overview.", "type": "string" } }, "required": [ "message", "errors" ], "type": "object" } } }, "description": "Validation error" } }, "schemas": { "AuditLogEventResource": { "properties": { "active_ms": { "type": [ "integer", "null" ] }, "active_seconds": { "type": [ "number", "null" ] }, "book_id": { "type": "integer" }, "event_type": { "type": "string" }, "id": { "type": "string" }, "metadata": { "anyOf": [ { "type": "null" }, { "type": "object" }, { "type": "string" } ] }, "occurred_at": { "type": [ "string", "null" ] }, "page_number": { "type": [ "integer", "null" ] }, "reason": { "type": "string" }, "source": { "type": "string" }, "source_event_id": { "type": "integer" }, "viewer_email": { "type": "string" }, "viewer_id": { "type": [ "integer", "null" ] } }, "required": [ "id", "source", "source_event_id", "book_id", "viewer_id", "viewer_email", "event_type", "page_number", "active_ms", "active_seconds", "reason", "metadata", "occurred_at" ], "title": "AuditLogEventResource", "type": "object" }, "BookInteractionEventResource": { "properties": { "active_ms": { "type": [ "integer", "null" ] }, "active_seconds": { "type": [ "number", "null" ] }, "book_id": { "type": "integer" }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "event_type": { "type": "string" }, "exit_reason": { "type": "string" }, "id": { "type": "integer" }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] }, "metadata": { "items": [], "type": [ "array", "null" ] }, "occurred_at": { "type": "string" }, "page_number": { "type": [ "integer", "null" ] }, "region": { "type": [ "string", "null" ] }, "session_id": { "type": "string" }, "source_host": { "type": [ "string", "null" ] }, "source_type": { "type": "string" }, "tracked_link_id": { "type": [ "integer", "null" ] }, "viewer_email": { "type": "string" }, "viewer_id": { "type": [ "integer", "null" ] } }, "required": [ "id", "book_id", "viewer_id", "tracked_link_id", "session_id", "event_type", "page_number", "active_ms", "active_seconds", "exit_reason", "source_type", "source_host", "country", "region", "city", "latitude", "longitude", "metadata", "occurred_at", "created_at" ], "title": "BookInteractionEventResource", "type": "object" }, "BookInteractionEventType": { "enum": [ "session_started", "page_segment_completed", "link_clicked", "document_downloaded", "lead_form_submitted", "form_widget_opened", "checkout_widget_opened", "checkout_redirect_clicked", "session_ended" ], "title": "BookInteractionEventType", "type": "string" }, "BookPageInteractionSummaryResource": { "properties": { "avg_active_ms_per_reader": { "type": "integer" }, "avg_active_ms_per_segment": { "type": "integer" }, "avg_active_seconds_per_reader": { "type": "number" }, "avg_active_seconds_per_segment": { "type": "number" }, "book_id": { "type": "integer" }, "id": { "type": "integer" }, "median_active_ms_per_segment": { "type": "integer" }, "median_active_seconds_per_segment": { "type": "number" }, "page_number": { "type": "integer" }, "total_active_ms": { "type": "integer" }, "total_active_seconds": { "type": "number" }, "total_segments": { "type": "integer" }, "unique_readers": { "type": "integer" } }, "required": [ "id", "book_id", "page_number", "unique_readers", "total_active_ms", "total_active_seconds", "avg_active_ms_per_reader", "avg_active_seconds_per_reader", "avg_active_ms_per_segment", "avg_active_seconds_per_segment", "median_active_ms_per_segment", "median_active_seconds_per_segment", "total_segments" ], "title": "BookPageInteractionSummaryResource", "type": "object" }, "BookReaderPageInteractionSummaryResource": { "properties": { "avg_active_ms_per_segment": { "type": "integer" }, "avg_active_seconds_per_segment": { "type": "number" }, "book_id": { "type": "integer" }, "first_viewed_at": { "type": "string" }, "id": { "type": "integer" }, "last_viewed_at": { "type": "string" }, "page_number": { "type": "integer" }, "segments": { "type": "integer" }, "total_active_ms": { "type": "integer" }, "total_active_seconds": { "type": "number" }, "viewer_email": { "type": "string" }, "viewer_id": { "type": "integer" } }, "required": [ "id", "book_id", "viewer_id", "page_number", "total_active_ms", "total_active_seconds", "segments", "avg_active_ms_per_segment", "avg_active_seconds_per_segment", "first_viewed_at", "last_viewed_at" ], "title": "BookReaderPageInteractionSummaryResource", "type": "object" }, "BookResource": { "properties": { "batch_id": { "type": [ "string", "null" ] }, "created_at": { "format": "date-time", "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "embed_code": { "type": [ "string", "null" ] }, "external_catalog_id": { "type": [ "integer", "null" ] }, "id": { "type": "integer" }, "name": { "type": "string" }, "page_count": { "type": "integer" }, "preview_url": { "type": [ "string", "null" ] }, "published_date": { "type": [ "string", "null" ] }, "random_id": { "type": "string" }, "settings": { "properties": { "animation_type": { "type": "string" }, "background": { "type": [ "string", "null" ] }, "copyright_enabled": { "type": "boolean" }, "domains_enabled": { "type": "boolean" }, "downloadable": { "type": "boolean" }, "eod_enabled": { "type": "boolean" }, "fullscreen_enabled": { "type": "boolean" }, "image_display": { "type": [ "string", "null" ] }, "mobile_animation_type": { "type": [ "string", "null" ] }, "privacy": { "type": [ "string", "null" ] }, "share_social_media": { "type": "boolean" }, "sound_enabled": { "type": "boolean" } }, "required": [ "background", "downloadable", "fullscreen_enabled", "sound_enabled", "copyright_enabled", "share_social_media", "privacy", "image_display", "animation_type", "mobile_animation_type", "eod_enabled", "domains_enabled" ], "type": "object" }, "status": { "type": [ "string", "null" ] }, "thumbnail_url": { "type": [ "string", "null" ] }, "updated_at": { "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "id", "batch_id", "external_catalog_id", "name", "description", "status", "random_id", "page_count", "preview_url", "thumbnail_url", "embed_code", "published_date", "settings", "created_at", "updated_at" ], "title": "BookResource", "type": "object" }, "BookViewEventResource": { "properties": { "book_id": { "type": "integer" }, "book_title": { "type": "string" }, "city": { "type": [ "string", "null" ] }, "clicks": { "type": "integer" }, "country": { "type": [ "string", "null" ] }, "duration_seconds": { "type": "integer" }, "engagement_score": { "type": "string" }, "from_embedded": { "type": "boolean" }, "id": { "type": "integer" }, "impressions": { "type": "integer" }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] }, "pages_viewed": { "type": "integer" }, "reads": { "type": "integer" }, "recorded_at": { "type": "string" }, "region": { "type": [ "string", "null" ] }, "source_host": { "type": [ "string", "null" ] }, "tracked_link": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ], "type": [ "object", "null" ] }, "updated_at": { "type": "string" }, "viewer_email": { "type": "string" }, "viewer_id": { "type": [ "integer", "null" ] } }, "required": [ "id", "book_id", "viewer_id", "source_host", "from_embedded", "impressions", "reads", "clicks", "pages_viewed", "duration_seconds", "engagement_score", "country", "region", "city", "latitude", "longitude", "recorded_at", "updated_at" ], "title": "BookViewEventResource", "type": "object" }, "BrandColor": { "properties": { "brand_id": { "type": "integer" }, "created_at": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "type": "integer" }, "primary_color": { "type": [ "string", "null" ] }, "secondary_color": { "type": [ "string", "null" ] }, "tertiary_color": { "type": [ "string", "null" ] }, "updated_at": { "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "id", "brand_id", "primary_color", "secondary_color", "tertiary_color", "created_at", "updated_at" ], "title": "BrandColor", "type": "object" }, "BrandResource": { "properties": { "about_brand": { "type": [ "string", "null" ] }, "brand_color": { "$ref": "#/components/schemas/BrandColor" }, "brand_social_media": { "$ref": "#/components/schemas/BrandSocialMedia" }, "company_name": { "type": [ "string", "null" ] }, "contact_number": { "type": [ "string", "null" ] }, "created_at": { "format": "date-time", "type": [ "string", "null" ] }, "google_analytics": { "type": [ "string", "null" ] }, "id": { "type": "integer" }, "logo": { "type": [ "string", "null" ] }, "updated_at": { "format": "date-time", "type": [ "string", "null" ] }, "website_url": { "type": [ "string", "null" ] }, "workspace": { "$ref": "#/components/schemas/WorkspaceResource", "description": "Relationships" }, "workspace_id": { "type": "integer" } }, "required": [ "id", "workspace_id", "company_name", "logo", "contact_number", "website_url", "google_analytics", "about_brand", "created_at", "updated_at" ], "title": "BrandResource", "type": "object" }, "BrandSocialMedia": { "properties": { "brand_id": { "type": "integer" }, "created_at": { "format": "date-time", "type": [ "string", "null" ] }, "facebook": { "type": [ "string", "null" ] }, "id": { "type": "integer" }, "instagram": { "type": [ "string", "null" ] }, "linkedin": { "type": [ "string", "null" ] }, "pinterest": { "type": [ "string", "null" ] }, "twitter": { "type": [ "string", "null" ] }, "updated_at": { "format": "date-time", "type": [ "string", "null" ] }, "youtube": { "type": [ "string", "null" ] } }, "required": [ "id", "brand_id", "twitter", "linkedin", "facebook", "youtube", "instagram", "pinterest", "created_at", "updated_at" ], "title": "BrandSocialMedia", "type": "object" }, "BulkUpsertExternalCatalogItemsRequest": { "properties": { "items": { "items": { "items": { "type": "string" }, "minItems": 1, "type": "array" }, "maxItems": 500, "minItems": 1, "type": "array" } }, "required": [ "items" ], "title": "BulkUpsertExternalCatalogItemsRequest", "type": "object" }, "CatalogTemplateResource": { "properties": { "id": { "type": "string" }, "is_default": { "type": "boolean" }, "name": { "type": "string" }, "thumbnails": { "additionalProperties": [], "type": "object" }, "type": { "type": "string" } }, "required": [ "id", "name", "thumbnails", "type", "is_default" ], "title": "CatalogTemplateResource", "type": "object" }, "CreateBookFromTemplateRequest": { "properties": { "content": { "items": { "properties": { "author": { "maxLength": 255, "type": [ "string", "null" ] }, "categories": { "items": { "maxLength": 255, "type": [ "string", "null" ] }, "maxItems": 20, "type": [ "array", "null" ] }, "content": { "maxLength": 50000, "type": [ "string", "null" ] }, "currency": { "maxLength": 10, "type": [ "string", "null" ] }, "date": { "maxLength": 100, "type": [ "string", "null" ] }, "description": { "maxLength": 50000, "type": [ "string", "null" ] }, "excerpt": { "maxLength": 5000, "type": [ "string", "null" ] }, "gallery": { "items": { "format": "uri", "maxLength": 2048, "type": [ "string", "null" ] }, "maxItems": 20, "type": [ "array", "null" ] }, "id": { "type": "string" }, "image": { "format": "uri", "maxLength": 2048, "type": [ "string", "null" ] }, "price": { "type": [ "string", "null" ] }, "regular_price": { "type": [ "string", "null" ] }, "sale_price": { "type": [ "string", "null" ] }, "short_description": { "maxLength": 5000, "type": [ "string", "null" ] }, "sku": { "maxLength": 255, "type": [ "string", "null" ] }, "stock_status": { "maxLength": 100, "type": [ "string", "null" ] }, "title": { "maxLength": 500, "type": "string" }, "type": { "maxLength": 50, "type": [ "string", "null" ] }, "url": { "format": "uri", "maxLength": 2048, "type": [ "string", "null" ] } }, "required": [ "id", "title" ], "type": "object" }, "maxItems": 50, "minItems": 1, "type": "array" }, "metadata": { "properties": { "currency": { "maxLength": 10, "type": [ "string", "null" ] }, "currency_symbol": { "maxLength": 20, "type": [ "string", "null" ] }, "site_name": { "maxLength": 255, "type": [ "string", "null" ] }, "site_url": { "format": "uri", "maxLength": 2048, "type": [ "string", "null" ] } }, "type": "object" }, "source": { "enum": [ "wordpress", "woocommerce" ], "type": "string" }, "source_type": { "enum": [ "posts", "products" ], "type": "string" }, "template_id": { "minimum": 1, "type": [ "integer", "null" ] } }, "required": [ "source", "source_type", "content" ], "title": "CreateBookFromTemplateRequest", "type": "object" }, "CreateExternalCatalogRequest": { "properties": { "external_id": { "maxLength": 255, "type": [ "string", "null" ] }, "metadata": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "name": { "maxLength": 255, "type": "string" }, "source": { "enum": [ "woocommerce", "wordpress", "shopify", "ecwid", "custom" ], "type": [ "string", "null" ] }, "source_url": { "format": "uri", "maxLength": 2048, "type": [ "string", "null" ] }, "template_key": { "type": "string" } }, "required": [ "name" ], "title": "CreateExternalCatalogRequest", "type": "object" }, "CreateKonvaBookRequest": { "properties": { "canvas": { "properties": { "height": { "maximum": 10000, "minimum": 1, "type": "integer" }, "objects": { "items": { "items": { "type": "string" }, "minItems": 1, "type": "array" }, "maxItems": 250, "minItems": 1, "type": "array" }, "orientation": { "enum": [ "portrait", "landscape" ], "type": "string" }, "width": { "maximum": 10000, "minimum": 1, "type": "integer" } }, "required": [ "width", "height", "orientation", "objects" ], "type": "object" }, "page_images": { "items": { "maxLength": 22020096, "type": "string" }, "maxItems": 250, "minItems": 1, "type": "array" }, "settings": { "properties": { "allow_fullscreen": { "type": "boolean" }, "animation_type": { "maxLength": 255, "type": "string" }, "auto_links_enabled": { "type": "boolean" }, "background": { "maxLength": 2048, "type": [ "string", "null" ] }, "copyright_enabled": { "type": "boolean" }, "domains_enabled": { "type": "boolean" }, "downloadable_pdf": { "type": "boolean" }, "eod_enabled": { "type": "boolean" }, "flip_sound": { "type": "boolean" }, "image_display": { "maxLength": 255, "type": [ "string", "null" ] }, "mobile_animation_type": { "maxLength": 255, "type": [ "string", "null" ] }, "pdf_password": { "maxLength": 255, "type": [ "string", "null" ] }, "pdf_privacy_status": { "maxLength": 50, "type": [ "string", "null" ] }, "share_social_media": { "type": "boolean" } }, "type": "object" }, "status": { "enum": [ "draft", "publish" ], "type": "string" }, "thumbnail": { "maxLength": 22020096, "type": [ "string", "null" ] }, "title": { "maxLength": 255, "type": "string" } }, "required": [ "title", "canvas", "page_images" ], "title": "CreateKonvaBookRequest", "type": "object" }, "ExternalCatalogItemResource": { "properties": { "availability": { "items": [], "type": [ "array", "null" ] }, "available": { "type": [ "boolean", "null" ] }, "catalog_id": { "type": "integer" }, "categories": { "items": [], "type": [ "array", "null" ] }, "created_at": { "type": "string" }, "currency": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "external_item_key": { "type": "string" }, "external_product_id": { "type": "string" }, "external_variant_id": { "type": [ "string", "null" ] }, "gallery": { "items": [], "type": [ "array", "null" ] }, "id": { "type": "integer" }, "image": { "type": [ "string", "null" ] }, "last_availability_synced_at": { "type": "string" }, "last_sync_error": { "type": [ "string", "null" ] }, "last_sync_status": { "type": [ "string", "null" ] }, "last_synced_at": { "type": "string" }, "payload": { "items": [], "type": [ "array", "null" ] }, "price": { "type": [ "string", "null" ] }, "product_type": { "type": [ "string", "null" ] }, "raw_payload": { "items": [], "type": [ "array", "null" ] }, "regular_price": { "type": [ "string", "null" ] }, "sale_price": { "type": [ "string", "null" ] }, "short_description": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "status": { "type": [ "string", "null" ] }, "stock_quantity": { "type": [ "integer", "null" ] }, "stock_status": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "updated_at": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "workspace_id": { "type": "integer" } }, "required": [ "id", "catalog_id", "workspace_id", "source", "external_item_key", "external_product_id", "external_variant_id", "sku", "title", "status", "product_type", "price", "regular_price", "sale_price", "currency", "image", "gallery", "url", "description", "short_description", "categories", "payload", "raw_payload", "availability", "stock_status", "stock_quantity", "available", "last_synced_at", "last_availability_synced_at", "last_sync_status", "last_sync_error", "created_at", "updated_at" ], "title": "ExternalCatalogItemResource", "type": "object" }, "ExternalCatalogResource": { "properties": { "created_at": { "type": "string" }, "external_id": { "type": [ "string", "null" ] }, "id": { "type": "integer" }, "last_sync_error": { "type": [ "string", "null" ] }, "last_sync_status": { "type": [ "string", "null" ] }, "last_synced_at": { "type": "string" }, "metadata": { "items": [], "type": [ "array", "null" ] }, "name": { "type": "string" }, "source": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "updated_at": { "type": "string" }, "workspace_id": { "type": "integer" } }, "required": [ "id", "workspace_id", "name", "source", "external_id", "source_url", "status", "metadata", "last_synced_at", "last_sync_status", "last_sync_error", "created_at", "updated_at" ], "title": "ExternalCatalogResource", "type": "object" }, "ExternalCatalogSyncJobResource": { "properties": { "catalog_id": { "type": "integer" }, "created_at": { "type": "string" }, "errors": { "items": [], "type": "array" }, "finished_at": { "type": "string" }, "id": { "type": "integer" }, "progress": { "properties": { "accepted": { "type": "integer" }, "failed": { "type": "integer" }, "processed": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "total", "processed", "accepted", "failed" ], "type": "object" }, "started_at": { "type": "string" }, "status": { "type": "string" }, "type": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "catalog_id", "type", "status", "progress", "errors", "started_at", "finished_at", "created_at", "updated_at" ], "title": "ExternalCatalogSyncJobResource", "type": "object" }, "PlanResource": { "properties": { "amount": { "type": [ "string", "null" ] }, "cancel_at_period_end": { "type": "boolean" }, "created_at": { "format": "date-time", "type": [ "string", "null" ] }, "current_period_end": { "format": "date-time", "type": [ "string", "null" ] }, "customer_id": { "type": [ "string", "null" ] }, "id": { "type": "integer" }, "invoice_id": { "type": [ "string", "null" ] }, "offer": { "type": "string" }, "payment_method_id": { "type": [ "string", "null" ] }, "payment_recurring": { "type": [ "string", "null" ] }, "plan_name": { "type": [ "string", "null" ] }, "session_status": { "type": [ "string", "null" ] }, "subscription_id": { "type": [ "string", "null" ] }, "subscription_item_id": { "type": [ "string", "null" ] }, "subscription_status": { "type": [ "string", "null" ] }, "updated_at": { "format": "date-time", "type": [ "string", "null" ] }, "user_id": { "type": "integer" }, "workspace_id": { "type": [ "integer", "null" ] } }, "required": [ "id", "user_id", "workspace_id", "customer_id", "subscription_id", "payment_method_id", "invoice_id", "amount", "plan_name", "payment_recurring", "session_status", "subscription_status", "offer", "created_at", "updated_at", "subscription_item_id", "cancel_at_period_end", "current_period_end" ], "title": "PlanResource", "type": "object" }, "ReaderJourneyResource": { "properties": { "aggregates": { "properties": { "overall_engagement_score": { "type": "string" }, "total_books": { "type": "string" }, "total_duration_seconds": { "type": "string" }, "total_pages_viewed": { "type": "string" } }, "required": [ "total_books", "total_pages_viewed", "total_duration_seconds", "overall_engagement_score" ], "type": "object" }, "books": { "items": { "properties": { "book_id": { "type": "string" }, "duration_seconds": { "type": "string" }, "engagement_score": { "type": "string" }, "last_visit": { "type": "string" }, "pages_viewed": { "type": "string" }, "title": { "type": "string" }, "visits": { "type": "string" } }, "required": [ "book_id", "title", "visits", "pages_viewed", "duration_seconds", "engagement_score", "last_visit" ], "type": "object" }, "type": "array" }, "viewer": { "properties": { "email": { "type": "string" }, "id": { "type": "string" } }, "required": [ "id", "email" ], "type": "object" } }, "required": [ "viewer", "aggregates", "books" ], "title": "ReaderJourneyResource", "type": "object" }, "RenderExternalCatalogRequest": { "properties": { "cover": { "properties": { "description": { "maxLength": 5000, "type": [ "string", "null" ] }, "title": { "maxLength": 255, "type": [ "string", "null" ] }, "website": { "maxLength": 2048, "type": [ "string", "null" ] } }, "type": "object" }, "items": { "items": { "maxLength": 255, "type": "string" }, "maxItems": 250, "minItems": 1, "type": "array" }, "settings": { "properties": { "allow_fullscreen": { "type": "boolean" }, "animation_type": { "maxLength": 255, "type": "string" }, "auto_links_enabled": { "type": "boolean" }, "background": { "maxLength": 2048, "type": [ "string", "null" ] }, "copyright_enabled": { "type": "boolean" }, "domains_enabled": { "type": "boolean" }, "downloadable_pdf": { "type": "boolean" }, "eod_enabled": { "type": "boolean" }, "flip_sound": { "type": "boolean" }, "image_display": { "maxLength": 255, "type": [ "string", "null" ] }, "mobile_animation_type": { "maxLength": 255, "type": [ "string", "null" ] }, "pdf_password": { "maxLength": 255, "type": [ "string", "null" ] }, "pdf_privacy_status": { "maxLength": 50, "type": [ "string", "null" ] }, "share_social_media": { "type": "boolean" } }, "type": "object" }, "status": { "enum": [ "draft", "publish" ], "type": "string" }, "template_id": { "minimum": 1, "type": [ "integer", "null" ] }, "title": { "maxLength": 255, "type": [ "string", "null" ] } }, "title": "RenderExternalCatalogRequest", "type": "object" }, "StoreBrandRequest": { "properties": { "about_brand": { "type": [ "string", "null" ] }, "company_name": { "type": "string" }, "contact_number": { "type": [ "string", "null" ] }, "facebook": { "type": [ "string", "null" ] }, "file": { "contentMediaType": "application/octet-stream", "format": "binary", "maxLength": 2048, "type": [ "string", "null" ] }, "google_analytics": { "type": [ "string", "null" ] }, "instagram": { "type": [ "string", "null" ] }, "linkedin": { "type": [ "string", "null" ] }, "pinterest": { "type": [ "string", "null" ] }, "primary_color": { "type": [ "string", "null" ] }, "secondary_color": { "type": [ "string", "null" ] }, "tertiary_color": { "type": [ "string", "null" ] }, "twitter": { "type": [ "string", "null" ] }, "website_url": { "format": "uri", "type": [ "string", "null" ] }, "youtube": { "type": [ "string", "null" ] } }, "required": [ "company_name" ], "title": "StoreBrandRequest", "type": "object" }, "StoreTrackedLinkRequest": { "properties": { "channel": { "maxLength": 64, "type": [ "string", "null" ] }, "kind": { "enum": [ "manual", "system" ], "type": [ "string", "null" ] }, "metadata": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "name": { "maxLength": 255, "type": "string" }, "slug": { "maxLength": 64, "type": [ "string", "null" ] } }, "required": [ "name" ], "title": "StoreTrackedLinkRequest", "type": "object" }, "TriggerWebhookRequest": { "properties": { "event": { "enum": [ "flipbook.created", "flipbook.updated", "subscriber.added" ], "type": [ "string", "null" ] }, "payload": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "url": { "format": "uri", "maxLength": 2048, "type": [ "string", "null" ] } }, "title": "TriggerWebhookRequest", "type": "object" }, "UpdateBrandRequest": { "properties": { "about_brand": { "type": [ "string", "null" ] }, "company_name": { "type": "string" }, "contact_number": { "type": [ "string", "null" ] }, "facebook": { "type": [ "string", "null" ] }, "file": { "contentMediaType": "application/octet-stream", "format": "binary", "maxLength": 2048, "type": [ "string", "null" ] }, "google_analytics": { "type": [ "string", "null" ] }, "id": { "type": "integer" }, "instagram": { "type": [ "string", "null" ] }, "linkedin": { "type": [ "string", "null" ] }, "pinterest": { "type": [ "string", "null" ] }, "primary_color": { "type": [ "string", "null" ] }, "secondary_color": { "type": [ "string", "null" ] }, "tertiary_color": { "type": [ "string", "null" ] }, "twitter": { "type": [ "string", "null" ] }, "website_url": { "format": "uri", "type": [ "string", "null" ] }, "youtube": { "type": [ "string", "null" ] } }, "required": [ "id", "company_name" ], "title": "UpdateBrandRequest", "type": "object" }, "UpdateExternalCatalogAvailabilityRequest": { "properties": { "items": { "items": { "items": { "type": "string" }, "minItems": 1, "type": "array" }, "maxItems": 1000, "minItems": 1, "type": "array" }, "snapshot_at": { "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "items" ], "title": "UpdateExternalCatalogAvailabilityRequest", "type": "object" }, "UpdateFlipbookSettingsRequest": { "properties": { "allow_fullscreen": { "type": "boolean" }, "animation_type": { "maxLength": 255, "type": "string" }, "auto_links_enabled": { "type": "boolean" }, "background": { "maxLength": 2048, "type": [ "string", "null" ] }, "copyright_enabled": { "type": "boolean" }, "description": { "maxLength": 50000, "type": [ "string", "null" ] }, "domains_enabled": { "type": "boolean" }, "downloadable_pdf": { "type": "boolean" }, "eod_enabled": { "type": "boolean" }, "flip_sound": { "type": "boolean" }, "image_display": { "maxLength": 255, "type": [ "string", "null" ] }, "magic_link_error_message": { "maxLength": 1000, "type": [ "string", "null" ] }, "magic_link_message": { "maxLength": 1000, "type": [ "string", "null" ] }, "mobile_animation_type": { "maxLength": 255, "type": [ "string", "null" ] }, "pdf_password": { "maxLength": 255, "type": [ "string", "null" ] }, "pdf_privacy_status": { "maxLength": 50, "type": [ "string", "null" ] }, "published_date": { "format": "date-time", "type": [ "string", "null" ] }, "share_social_media": { "type": "boolean" }, "slug": { "maxLength": 255, "type": [ "string", "null" ] }, "status": { "enum": [ "draft", "schedule", "publish" ], "type": "string" }, "title": { "maxLength": 255, "type": "string" } }, "required": [ "status", "published_date" ], "title": "UpdateFlipbookSettingsRequest", "type": "object" }, "UploadPdfResource": { "properties": { "batch_id": { "type": "string" } }, "required": [ "batch_id" ], "title": "UploadPdfResource", "type": "object" }, "UserAddress": { "properties": { "address": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "created_at": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "type": "integer" }, "state": { "type": [ "string", "null" ] }, "updated_at": { "format": "date-time", "type": [ "string", "null" ] }, "user_id": { "type": "integer" }, "zip": { "type": [ "string", "null" ] } }, "required": [ "id", "user_id", "address", "country", "zip", "state", "created_at", "updated_at" ], "title": "UserAddress", "type": "object" }, "UserResource": { "properties": { "address": { "$ref": "#/components/schemas/UserAddress", "description": "Column doesn't exist in users table" }, "avatar": { "type": [ "string", "null" ] }, "company": { "type": "null" }, "created_at": { "format": "date-time", "type": [ "string", "null" ] }, "email": { "type": "string" }, "first_name": { "type": "string" }, "full_name": { "type": "string" }, "id": { "type": "integer" }, "last_name": { "type": [ "string", "null" ] }, "phone": { "description": "Use user_address relationship instead", "type": [ "string", "null" ] }, "stripe_id": { "type": [ "string", "null" ] }, "theme": { "type": "string" }, "updated_at": { "format": "date-time", "type": [ "string", "null" ] }, "user_address": { "$ref": "#/components/schemas/UserAddress" }, "user_workspace_middle": { "items": { "properties": { "id": { "type": "integer" }, "user_id": { "type": "integer" }, "user_type": { "type": [ "string", "null" ] }, "workspace": { "$ref": "#/components/schemas/WorkspaceResource" }, "workspace_id": { "type": "integer" } }, "required": [ "id", "user_id", "workspace_id", "user_type", "workspace" ], "type": "object" }, "type": "array" } }, "required": [ "id", "email", "first_name", "last_name", "full_name", "company", "address", "phone", "avatar", "theme", "stripe_id", "created_at", "updated_at", "user_workspace_middle", "user_address" ], "title": "UserResource", "type": "object" }, "ValidateBookFilesRequest": { "properties": { "auto_links_enabled": { "type": "boolean" }, "files": { "items": { "contentMediaType": "application/octet-stream", "format": "binary", "maxLength": 0, "type": "string" }, "minItems": 1, "type": "array" }, "original_filename": { "maxLength": 255, "type": "string" }, "status": { "enum": [ "draft", "publish" ], "type": "string" } }, "required": [ "files" ], "title": "ValidateBookFilesRequest", "type": "object" }, "WorkspaceResource": { "properties": { "created_at": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "type": "integer" }, "owner": { "$ref": "#/components/schemas/UserResource", "description": "Include relationships when loaded" }, "owner_id": { "type": [ "integer", "null" ] }, "plan": { "$ref": "#/components/schemas/PlanResource" }, "slug": { "type": [ "string", "null" ] }, "updated_at": { "format": "date-time", "type": [ "string", "null" ] }, "workspace": { "type": [ "string", "null" ] } }, "required": [ "id", "workspace", "slug", "owner_id", "created_at", "updated_at" ], "title": "WorkspaceResource", "type": "object" }, "WorkspaceSubscriberRequest": { "properties": { "book_id": { "type": "integer" }, "email": { "format": "email", "maxLength": 255, "type": "string" }, "type": { "enum": [ "email", "domain" ], "type": [ "string", "null" ] } }, "required": [ "book_id", "email" ], "title": "WorkspaceSubscriberRequest", "type": "object" } }, "securitySchemes": { "oauth2": { "description": "OAuth access token issued by Flipbooker.", "flows": { "authorizationCode": { "authorizationUrl": "https://app.flipbooker.com/oauth/authorize", "scopes": { "analytics:read": "View analytics and engagement data", "books:read": "View your flipbooks and their settings", "books:write": "Create and update flipbooks", "brand:read": "View brand settings and assets", "brand:write": "Update brand settings and upload assets", "catalogs:read": "View product catalogs, catalog items, and sync status", "catalogs:write": "Create and update product catalog data", "exports:read": "Export data and generate reports", "subscribers:read": "View subscriber information", "subscribers:write": "Manage subscribers", "tracked-links:read": "View tracked links", "tracked-links:write": "Create and manage tracked links", "webhooks:read": "View webhook subscriptions and delivery history", "webhooks:write": "Manage webhook configurations" }, "tokenUrl": "https://app.flipbooker.com/oauth/token" } }, "type": "oauth2" }, "workspaceApiKey": { "description": "Workspace API key sent as an Authorization bearer token.", "scheme": "bearer", "type": "http" } } }, "info": { "description": "Public API for managing flipbooks, subscribers, analytics, and more. All endpoints require authentication via workspace API keys.", "title": "Flipbook Public API Documentation", "version": "1.0.0" }, "openapi": "3.1.0", "paths": { "/analytics/audit-log": { "get": { "description": "Returns a chronological record of analytics events.", "operationId": "api.v1.analytics.audit-log", "parameters": [ { "in": "query", "name": "book_id", "required": true, "schema": { "type": "integer" } }, { "in": "query", "name": "viewer_id", "schema": { "type": [ "integer", "null" ] } }, { "in": "query", "name": "event_type", "schema": { "enum": [ "access_requested", "access_granted", "access_rejected", "document_downloaded", "link_clicked", "lead_form_submitted", "form_widget_opened", "checkout_widget_opened", "checkout_redirect_clicked" ], "type": [ "string", "null" ] } }, { "in": "query", "name": "date", "schema": { "pattern": "^(all|\\d+)$", "type": [ "string", "null" ] } }, { "in": "query", "name": "tracked_link_id", "schema": { "type": [ "integer", "null" ] } }, { "in": "query", "name": "limit", "schema": { "maximum": 500, "minimum": 1, "type": [ "integer", "null" ] } }, { "in": "query", "name": "cursor", "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AuditLogEventResource" }, "type": "array" }, "meta": { "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "prev_cursor": { "type": "string" } }, "required": [ "next_cursor", "prev_cursor", "has_more", "path" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "422": { "$ref": "#/components/responses/ValidationException" } }, "security": [ { "workspaceApiKey": [ "analytics:read" ] }, { "oauth2": [ "analytics:read" ] } ], "summary": "Get the analytics audit log", "tags": [ "Analytics" ], "x-plan-features": [ "per_reader_analytics" ], "x-scopes": [ "analytics:read" ] } }, "/analytics/book-flow": { "get": { "description": "Returns page-to-page reader transitions for a flipbook.", "operationId": "api.v1.analytics.book-flow", "parameters": [ { "in": "query", "name": "book_id", "required": true, "schema": { "type": "integer" } }, { "in": "query", "name": "date", "schema": { "pattern": "^(all|[1-9][0-9]*)$", "type": [ "string", "null" ] } }, { "in": "query", "name": "tracked_link_id", "schema": { "type": [ "integer", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "aggregates": { "properties": { "downloads": { "type": "integer" }, "link_clicks": { "type": "integer" }, "max_total_active_ms": { "type": "integer" }, "max_unique_readers": { "type": "integer" }, "pages": { "type": "integer" } }, "required": [ "pages", "downloads", "link_clicks", "max_unique_readers", "max_total_active_ms" ], "type": "object" }, "baseline_unique_readers": { "type": "integer" }, "book_id": { "type": "integer" }, "pages": { "items": { "properties": { "avg_active_ms_per_reader": { "type": "integer" }, "avg_active_ms_per_segment": { "type": "integer" }, "avg_active_seconds_per_reader": { "type": "number" }, "avg_active_seconds_per_segment": { "type": "number" }, "median_active_ms_per_segment": { "type": "integer" }, "median_active_seconds_per_segment": { "type": "number" }, "page_number": { "type": "integer" }, "reach_rate": { "type": "number" }, "total_active_ms": { "type": "integer" }, "total_active_seconds": { "type": "number" }, "total_segments": { "type": "integer" }, "unique_readers": { "type": "integer" } }, "required": [ "page_number", "unique_readers", "reach_rate", "total_active_ms", "total_active_seconds", "avg_active_ms_per_reader", "avg_active_seconds_per_reader", "avg_active_ms_per_segment", "avg_active_seconds_per_segment", "median_active_ms_per_segment", "median_active_seconds_per_segment", "total_segments" ], "type": "object" }, "type": "array" } }, "required": [ "book_id", "baseline_unique_readers", "aggregates", "pages" ], "type": "object" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "422": { "$ref": "#/components/responses/ValidationException" } }, "security": [ { "workspaceApiKey": [ "analytics:read" ] }, { "oauth2": [ "analytics:read" ] } ], "summary": "Get reading flow", "tags": [ "Analytics" ], "x-plan-features": [ "per_reader_analytics" ], "x-scopes": [ "analytics:read" ] } }, "/analytics/book-view-events": { "get": { "description": "Returns raw per-reader flipbook view events.", "operationId": "api.v1.analytics.book-view-events", "parameters": [ { "in": "query", "name": "book_id", "required": true, "schema": { "type": "integer" } }, { "in": "query", "name": "date", "schema": { "pattern": "^(all|\\d+)$", "type": [ "string", "null" ] } }, { "in": "query", "name": "limit", "schema": { "maximum": 500, "minimum": 1, "type": [ "integer", "null" ] } }, { "in": "query", "name": "cursor", "schema": { "type": [ "string", "null" ] } }, { "in": "query", "name": "source_host", "schema": { "maxLength": 255, "type": [ "string", "null" ] } }, { "in": "query", "name": "viewer_id", "schema": { "type": [ "integer", "null" ] } }, { "in": "query", "name": "tracked_link_id", "schema": { "type": [ "integer", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/BookViewEventResource" }, "type": "array" }, "meta": { "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "prev_cursor": { "type": "string" } }, "required": [ "next_cursor", "prev_cursor", "has_more", "path" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "422": { "$ref": "#/components/responses/ValidationException" } }, "security": [ { "workspaceApiKey": [ "analytics:read" ] }, { "oauth2": [ "analytics:read" ] } ], "summary": "List view events", "tags": [ "Analytics" ], "x-plan-features": [ "per_reader_analytics" ], "x-scopes": [ "analytics:read" ] } }, "/analytics/interaction-events": { "get": { "description": "Returns raw reader interaction events such as clicks, plays and downloads.", "operationId": "api.v1.analytics.interaction-events", "parameters": [ { "in": "query", "name": "book_id", "required": true, "schema": { "type": "integer" } }, { "in": "query", "name": "viewer_id", "schema": { "type": [ "integer", "null" ] } }, { "in": "query", "name": "event_type", "schema": { "$ref": "#/components/schemas/BookInteractionEventType" } }, { "in": "query", "name": "page_number", "schema": { "minimum": 1, "type": [ "integer", "null" ] } }, { "in": "query", "name": "session_id", "schema": { "maxLength": 255, "type": [ "string", "null" ] } }, { "in": "query", "name": "date", "schema": { "pattern": "^(all|\\d+)$", "type": [ "string", "null" ] } }, { "in": "query", "name": "tracked_link_id", "schema": { "type": [ "integer", "null" ] } }, { "in": "query", "name": "limit", "schema": { "maximum": 500, "minimum": 1, "type": [ "integer", "null" ] } }, { "in": "query", "name": "cursor", "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/BookInteractionEventResource" }, "type": "array" }, "meta": { "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "prev_cursor": { "type": "string" } }, "required": [ "next_cursor", "prev_cursor", "has_more", "path" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "422": { "$ref": "#/components/responses/ValidationException" } }, "security": [ { "workspaceApiKey": [ "analytics:read" ] }, { "oauth2": [ "analytics:read" ] } ], "summary": "List interaction events", "tags": [ "Analytics" ], "x-plan-features": [ "per_reader_analytics" ], "x-scopes": [ "analytics:read" ] } }, "/analytics/page-performance": { "get": { "description": "Returns aggregate engagement for each page.", "operationId": "api.v1.analytics.page-performance", "parameters": [ { "in": "query", "name": "book_id", "required": true, "schema": { "type": "integer" } }, { "in": "query", "name": "date", "schema": { "pattern": "^(all|[1-9][0-9]*)$", "type": [ "string", "null" ] } }, { "in": "query", "name": "tracked_link_id", "schema": { "type": [ "integer", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "anyOf": [ { "properties": { "data": { "items": { "$ref": "#/components/schemas/BookPageInteractionSummaryResource" }, "type": "array" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" }, { "properties": { "data": { "items": { "properties": { "avg_active_ms_per_reader": { "type": "integer" }, "avg_active_ms_per_segment": { "type": "integer" }, "avg_active_seconds_per_reader": { "type": "number" }, "avg_active_seconds_per_segment": { "type": "number" }, "book_id": { "type": "integer" }, "id": { "type": "string" }, "median_active_ms_per_segment": { "type": "integer" }, "median_active_seconds_per_segment": { "type": "number" }, "page_number": { "type": "integer" }, "total_active_ms": { "type": "integer" }, "total_active_seconds": { "type": "number" }, "total_segments": { "type": "integer" }, "unique_readers": { "type": "integer" } }, "required": [ "id", "book_id", "page_number", "unique_readers", "total_active_ms", "total_active_seconds", "avg_active_ms_per_reader", "avg_active_seconds_per_reader", "avg_active_ms_per_segment", "avg_active_seconds_per_segment", "median_active_ms_per_segment", "median_active_seconds_per_segment", "total_segments" ], "type": "object" }, "type": "array" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" } ] } } }, "description": "" }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "422": { "$ref": "#/components/responses/ValidationException" } }, "security": [ { "workspaceApiKey": [ "analytics:read" ] }, { "oauth2": [ "analytics:read" ] } ], "summary": "Summarise page performance", "tags": [ "Analytics" ], "x-plan-features": [ "per_reader_analytics" ], "x-scopes": [ "analytics:read" ] } }, "/analytics/reader-journey": { "get": { "description": "Returns the ordered timeline for one reader across sessions.", "operationId": "api.v1.analytics.reader-journey", "parameters": [ { "in": "query", "name": "viewer_id", "schema": { "type": [ "integer", "null" ] } }, { "in": "query", "name": "session_id", "schema": { "maxLength": 255, "type": [ "string", "null" ] } }, { "in": "query", "name": "date", "schema": { "pattern": "^(all|\\d+)$", "type": [ "string", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "anyOf": [ { "properties": { "data": { "$ref": "#/components/schemas/ReaderJourneyResource" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" }, { "properties": { "data": { "properties": { "aggregates": { "properties": { "overall_engagement_score": { "type": "integer" }, "total_books": { "type": "integer" }, "total_duration_seconds": { "type": "integer" }, "total_pages_viewed": { "type": "integer" } }, "required": [ "total_books", "total_pages_viewed", "total_duration_seconds", "overall_engagement_score" ], "type": "object" }, "books": { "items": { "properties": { "book_id": { "type": "integer" }, "duration_seconds": { "type": "integer" }, "engagement_score": { "type": "integer" }, "last_visit": { "type": "string" }, "pages_viewed": { "type": "integer" }, "title": { "anyOf": [ { "type": "string" }, { "enum": [ "Unknown" ], "type": "string" } ] }, "visits": { "const": 1, "type": "integer" } }, "required": [ "book_id", "title", "visits", "pages_viewed", "duration_seconds", "engagement_score", "last_visit" ], "type": "object" }, "type": "array" }, "session": { "properties": { "first_seen_at": { "type": "string" }, "is_anonymous": { "type": "boolean" }, "last_country": { "type": "string" }, "last_seen_at": { "type": "string" }, "last_source_host": { "type": "string" }, "last_source_type": { "type": "string" }, "session_id": { "type": [ "string", "null" ] } }, "required": [ "session_id", "is_anonymous", "first_seen_at", "last_seen_at", "last_country", "last_source_host", "last_source_type" ], "type": "object" }, "viewer": { "type": "null" } }, "required": [ "viewer", "session", "aggregates", "books" ], "type": "object" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" } ] } } }, "description": "" }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "422": { "$ref": "#/components/responses/ValidationException" } }, "security": [ { "workspaceApiKey": [ "analytics:read" ] }, { "oauth2": [ "analytics:read" ] } ], "summary": "Get a reader's journey", "tags": [ "Analytics" ], "x-plan-features": [ "per_reader_analytics" ], "x-scopes": [ "analytics:read" ] } }, "/analytics/reader-pages": { "get": { "description": "Returns per-reader, per-page engagement.", "operationId": "api.v1.analytics.reader-pages", "parameters": [ { "in": "query", "name": "book_id", "required": true, "schema": { "type": "integer" } }, { "in": "query", "name": "viewer_id", "schema": { "type": [ "integer", "null" ] } }, { "in": "query", "name": "session_id", "schema": { "maxLength": 255, "type": [ "string", "null" ] } }, { "in": "query", "name": "date", "schema": { "pattern": "^(all|[1-9][0-9]*)$", "type": [ "string", "null" ] } }, { "in": "query", "name": "tracked_link_id", "schema": { "type": [ "integer", "null" ] } }, { "in": "query", "name": "page_number", "schema": { "minimum": 1, "type": [ "integer", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "anyOf": [ { "properties": { "data": { "items": { "$ref": "#/components/schemas/BookReaderPageInteractionSummaryResource" }, "type": "array" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" }, { "properties": { "data": { "items": { "properties": { "avg_active_ms_per_segment": { "type": "integer" }, "avg_active_seconds_per_segment": { "type": "number" }, "book_id": { "type": "integer" }, "first_viewed_at": { "type": "string" }, "id": { "type": "string" }, "last_viewed_at": { "type": "string" }, "page_number": { "type": "integer" }, "segments": { "type": "integer" }, "total_active_ms": { "type": "integer" }, "total_active_seconds": { "type": "number" }, "viewer_email": [], "viewer_id": { "type": "integer" } }, "required": [ "id", "book_id", "viewer_id", "viewer_email", "page_number", "total_active_ms", "total_active_seconds", "segments", "avg_active_ms_per_segment", "avg_active_seconds_per_segment", "first_viewed_at", "last_viewed_at" ], "type": "object" }, "type": "array" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" }, { "properties": { "data": { "items": { "properties": { "avg_active_ms_per_segment": { "type": "integer" }, "avg_active_seconds_per_segment": { "type": "number" }, "book_id": { "type": "integer" }, "first_viewed_at": { "type": "string" }, "id": { "type": "string" }, "is_anonymous": { "type": "boolean" }, "last_viewed_at": { "type": "string" }, "page_number": { "type": "integer" }, "segments": { "type": "integer" }, "session_id": { "type": [ "string", "null" ] }, "total_active_ms": { "type": "integer" }, "total_active_seconds": { "type": "number" }, "viewer_email": { "type": "null" }, "viewer_id": { "type": "null" } }, "required": [ "id", "book_id", "viewer_id", "viewer_email", "session_id", "is_anonymous", "page_number", "total_active_ms", "total_active_seconds", "segments", "avg_active_ms_per_segment", "avg_active_seconds_per_segment", "first_viewed_at", "last_viewed_at" ], "type": "object" }, "type": "array" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" } ] } } }, "description": "" }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "422": { "$ref": "#/components/responses/ValidationException" } }, "security": [ { "workspaceApiKey": [ "analytics:read" ] }, { "oauth2": [ "analytics:read" ] } ], "summary": "Summarise readers by page", "tags": [ "Analytics" ], "x-plan-features": [ "per_reader_analytics" ], "x-scopes": [ "analytics:read" ] } }, "/analytics/readers": { "get": { "description": "Returns one engagement summary per reader.", "operationId": "api.v1.analytics.readers", "parameters": [ { "in": "query", "name": "book_id", "required": true, "schema": { "type": "integer" } }, { "in": "query", "name": "viewer_id", "schema": { "type": [ "integer", "null" ] } }, { "in": "query", "name": "session_id", "schema": { "maxLength": 255, "type": [ "string", "null" ] } }, { "in": "query", "name": "include_anonymous", "schema": { "type": [ "boolean", "null" ] } }, { "in": "query", "name": "date", "schema": { "pattern": "^(all|[1-9][0-9]*)$", "type": [ "string", "null" ] } }, { "in": "query", "name": "sort", "schema": { "enum": [ "recent", "engagement" ], "type": [ "string", "null" ] } }, { "in": "query", "name": "tracked_link_id", "schema": { "type": [ "integer", "null" ] } }, { "in": "query", "name": "limit", "schema": { "maximum": 500, "minimum": 1, "type": [ "integer", "null" ] } }, { "in": "query", "name": "cursor", "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "anyOf": [ { "properties": { "data": { "items": { "type": "string" }, "type": "array" }, "meta": { "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "prev_cursor": { "type": "string" } }, "required": [ "next_cursor", "prev_cursor", "has_more", "path" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" }, { "properties": { "data": { "items": [], "type": "array" }, "meta": { "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "path": { "type": "string" }, "prev_cursor": { "type": [ "string", "null" ] } }, "required": [ "next_cursor", "prev_cursor", "has_more", "path" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } ] } } }, "description": "" }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "422": { "$ref": "#/components/responses/ValidationException" } }, "security": [ { "workspaceApiKey": [ "analytics:read" ] }, { "oauth2": [ "analytics:read" ] } ], "summary": "Summarise readers", "tags": [ "Analytics" ], "x-plan-features": [ "per_reader_analytics" ], "x-scopes": [ "analytics:read" ] } }, "/analytics/reading-session-pages": { "get": { "description": "Returns page-level detail within each reading session.", "operationId": "api.v1.analytics.reading-session-pages", "parameters": [ { "in": "query", "name": "book_id", "required": true, "schema": { "type": "integer" } }, { "in": "query", "name": "view_event_id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "string" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "422": { "$ref": "#/components/responses/ValidationException" } }, "security": [ { "workspaceApiKey": [ "analytics:read" ] }, { "oauth2": [ "analytics:read" ] } ], "summary": "Summarise sessions by page", "tags": [ "Analytics" ], "x-plan-features": [ "per_reader_analytics" ], "x-scopes": [ "analytics:read" ] } }, "/batches/{batchId}": { "delete": { "description": "Cancels an upload batch that is still in flight.", "operationId": "api.v1.batches.cancel", "parameters": [ { "in": "path", "name": "batchId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "anyOf": [ { "properties": { "data": { "anyOf": [ { "properties": { "batch_id": { "type": "string" }, "message": { "const": "Your upload was cancelled.", "type": "string" }, "state": { "const": "cancelled", "type": "string" } }, "required": [ "batch_id", "state", "message" ], "type": "object" }, { "items": [], "type": "array" }, { "properties": { "batch_id": { "type": "string" }, "message": { "const": "Your upload was already cancelled.", "type": "string" }, "state": { "const": "cancelled", "type": "string" } }, "required": [ "batch_id", "state", "message" ], "type": "object" } ] }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" }, { "type": "string" } ] } } }, "description": "" } }, "security": [ { "workspaceApiKey": [ "books:write" ] }, { "oauth2": [ "books:write" ] } ], "summary": "Cancel an upload batch", "tags": [ "Batches" ], "x-plan-features": [], "x-scopes": [ "books:write" ] }, "get": { "description": "Returns the status of an upload batch and the books it produced.", "operationId": "api.v1.batches.show", "parameters": [ { "in": "path", "name": "batchId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "books": { "items": { "$ref": "#/components/schemas/BookResource" }, "type": "array" }, "created_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "progress": { "properties": { "completed": { "type": "string" }, "failed": { "type": "string" }, "pending": { "type": "string" }, "total": { "type": "string" } }, "required": [ "total", "completed", "pending", "failed" ], "type": "object" }, "status": { "enum": [ "processing", "complete", "failed", "partial_failure", "cancelled" ], "type": "string" } }, "required": [ "id", "status", "progress", "books", "created_at", "finished_at" ], "type": "object" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "items": [], "type": "array" } }, "required": [ "error" ], "type": "object" } } }, "description": "Return 404 to avoid leaking batch existence" } }, "security": [ { "workspaceApiKey": [ "books:read" ] }, { "oauth2": [ "books:read" ] } ], "summary": "Retrieve a batch", "tags": [ "Batches" ], "x-plan-features": [], "x-scopes": [ "books:read" ] } }, "/books": { "get": { "description": "Returns the workspace flipbooks, newest first. The collection is cursor-paginated.", "operationId": "api.v1.books.index", "parameters": [ { "in": "query", "name": "filter[status]", "schema": { "enum": [ "publish", "draft", "schedule" ], "type": [ "string", "null" ] } }, { "in": "query", "name": "filter[name]", "schema": { "maxLength": 255, "type": [ "string", "null" ] } }, { "in": "query", "name": "sort", "schema": { "enum": [ "name", "-name", "created_at", "-created_at", "updated_at", "-updated_at", "status", "-status" ], "type": [ "string", "null" ] } }, { "in": "query", "name": "cursor", "schema": { "type": [ "string", "null" ] } }, { "in": "query", "name": "limit", "schema": { "maximum": 200, "minimum": 1, "type": [ "integer", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/BookResource" }, "type": "array" }, "meta": { "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "prev_cursor": { "type": "string" } }, "required": [ "next_cursor", "prev_cursor", "has_more", "path" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" }, "422": { "$ref": "#/components/responses/ValidationException" } }, "security": [ { "workspaceApiKey": [ "books:read" ] }, { "oauth2": [ "books:read" ] } ], "summary": "List flipbooks", "tags": [ "Books" ], "x-plan-features": [], "x-scopes": [ "books:read" ] }, "post": { "description": "Accepts a multipart PDF upload and queues conversion. The response contains a batch ID to poll.", "operationId": "api.v1.books.store", "requestBody": { "content": { "multipart/form-data": { "example": { "status": "draft" }, "schema": { "$ref": "#/components/schemas/ValidateBookFilesRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "" }, "202": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/UploadPdfResource" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" }, "422": { "$ref": "#/components/responses/ValidationException" } }, "security": [ { "workspaceApiKey": [ "books:write" ] }, { "oauth2": [ "books:write" ] } ], "summary": "Upload a PDF and create a flipbook", "tags": [ "Books" ], "x-plan-features": [], "x-scopes": [ "books:write" ] } }, "/books/create-from-template": { "post": { "description": "Creates a flipbook using a catalog template.", "operationId": "api.v1.books.create-from-template", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBookFromTemplateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "book": { "$ref": "#/components/schemas/BookResource" }, "edit_url": { "type": "string" }, "project": { "properties": { "id": { "type": "integer" } }, "required": [ "id" ], "type": "object" }, "status": { "const": "draft", "type": "string" } }, "required": [ "status", "book", "project", "edit_url" ], "type": "object" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" }, "422": { "$ref": "#/components/responses/ValidationException" } }, "security": [ { "workspaceApiKey": [ "books:write" ] }, { "oauth2": [ "books:write" ] } ], "summary": "Create a flipbook from a template", "tags": [ "Books" ], "x-plan-features": [], "x-scopes": [ "books:write" ] } }, "/books/konva": { "post": { "description": "Creates a flipbook from editor content.", "operationId": "api.v1.books.konva.store", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKonvaBookRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "anyOf": [ { "properties": { "data": { "$ref": "#/components/schemas/BookResource" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" }, { "type": "string" } ] } } }, "description": "" }, "422": { "$ref": "#/components/responses/ValidationException" } }, "security": [ { "workspaceApiKey": [ "books:write" ] }, { "oauth2": [ "books:write" ] } ], "summary": "Create an editor flipbook", "tags": [ "Books" ], "x-plan-features": [], "x-scopes": [ "books:write" ] } }, "/books/uploads/status/active": { "get": { "description": "Returns upload batches that are still converting.", "operationId": "api.v1.books.upload-status.active", "responses": { "200": { "content": { "application/json": { "schema": { "anyOf": [ { "properties": { "data": { "anyOf": [ { "properties": { "batch_id": { "type": "string" }, "conversion": { "properties": { "message": [], "progress": { "type": "integer" }, "state": { "const": "processing", "type": "string" }, "status": { "const": "processing", "type": "string" }, "tasks": { "items": { "properties": { "details": { "properties": { "pages": { "type": "integer" }, "s3_path": { "type": [ "string", "null" ] } }, "required": [ "pages", "s3_path" ], "type": "object" }, "message": { "anyOf": [ { "type": "string" }, { "enum": [ "Your file has been converted successfully.", "Something went wrong while converting your file. Please try again.", "Your file is being converted. This may take a moment.", "Your file is queued for conversion." ], "type": "string" } ] }, "payload": { "items": [], "type": [ "array", "null" ] }, "progress": { "type": "integer" }, "state": { "enum": [ "unknown", "processing", "failed", "completed" ], "type": "string" }, "status": { "enum": [ "unknown", "processing", "failed", "completed" ], "type": "string" }, "task_id": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "task_id", "status", "state", "progress", "message", "details", "payload", "updated_at" ], "type": [ "object", "null" ] }, "type": "array" } }, "required": [ "state", "status", "progress", "message", "tasks" ], "type": [ "object", "null" ] }, "failed_jobs": { "type": "string" }, "message": { "anyOf": [ { "type": "string" }, { "enum": [ "Your upload timed out. Please try again." ], "type": "string" } ] }, "pending_jobs": { "type": "string" }, "processed_jobs": { "type": "string" }, "progress": { "type": [ "object", "null" ] }, "state": { "anyOf": [ { "type": "string" }, { "enum": [ "failed" ], "type": "string" } ] }, "total_jobs": { "type": "string" }, "upload_outcome": { "items": [], "type": [ "array", "null" ] } }, "required": [ "batch_id", "state", "message", "progress", "total_jobs", "pending_jobs", "processed_jobs", "failed_jobs", "conversion", "upload_outcome" ], "type": "object" }, { "items": [], "type": "array" }, { "properties": { "batch_id": { "type": "null" }, "message": { "type": "null" }, "progress": { "type": "integer" }, "state": { "const": "idle", "type": "string" }, "status": { "const": "idle", "type": "string" } }, "required": [ "batch_id", "state", "status", "message", "progress" ], "type": "object" }, { "properties": { "batch_id": { "type": "null" }, "message": { "const": "Your file is being uploaded. Please wait a moment.", "type": "string" }, "progress": { "type": "integer" }, "state": { "const": "uploading", "type": "string" }, "status": { "const": "uploading", "type": "string" } }, "required": [ "batch_id", "state", "status", "message", "progress" ], "type": "object" } ] }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" }, { "type": "string" } ] } } }, "description": "" } }, "security": [ { "workspaceApiKey": [ "books:read" ] }, { "oauth2": [ "books:read" ] } ], "summary": "List active uploads", "tags": [ "Books" ], "x-plan-features": [], "x-scopes": [ "books:read" ] } }, "/books/uploads/{batchId}/status": { "get": { "description": "Returns conversion progress for one upload batch.", "operationId": "api.v1.books.upload-status", "parameters": [ { "in": "path", "name": "batchId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "anyOf": [ { "properties": { "data": { "anyOf": [ { "properties": { "batch_id": { "type": "string" }, "conversion": { "properties": { "message": [], "progress": { "type": "integer" }, "state": { "const": "processing", "type": "string" }, "status": { "const": "processing", "type": "string" }, "tasks": { "items": { "properties": { "details": { "properties": { "pages": { "type": "integer" }, "s3_path": { "type": [ "string", "null" ] } }, "required": [ "pages", "s3_path" ], "type": "object" }, "message": { "anyOf": [ { "type": "string" }, { "enum": [ "Your file has been converted successfully.", "Something went wrong while converting your file. Please try again.", "Your file is being converted. This may take a moment.", "Your file is queued for conversion." ], "type": "string" } ] }, "payload": { "items": [], "type": [ "array", "null" ] }, "progress": { "type": "integer" }, "state": { "enum": [ "unknown", "processing", "failed", "completed" ], "type": "string" }, "status": { "enum": [ "unknown", "processing", "failed", "completed" ], "type": "string" }, "task_id": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "task_id", "status", "state", "progress", "message", "details", "payload", "updated_at" ], "type": [ "object", "null" ] }, "type": "array" } }, "required": [ "state", "status", "progress", "message", "tasks" ], "type": [ "object", "null" ] }, "failed_jobs": { "type": "string" }, "message": { "anyOf": [ { "type": "string" }, { "enum": [ "Your upload timed out. Please try again." ], "type": "string" } ] }, "pending_jobs": { "type": "string" }, "processed_jobs": { "type": "string" }, "progress": { "type": [ "object", "null" ] }, "state": { "anyOf": [ { "type": "string" }, { "enum": [ "failed" ], "type": "string" } ] }, "total_jobs": { "type": "string" }, "upload_outcome": { "items": [], "type": [ "array", "null" ] } }, "required": [ "batch_id", "state", "message", "progress", "total_jobs", "pending_jobs", "processed_jobs", "failed_jobs", "conversion", "upload_outcome" ], "type": "object" }, { "items": [], "type": "array" } ] }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" }, { "type": "string" } ] } } }, "description": "" } }, "security": [ { "workspaceApiKey": [ "books:read" ] }, { "oauth2": [ "books:read" ] } ], "summary": "Get upload status", "tags": [ "Books" ], "x-plan-features": [], "x-scopes": [ "books:read" ] } }, "/books/{book}": { "delete": { "description": "Permanently deletes a flipbook and its generated assets.", "operationId": "api.v1.books.destroy", "parameters": [ { "description": "The book ID", "in": "path", "name": "book", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "message": { "const": "Book successfully deleted.", "type": "string" } }, "required": [ "message" ], "type": "object" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" } }, "security": [ { "workspaceApiKey": [ "books:write" ] }, { "oauth2": [ "books:write" ] } ], "summary": "Delete a flipbook", "tags": [ "Books" ], "x-plan-features": [], "x-scopes": [ "books:write" ] }, "get": { "description": "Fetches a single flipbook by its numeric ID.", "operationId": "api.v1.books.show", "parameters": [ { "description": "The book ID", "in": "path", "name": "book", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/BookResource" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" } }, "security": [ { "workspaceApiKey": [ "books:read" ] }, { "oauth2": [ "books:read" ] } ], "summary": "Retrieve a flipbook", "tags": [ "Books" ], "x-plan-features": [], "x-scopes": [ "books:read" ] } }, "/books/{book}/tracked-links": { "get": { "description": "Returns the tracked links configured on a flipbook and their click counts.", "operationId": "api.v1.books.tracked-links.index", "parameters": [ { "description": "The book ID", "in": "path", "name": "book", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "tracked_links": { "items": { "properties": { "book_id": { "type": [ "integer", "null" ] }, "clicks": { "type": "integer" }, "created_at": { "type": "string" }, "destination_url": { "type": "string" }, "id": { "type": "integer" }, "legacy_url": { "type": "string" }, "metadata": { "items": [], "type": [ "array", "null" ] }, "name": { "type": "string" }, "qr_url": { "type": "string" }, "slug": { "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "book_id", "name", "slug", "destination_url", "url", "qr_url", "legacy_url", "clicks", "metadata", "created_at" ], "type": "object" }, "type": "array" } }, "required": [ "tracked_links" ], "type": "object" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" } }, "security": [ { "workspaceApiKey": [ "tracked-links:read" ] }, { "oauth2": [ "tracked-links:read" ] } ], "summary": "List tracked links", "tags": [ "Tracked links" ], "x-plan-features": [], "x-scopes": [ "tracked-links:read" ] }, "post": { "description": "Adds a tracked link so clicks can be attributed to a reader.", "operationId": "api.v1.books.tracked-links.store", "parameters": [ { "description": "The book ID", "in": "path", "name": "book", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreTrackedLinkRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "tracked_link": { "properties": { "book_id": { "type": [ "integer", "null" ] }, "clicks": { "type": "integer" }, "created_at": { "type": "string" }, "destination_url": { "type": "string" }, "id": { "type": "integer" }, "legacy_url": { "type": "string" }, "metadata": { "items": [], "type": [ "array", "null" ] }, "name": { "type": "string" }, "qr_url": { "type": "string" }, "slug": { "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "book_id", "name", "slug", "destination_url", "url", "qr_url", "legacy_url", "clicks", "metadata", "created_at" ], "type": "object" } }, "required": [ "tracked_link" ], "type": "object" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "422": { "$ref": "#/components/responses/ValidationException" } }, "security": [ { "workspaceApiKey": [ "tracked-links:write" ] }, { "oauth2": [ "tracked-links:write" ] } ], "summary": "Create a tracked link", "tags": [ "Tracked links" ], "x-plan-features": [], "x-scopes": [ "tracked-links:write" ] } }, "/books/{book}/tracked-links/{trackedLink}": { "delete": { "description": "Removes a tracked link. Existing clicks are retained.", "operationId": "api.v1.books.tracked-links.destroy", "parameters": [ { "description": "The book ID", "in": "path", "name": "book", "required": true, "schema": { "type": "integer" } }, { "description": "The tracked link ID", "in": "path", "name": "trackedLink", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "message": { "const": "Tracked link deleted.", "type": "string" } }, "required": [ "message" ], "type": "object" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" } }, "security": [ { "workspaceApiKey": [ "tracked-links:write" ] }, { "oauth2": [ "tracked-links:write" ] } ], "summary": "Delete a tracked link", "tags": [ "Tracked links" ], "x-plan-features": [], "x-scopes": [ "tracked-links:write" ] } }, "/books/{id}": { "put": { "description": "Updates the supplied flipbook metadata and viewer settings.", "operationId": "api.v1.books.update", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFlipbookSettingsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/BookResource" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "items": [], "type": "array" } }, "required": [ "error" ], "type": "object" } } }, "description": "" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "422": { "$ref": "#/components/responses/ValidationException" } }, "security": [ { "workspaceApiKey": [ "books:write" ] }, { "oauth2": [ "books:write" ] } ], "summary": "Update flipbook settings", "tags": [ "Books" ], "x-plan-features": [], "x-scopes": [ "books:write" ] } }, "/brand": { "get": { "description": "Returns the workspace brand and public flipbook styling.", "operationId": "api.v1.brands.index", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "brand": { "anyOf": [ { "$ref": "#/components/schemas/BrandResource" }, { "type": "null" } ] } }, "required": [ "brand" ], "type": "object" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" } }, "security": [ { "workspaceApiKey": [ "brand:read" ] }, { "oauth2": [ "brand:read" ] } ], "summary": "Retrieve the brand", "tags": [ "Brand" ], "x-plan-features": [], "x-scopes": [ "brand:read" ] }, "post": { "description": "Creates the workspace brand record.", "operationId": "api.v1.brands.store", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/StoreBrandRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "brand": { "$ref": "#/components/schemas/BrandResource" } }, "required": [ "brand" ], "type": "object" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "items": [], "type": "array" } }, "required": [ "error" ], "type": "object" } } }, "description": "" }, "422": { "$ref": "#/components/responses/ValidationException" } }, "security": [ { "workspaceApiKey": [ "brand:write" ] }, { "oauth2": [ "brand:write" ] } ], "summary": "Create the brand", "tags": [ "Brand" ], "x-plan-features": [], "x-scopes": [ "brand:write" ] }, "put": { "description": "Updates the supplied workspace brand fields.", "operationId": "api.v1.brands.update", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/UpdateBrandRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "brand": { "anyOf": [ { "$ref": "#/components/schemas/BrandResource" }, { "type": "null" } ] } }, "required": [ "brand" ], "type": "object" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "items": [], "type": "array" } }, "required": [ "error" ], "type": "object" } } }, "description": "" }, "422": { "$ref": "#/components/responses/ValidationException" } }, "security": [ { "workspaceApiKey": [ "brand:write" ] }, { "oauth2": [ "brand:write" ] } ], "summary": "Update the brand", "tags": [ "Brand" ], "x-plan-features": [], "x-scopes": [ "brand:write" ] } }, "/catalogs": { "get": { "description": "Returns product catalogs in the workspace.", "operationId": "api.v1.catalogs.index", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ExternalCatalogResource" }, "type": "array" }, "meta": { "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "prev_cursor": { "type": "string" } }, "required": [ "next_cursor", "prev_cursor", "has_more", "path" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" } }, "security": [ { "workspaceApiKey": [ "catalogs:read" ] }, { "oauth2": [ "catalogs:read" ] } ], "summary": "List catalogs", "tags": [ "Catalogs" ], "x-plan-features": [], "x-scopes": [ "catalogs:read" ] }, "post": { "description": "Creates a product catalog.", "operationId": "api.v1.catalogs.store", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateExternalCatalogRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "catalog": { "$ref": "#/components/schemas/ExternalCatalogResource" }, "sync_job": { "$ref": "#/components/schemas/ExternalCatalogSyncJobResource" } }, "required": [ "catalog", "sync_job" ], "type": "object" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" }, "422": { "$ref": "#/components/responses/ValidationException" } }, "security": [ { "workspaceApiKey": [ "catalogs:write" ] }, { "oauth2": [ "catalogs:write" ] } ], "summary": "Create a catalog", "tags": [ "Catalogs" ], "x-plan-features": [], "x-scopes": [ "catalogs:write" ] } }, "/catalogs/{catalog}": { "delete": { "description": "Deletes a product catalog.", "operationId": "api.v1.catalogs.destroy", "parameters": [ { "description": "The catalog ID", "in": "path", "name": "catalog", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "catalog": { "$ref": "#/components/schemas/ExternalCatalogResource" }, "message": { "const": "Catalog archived.", "type": "string" } }, "required": [ "message", "catalog" ], "type": "object" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" } }, "security": [ { "workspaceApiKey": [ "catalogs:write" ] }, { "oauth2": [ "catalogs:write" ] } ], "summary": "Delete a catalog", "tags": [ "Catalogs" ], "x-plan-features": [], "x-scopes": [ "catalogs:write" ] }, "get": { "description": "Returns one product catalog and its metadata.", "operationId": "api.v1.catalogs.show", "parameters": [ { "description": "The catalog ID", "in": "path", "name": "catalog", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "catalog": { "$ref": "#/components/schemas/ExternalCatalogResource" } }, "required": [ "catalog" ], "type": "object" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" } }, "security": [ { "workspaceApiKey": [ "catalogs:read" ] }, { "oauth2": [ "catalogs:read" ] } ], "summary": "Retrieve a catalog", "tags": [ "Catalogs" ], "x-plan-features": [], "x-scopes": [ "catalogs:read" ] } }, "/catalogs/{catalog}/items": { "get": { "description": "Returns the products in a catalog.", "operationId": "api.v1.catalogs.items.index", "parameters": [ { "description": "The catalog ID", "in": "path", "name": "catalog", "required": true, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "schema": { "default": 25, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ExternalCatalogItemResource" }, "type": "array" }, "meta": { "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "prev_cursor": { "type": "string" } }, "required": [ "next_cursor", "prev_cursor", "has_more", "path" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" } }, "security": [ { "workspaceApiKey": [ "catalogs:read" ] }, { "oauth2": [ "catalogs:read" ] } ], "summary": "List catalog items", "tags": [ "Catalogs" ], "x-plan-features": [], "x-scopes": [ "catalogs:read" ] } }, "/catalogs/{catalog}/items/availability": { "patch": { "description": "Updates availability for catalog items.", "operationId": "api.v1.catalogs.items.availability", "parameters": [ { "description": "The catalog ID", "in": "path", "name": "catalog", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateExternalCatalogAvailabilityRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "summary": { "properties": { "accepted_items": { "type": "string" }, "errors": { "anyOf": [ { "type": "string" }, { "additionalItems": false, "items": { "type": "string" }, "maxItems": 0, "minItems": 0, "type": "array" } ] }, "failed_items": { "type": "string" }, "status": { "type": "string" }, "total_items": { "type": "string" } }, "required": [ "status", "total_items", "accepted_items", "failed_items", "errors" ], "type": "object" }, "sync_job": { "$ref": "#/components/schemas/ExternalCatalogSyncJobResource" } }, "required": [ "sync_job", "summary" ], "type": "object" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "422": { "$ref": "#/components/responses/ValidationException" } }, "security": [ { "workspaceApiKey": [ "catalogs:write" ] }, { "oauth2": [ "catalogs:write" ] } ], "summary": "Update catalog item availability", "tags": [ "Catalogs" ], "x-plan-features": [], "x-scopes": [ "catalogs:write" ] } }, "/catalogs/{catalog}/items/{item}": { "delete": { "description": "Removes an item from a catalog.", "operationId": "api.v1.catalogs.items.destroy", "parameters": [ { "description": "The catalog ID", "in": "path", "name": "catalog", "required": true, "schema": { "type": "integer" } }, { "description": "The item ID", "in": "path", "name": "item", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "message": { "const": "Catalog item deleted.", "type": "string" } }, "required": [ "message" ], "type": "object" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" } }, "security": [ { "workspaceApiKey": [ "catalogs:write" ] }, { "oauth2": [ "catalogs:write" ] } ], "summary": "Delete a catalog item", "tags": [ "Catalogs" ], "x-plan-features": [], "x-scopes": [ "catalogs:write" ] } }, "/catalogs/{catalog}/items:bulk-upsert": { "post": { "description": "Creates or updates multiple catalog items in one request.", "operationId": "api.v1.catalogs.items.bulk-upsert", "parameters": [ { "description": "The catalog ID", "in": "path", "name": "catalog", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkUpsertExternalCatalogItemsRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "summary": { "properties": { "accepted_items": { "type": "string" }, "errors": { "anyOf": [ { "type": "string" }, { "additionalItems": false, "items": { "type": "string" }, "maxItems": 0, "minItems": 0, "type": "array" } ] }, "failed_items": { "type": "string" }, "status": { "type": "string" }, "total_items": { "type": "string" } }, "required": [ "status", "total_items", "accepted_items", "failed_items", "errors" ], "type": "object" }, "sync_job": { "$ref": "#/components/schemas/ExternalCatalogSyncJobResource" } }, "required": [ "sync_job", "summary" ], "type": "object" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "422": { "$ref": "#/components/responses/ValidationException" } }, "security": [ { "workspaceApiKey": [ "catalogs:write" ] }, { "oauth2": [ "catalogs:write" ] } ], "summary": "Bulk upsert catalog items", "tags": [ "Catalogs" ], "x-plan-features": [], "x-scopes": [ "catalogs:write" ] } }, "/catalogs/{catalog}/render": { "post": { "description": "Creates a flipbook from a product catalog.", "operationId": "api.v1.catalogs.render", "parameters": [ { "description": "The catalog ID", "in": "path", "name": "catalog", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenderExternalCatalogRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "properties": { "message": { "description": "Error overview.", "example": "Unauthenticated workspace.", "type": "string" } }, "required": [ "message" ], "type": "object" } } }, "description": "An error" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "422": { "$ref": "#/components/responses/ValidationException" } }, "security": [ { "workspaceApiKey": [ "catalogs:read", "books:write" ] }, { "oauth2": [ "catalogs:read", "books:write" ] } ], "summary": "Render a catalog", "tags": [ "Catalogs" ], "x-plan-features": [], "x-scopes": [ "catalogs:read", "books:write" ] } }, "/catalogs/{catalog}/sync-jobs/{syncJob}": { "get": { "description": "Returns the status of a catalog synchronization job.", "operationId": "api.v1.catalogs.sync-jobs.show", "parameters": [ { "description": "The catalog ID", "in": "path", "name": "catalog", "required": true, "schema": { "type": "integer" } }, { "description": "The sync job ID", "in": "path", "name": "syncJob", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "sync_job": { "$ref": "#/components/schemas/ExternalCatalogSyncJobResource" } }, "required": [ "sync_job" ], "type": "object" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "properties": { "message": { "description": "Error overview.", "example": "Unauthenticated workspace.", "type": "string" } }, "required": [ "message" ], "type": "object" } } }, "description": "An error" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" } }, "security": [ { "workspaceApiKey": [ "catalogs:read" ] }, { "oauth2": [ "catalogs:read" ] } ], "summary": "Retrieve a catalog sync job", "tags": [ "Catalogs" ], "x-plan-features": [], "x-scopes": [ "catalogs:read" ] } }, "/exports/analytics/{bookId}": { "get": { "description": "Downloads a flipbook analytics summary as a CSV file.", "operationId": "api.v1.exports.analytics", "parameters": [ { "in": "path", "name": "bookId", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "text/csv": { "schema": { "type": "string" } } }, "description": "", "headers": { "Transfer-Encoding": { "required": true, "schema": { "enum": [ "chunked" ], "type": "string" } } } } }, "security": [ { "workspaceApiKey": [ "exports:read" ] }, { "oauth2": [ "exports:read" ] } ], "summary": "Export analytics", "tags": [ "Exports" ], "x-plan-features": [ "per_reader_analytics" ], "x-scopes": [ "exports:read" ] } }, "/exports/books/{bookId}/access-audit": { "get": { "description": "Downloads the flipbook access audit as CSV.", "operationId": "api.v1.exports.books.access-audit", "parameters": [ { "in": "path", "name": "bookId", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "text/csv": { "schema": { "type": "string" } } }, "description": "", "headers": { "Transfer-Encoding": { "required": true, "schema": { "enum": [ "chunked" ], "type": "string" } } } } }, "security": [ { "workspaceApiKey": [ "exports:read" ] }, { "oauth2": [ "exports:read" ] } ], "summary": "Export the access audit", "tags": [ "Exports" ], "x-plan-features": [ "per_reader_analytics" ], "x-scopes": [ "exports:read" ] } }, "/exports/books/{bookId}/leads": { "get": { "description": "Downloads captured lead form submissions as CSV.", "operationId": "api.v1.exports.books.leads", "parameters": [ { "in": "path", "name": "bookId", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "text/csv": { "schema": { "type": "string" } } }, "description": "", "headers": { "Transfer-Encoding": { "required": true, "schema": { "enum": [ "chunked" ], "type": "string" } } } } }, "security": [ { "workspaceApiKey": [ "exports:read" ] }, { "oauth2": [ "exports:read" ] } ], "summary": "Export leads", "tags": [ "Exports" ], "x-plan-features": [], "x-scopes": [ "exports:read" ] } }, "/exports/books/{id}/audit-log": { "get": { "description": "Downloads the analytics audit log as CSV.", "operationId": "api.v1.exports.books.audit-log", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "text/csv": { "schema": { "type": "string" } } }, "description": "", "headers": { "Transfer-Encoding": { "required": true, "schema": { "enum": [ "chunked" ], "type": "string" } } } } }, "security": [ { "workspaceApiKey": [ "exports:read" ] }, { "oauth2": [ "exports:read" ] } ], "summary": "Export the audit log", "tags": [ "Exports" ], "x-plan-features": [ "per_reader_analytics" ], "x-scopes": [ "exports:read" ] } }, "/exports/books/{id}/interaction-events": { "get": { "description": "Downloads raw reader interaction events as CSV.", "operationId": "api.v1.exports.books.interaction-events", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "text/csv": { "schema": { "type": "string" } } }, "description": "", "headers": { "Transfer-Encoding": { "required": true, "schema": { "enum": [ "chunked" ], "type": "string" } } } } }, "security": [ { "workspaceApiKey": [ "exports:read" ] }, { "oauth2": [ "exports:read" ] } ], "summary": "Export interaction events", "tags": [ "Exports" ], "x-plan-features": [ "per_reader_analytics" ], "x-scopes": [ "exports:read" ] } }, "/exports/books/{id}/page-performance": { "get": { "description": "Downloads aggregate page engagement as CSV.", "operationId": "api.v1.exports.books.page-performance", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "text/csv": { "schema": { "type": "string" } } }, "description": "", "headers": { "Transfer-Encoding": { "required": true, "schema": { "enum": [ "chunked" ], "type": "string" } } } } }, "security": [ { "workspaceApiKey": [ "exports:read" ] }, { "oauth2": [ "exports:read" ] } ], "summary": "Export page performance", "tags": [ "Exports" ], "x-plan-features": [ "per_reader_analytics" ], "x-scopes": [ "exports:read" ] } }, "/exports/books/{id}/reader-pages": { "get": { "description": "Downloads per-reader, per-page engagement as CSV.", "operationId": "api.v1.exports.books.reader-pages", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "text/csv": { "schema": { "type": "string" } } }, "description": "", "headers": { "Transfer-Encoding": { "required": true, "schema": { "enum": [ "chunked" ], "type": "string" } } } } }, "security": [ { "workspaceApiKey": [ "exports:read" ] }, { "oauth2": [ "exports:read" ] } ], "summary": "Export reader page summaries", "tags": [ "Exports" ], "x-plan-features": [ "per_reader_analytics" ], "x-scopes": [ "exports:read" ] } }, "/exports/books/{id}/readers": { "get": { "description": "Downloads per-reader engagement summaries as CSV.", "operationId": "api.v1.exports.books.readers", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "text/csv": { "schema": { "type": "string" } } }, "description": "", "headers": { "Transfer-Encoding": { "required": true, "schema": { "enum": [ "chunked" ], "type": "string" } } } } }, "security": [ { "workspaceApiKey": [ "exports:read" ] }, { "oauth2": [ "exports:read" ] } ], "summary": "Export reader summaries", "tags": [ "Exports" ], "x-plan-features": [ "per_reader_analytics" ], "x-scopes": [ "exports:read" ] } }, "/health": { "get": { "description": "Returns the API status and version.", "operationId": "api.v1.health", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "status": { "const": "healthy", "type": "string" }, "timestamp": { "type": "string" }, "version": { "type": "string" } }, "required": [ "status", "version", "timestamp" ], "type": "object" } } }, "description": "" } }, "summary": "Health check", "tags": [ "General" ], "x-plan-features": [], "x-scopes": [] } }, "/integrations/shopify/webhooks": { "post": { "description": "Processes a Shopify product data webhook for catalog synchronization.", "operationId": "api.v1.integrations.shopify.webhooks.store", "requestBody": { "content": { "application/json": { "schema": { "properties": { "payload": { "properties": { "customer": { "properties": { "email": { "format": "email", "maxLength": 255, "type": "string" }, "id": { "type": "integer" } }, "type": "object" }, "data_request": { "properties": { "id": { "type": "integer" } }, "type": "object" }, "shop_domain": { "maxLength": 255, "type": "string" }, "shop_id": { "type": "integer" } }, "required": [ "shop_id", "shop_domain" ], "type": "object" }, "shopDomain": { "maxLength": 255, "pattern": "^[a-z0-9][a-z0-9.-]*\\.myshopify\\.com$", "type": "string" }, "topic": { "enum": [ "customers/data_request", "customers/redact", "shop/redact" ], "type": "string" } }, "required": [ "topic", "shopDomain", "payload" ], "type": "object" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "counts": { "additionalProperties": { "type": "integer" }, "type": "object" }, "replayed": { "type": "boolean" }, "status": { "type": "string" } }, "required": [ "status", "action", "counts", "replayed" ], "type": "object" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "properties": { "message": { "description": "Error overview.", "example": "Unauthenticated workspace.", "type": "string" } }, "required": [ "message" ], "type": "object" } } }, "description": "An error" }, "422": { "$ref": "#/components/responses/ValidationException" } }, "security": [ { "workspaceApiKey": [ "catalogs:write" ] }, { "oauth2": [ "catalogs:write" ] } ], "summary": "Receive a Shopify product webhook", "tags": [ "Integrations" ], "x-plan-features": [], "x-scopes": [ "catalogs:write" ] } }, "/subscribers": { "get": { "description": "Returns subscribers captured across the workspace flipbooks.", "operationId": "api.v1.subscribers.index", "parameters": [ { "in": "query", "name": "pagination[per_page]", "schema": { "maximum": 200, "minimum": 1, "type": [ "integer", "null" ] } }, { "in": "query", "name": "pagination[rowsPerPage]", "schema": { "maximum": 200, "minimum": 1, "type": [ "integer", "null" ] } }, { "in": "query", "name": "pagination[page]", "schema": { "minimum": 1, "type": "integer" } }, { "in": "query", "name": "filter", "schema": { "type": [ "string", "null" ] } }, { "in": "query", "name": "type", "schema": { "enum": [ "email", "domain" ], "type": [ "string", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": [], "type": "array" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" }, "422": { "$ref": "#/components/responses/ValidationException" } }, "security": [ { "workspaceApiKey": [ "subscribers:read" ] }, { "oauth2": [ "subscribers:read" ] } ], "summary": "List subscribers", "tags": [ "Subscribers" ], "x-plan-features": [], "x-scopes": [ "subscribers:read" ] }, "post": { "description": "Grants a reader access to a gated flipbook.", "operationId": "api.v1.subscribers.store", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceSubscriberRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "" }, "422": { "$ref": "#/components/responses/ValidationException" } }, "security": [ { "workspaceApiKey": [ "subscribers:write" ] }, { "oauth2": [ "subscribers:write" ] } ], "summary": "Create a subscriber", "tags": [ "Subscribers" ], "x-plan-features": [], "x-scopes": [ "subscribers:write" ] } }, "/templates": { "get": { "description": "Returns the catalog templates available to the workspace.", "operationId": "api.v1.templates.index", "parameters": [ { "in": "query", "name": "type", "schema": { "maxLength": 64, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/CatalogTemplateResource" }, "type": "array" }, "meta": { "properties": { "default_template_id": { "type": "string" }, "default_template_source": { "const": "catalog-render-fallback", "type": "string" } }, "required": [ "default_template_id", "default_template_source" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" }, "422": { "$ref": "#/components/responses/ValidationException" } }, "security": [ { "workspaceApiKey": [ "catalogs:read" ] }, { "oauth2": [ "catalogs:read" ] } ], "summary": "List catalog templates", "tags": [ "Catalogs" ], "x-plan-features": [], "x-scopes": [ "catalogs:read" ] } }, "/toggle-take-over-branding": { "post": { "description": "Turns workspace branding takeover on or off for public flipbook pages.", "operationId": "api.v1.brands.toggle-take-over-branding", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "brand": { "$ref": "#/components/schemas/BrandResource" } }, "required": [ "brand" ], "type": "object" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "items": [], "type": "array" } }, "required": [ "error" ], "type": "object" } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "items": [], "type": "array" } }, "required": [ "error" ], "type": "object" } } }, "description": "" } }, "security": [ { "workspaceApiKey": [ "brand:write" ] }, { "oauth2": [ "brand:write" ] } ], "summary": "Toggle branding takeover", "tags": [ "Brand" ], "x-plan-features": [], "x-scopes": [ "brand:write" ] } }, "/webhook-subscriptions": { "get": { "description": "Returns the workspace webhook subscriptions and their event filters.", "operationId": "api.v1.webhook-subscriptions.index", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "created_at": { "type": "string" }, "deliveries_count": { "type": "integer" }, "event_types": { "items": [], "type": "array" }, "filters": { "items": [], "type": "array" }, "has_signing_secret": { "type": "boolean" }, "id": { "type": "integer" }, "is_active": { "type": "boolean" }, "name": { "type": "string" }, "provider": { "type": "string" }, "target_url": { "type": "string" }, "updated_at": { "type": "string" }, "workspace_id": { "type": "integer" } }, "required": [ "id", "workspace_id", "name", "provider", "target_url", "is_active", "event_types", "filters", "has_signing_secret", "deliveries_count", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" } }, "security": [ { "workspaceApiKey": [ "webhooks:read" ] }, { "oauth2": [ "webhooks:read" ] } ], "summary": "List webhook subscriptions", "tags": [ "Webhooks" ], "x-plan-features": [], "x-scopes": [ "webhooks:read" ] }, "post": { "description": "Subscribes an endpoint to one or more analytics events.", "operationId": "api.v1.webhook-subscriptions.store", "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "created_at": { "type": "string" }, "deliveries_count": { "type": "integer" }, "event_types": { "items": [], "type": "array" }, "filters": { "items": [], "type": "array" }, "has_signing_secret": { "type": "boolean" }, "id": { "type": "integer" }, "is_active": { "type": "boolean" }, "name": { "type": "string" }, "provider": { "type": "string" }, "target_url": { "type": "string" }, "updated_at": { "type": "string" }, "workspace_id": { "type": "integer" } }, "required": [ "id", "workspace_id", "name", "provider", "target_url", "is_active", "event_types", "filters", "has_signing_secret", "deliveries_count", "created_at", "updated_at" ], "type": "object" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" } }, "security": [ { "workspaceApiKey": [ "webhooks:write" ] }, { "oauth2": [ "webhooks:write" ] } ], "summary": "Create a webhook subscription", "tags": [ "Webhooks" ], "x-plan-features": [], "x-scopes": [ "webhooks:write" ] } }, "/webhook-subscriptions/{subscription}": { "delete": { "description": "Removes a subscription while preserving its delivery history.", "operationId": "api.v1.webhook-subscriptions.destroy", "parameters": [ { "description": "The subscription ID", "in": "path", "name": "subscription", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" } }, "security": [ { "workspaceApiKey": [ "webhooks:write" ] }, { "oauth2": [ "webhooks:write" ] } ], "summary": "Delete a webhook subscription", "tags": [ "Webhooks" ], "x-plan-features": [], "x-scopes": [ "webhooks:write" ] }, "put": { "description": "Changes a subscription target URL or event list.", "operationId": "api.v1.webhook-subscriptions.update", "parameters": [ { "description": "The subscription ID", "in": "path", "name": "subscription", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "created_at": { "type": "string" }, "deliveries_count": { "type": "integer" }, "event_types": { "items": [], "type": "array" }, "filters": { "items": [], "type": "array" }, "has_signing_secret": { "type": "boolean" }, "id": { "type": "integer" }, "is_active": { "type": "boolean" }, "name": { "type": "string" }, "provider": { "type": "string" }, "target_url": { "type": "string" }, "updated_at": { "type": "string" }, "workspace_id": { "type": "integer" } }, "required": [ "id", "workspace_id", "name", "provider", "target_url", "is_active", "event_types", "filters", "has_signing_secret", "deliveries_count", "created_at", "updated_at" ], "type": "object" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" } }, "security": [ { "workspaceApiKey": [ "webhooks:write" ] }, { "oauth2": [ "webhooks:write" ] } ], "summary": "Update a webhook subscription", "tags": [ "Webhooks" ], "x-plan-features": [], "x-scopes": [ "webhooks:write" ] } }, "/webhook-subscriptions/{subscription}/deliveries": { "get": { "description": "Returns recent delivery attempts and response statuses.", "operationId": "api.v1.webhook-subscriptions.deliveries", "parameters": [ { "description": "The subscription ID", "in": "path", "name": "subscription", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "attempts": { "type": "integer" }, "created_at": { "type": "string" }, "delivered_at": { "type": "string" }, "error_message": { "type": [ "string", "null" ] }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "id": { "type": "integer" }, "payload": { "items": [], "type": "array" }, "response_body": { "type": [ "string", "null" ] }, "response_status": { "type": [ "integer", "null" ] }, "status": { "type": "string" }, "subscription_id": { "type": "integer" }, "updated_at": { "type": "string" } }, "required": [ "id", "subscription_id", "event_id", "event_type", "status", "attempts", "response_status", "response_body", "error_message", "payload", "delivered_at", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" } }, "security": [ { "workspaceApiKey": [ "webhooks:read" ] }, { "oauth2": [ "webhooks:read" ] } ], "summary": "List webhook deliveries", "tags": [ "Webhooks" ], "x-plan-features": [], "x-scopes": [ "webhooks:read" ] } }, "/webhook-subscriptions/{subscription}/test": { "post": { "description": "Sends a test delivery to a subscription endpoint.", "operationId": "api.v1.webhook-subscriptions.test", "parameters": [ { "description": "The subscription ID", "in": "path", "name": "subscription", "required": true, "schema": { "type": "integer" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "attempts": { "type": "integer" }, "created_at": { "type": "string" }, "delivered_at": { "type": "string" }, "error_message": { "type": [ "string", "null" ] }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "id": { "type": "integer" }, "payload": { "items": [], "type": "array" }, "response_body": { "type": [ "string", "null" ] }, "response_status": { "type": [ "integer", "null" ] }, "status": { "type": "string" }, "subscription_id": { "type": "integer" }, "updated_at": { "type": "string" } }, "required": [ "id", "subscription_id", "event_id", "event_type", "status", "attempts", "response_status", "response_body", "error_message", "payload", "delivered_at", "created_at", "updated_at" ], "type": "object" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" } }, "security": [ { "workspaceApiKey": [ "webhooks:write" ] }, { "oauth2": [ "webhooks:write" ] } ], "summary": "Test a webhook subscription", "tags": [ "Webhooks" ], "x-plan-features": [], "x-scopes": [ "webhooks:write" ] } }, "/webhooks": { "post": { "description": "Dispatches a sample event to a URL so you can verify a webhook endpoint.", "operationId": "api.v1.webhooks", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerWebhookRequest" } } } }, "responses": { "202": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "event": { "anyOf": [ { "type": "string" }, { "enum": [ "subscriber.added" ], "type": "string" } ] }, "message": { "const": "Webhook event dispatched.", "type": "string" }, "payload": { "items": [], "type": "array" }, "target_url": { "type": "string" } }, "required": [ "message", "event", "target_url", "payload" ], "type": "object" }, "meta": { "type": "string" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" }, "422": { "$ref": "#/components/responses/ValidationException" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "items": [], "type": "array" } }, "required": [ "error" ], "type": "object" } } }, "description": "" } }, "security": [ { "workspaceApiKey": [ "webhooks:write" ] }, { "oauth2": [ "webhooks:write" ] } ], "summary": "Send a sample webhook", "tags": [ "Webhooks" ], "x-plan-features": [], "x-scopes": [ "webhooks:write" ] } } }, "security": [ { "workspaceApiKey": [] }, { "oauth2": [] } ], "servers": [ { "description": "Production", "url": "https://app.flipbooker.com/api/v1" } ] }