{ "openapi": "3.1.0", "info": { "title": "kustos.app API Reference", "version": "1.0.0", "description": "## kustos.app REST API \u2014 v1\n\nManage QR codes, short links, change requests and governance workflows via the kustos\n**Change Control** layer \u2014 protecting already-printed physical assets from unauthorised redirects.\n\n### Authentication\nEvery request must carry a Bearer token in the `Authorization` header:\n```\nAuthorization: Bearer \n```\nGenerate your token on your **Profile \u2192 API Keys** page.\n\n### Rate limiting\nThe API enforces **60 requests per minute** per token (HTTP 429 when exceeded).\n\n### Change Control (Governance)\nWhen a workspace collaborator updates the destination URL of a short link or QR code,\nthe change is queued as a `AssetChangeRequest` with status `pending` and the owner receives\na HTTP 202 response. The workspace owner must explicitly **approve** or **reject** the request\nbefore the destination changes \u2014 protecting already-printed physical assets from unauthorised\nredirects.\n\n### Error codes\n| HTTP | Code | Meaning |\n|------|------|---------|\n| 401 | \u2014 | Missing or invalid Bearer token |\n| 403 | \u2014 | Forbidden (not your resource) |\n| 422 | `limit_reached` | Plan resource limit reached |\n| 422 | `unsafe_url` | Destination URL flagged as unsafe |\n| 422 | `pending_request_exists` | A pending change request already exists |\n| 423 | `asset_frozen` | Asset is frozen \u2014 contact workspace owner |\n| 429 | \u2014 | Rate limit exceeded (60 req\/min) |" }, "servers": [ { "url": "https:\/\/kustos.app\/api\/v1" } ], "tags": [ { "name": "Auth", "description": "Authenticated user info" }, { "name": "Short Links", "description": "Create, update, delete and get stats for short links" }, { "name": "QR Codes", "description": "Create, update, delete and get stats for QR codes" }, { "name": "Governance", "description": "Change Control workflow \u2014 approve or reject pending destination changes on physical assets before they go live" }, { "name": "Workspace", "description": "Workspace metadata, billing invoices and resource usage" }, { "name": "Workspace Members", "description": "Invite and manage workspace team members" }, { "name": "Monetization", "description": "Link monetization stats, click breakdown and payout requests" }, { "name": "Modules", "description": "Digital products, bookings and courses (plan-gated)" } ], "security": [ { "BearerToken": [] } ], "paths": { "\/ai-pipeline\/blog\/draft": { "post": { "operationId": "ai-pipeline.blog.draft", "tags": [ "AiPipelineBlog" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "pipeline_run_id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "maxLength": 255 }, "slug": { "type": [ "string", "null" ], "pattern": "^[a-z0-9\\-]+$", "maxLength": 255 }, "excerpt": { "type": [ "string", "null" ], "maxLength": 500 }, "content": { "type": "string", "maxLength": 200000 }, "format": { "type": [ "string", "null" ], "enum": [ "markdown", "html", "editorjs" ] }, "category": { "type": [ "string", "null" ], "maxLength": 100 }, "language": { "type": [ "string", "null" ], "maxLength": 8 }, "image_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 1000 }, "target_keyword": { "type": [ "string", "null" ], "maxLength": 255 }, "seo_title": { "type": [ "string", "null" ], "maxLength": 70 }, "seo_description": { "type": [ "string", "null" ], "maxLength": 160 }, "outline": { "type": [ "array", "null" ], "items": { "type": "string" } }, "internal_links_suggestions": { "type": [ "array", "null" ], "items": { "type": "string" } }, "schema_jsonld": { "type": [ "array", "null" ], "items": { "type": "string" } }, "research_data": { "type": [ "array", "null" ], "items": { "type": "string" } }, "ai_model": { "type": [ "string", "null" ], "maxLength": 100 }, "author_user_id": { "type": [ "integer", "null" ] }, "secondary_keywords": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 255 }, "maxItems": 20 } }, "required": [ "pipeline_run_id", "title", "content" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "string" } } } }, "409": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "This pipeline_run_id is already published; refusing to overwrite" }, "id": { "type": "integer" }, "slug": { "type": "string" } }, "required": [ "error", "id", "slug" ] } } } }, "429": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Daily AI draft quota reached" }, "daily_quota": { "type": "integer" }, "today_count": { "type": "integer", "minimum": 0 } }, "required": [ "error", "daily_quota", "today_count" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/me": { "get": { "operationId": "apiMe", "description": "Returns the identity and plan information for the token owner.", "summary": "Get authenticated user", "tags": [ "ApiMe" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "plan": { "type": "string" }, "short_link_limit": { "type": [ "integer", "null" ] }, "short_links_count": { "type": "integer", "minimum": 0 } }, "required": [ "id", "name", "email", "plan", "short_link_limit", "short_links_count" ] } } } } } } }, "\/audit-exports\/{id}\/verify": { "post": { "operationId": "audit-exports.verify", "tags": [ "AuditExportApi" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "signature": { "type": "string", "minLength": 64, "maxLength": 64 } }, "required": [ "signature" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "signed_at": { "type": "string" }, "period_start": { "type": "string" }, "period_end": { "type": "string" }, "scope_summary": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "format": { "type": "string" } }, "required": [ "valid", "signed_at", "period_start", "period_end", "scope_summary", "format" ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "error": { "type": "string", "const": "Export not found" } }, "required": [ "valid", "error" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/change-requests": { "get": { "operationId": "change-requests.index", "description": "Returns change requests visible to the authenticated user \u2014 either requests on assets they own,\nor requests they submitted as a collaborator. Filter by `status` to see pending, approved or\nrejected changes.", "summary": "List change requests", "tags": [ "ChangeRequestApi" ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "default": "pending" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/LengthAwarePaginator" }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" } }, "required": [ "current_page", "per_page", "total", "last_page" ] } }, "required": [ "data", "meta" ] } } } } } } }, "\/change-requests\/{changeRequest}": { "get": { "operationId": "change-requests.show", "description": "Returns the full detail of a single change request. Accessible by the asset owner or the\ncollaborator who submitted the request.", "summary": "Get a change request", "tags": [ "ChangeRequestApi" ], "parameters": [ { "name": "changeRequest", "in": "path", "required": true, "description": "The change request ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string" }, "source": { "type": "string" }, "field": { "type": "string" }, "old_value": { "type": "string" }, "new_value": { "type": "string" }, "asset_type": { "type": [ "string", "null" ] }, "asset_id": { "type": "integer" }, "requested_by": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, "decided_by": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, "decided_at": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "status", "source", "field", "old_value", "new_value", "asset_type", "asset_id", "requested_by", "decided_by", "decided_at", "created_at" ] } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/change-requests\/{changeRequest}\/approve": { "post": { "operationId": "change-requests.approve", "description": "**Workspace owner only.** Applies the queued destination change to the physical asset\nimmediately and marks the request as `approved`. A webhook is dispatched to all configured\nendpoints on `change_request.approved`.\n\nThis endpoint is the heart of the Change Control governance layer \u2014 no destination on a\nprinted QR code or short link can change without an explicit approval.", "summary": "Approve a change request", "tags": [ "ChangeRequestApi" ], "parameters": [ { "name": "changeRequest", "in": "path", "required": true, "description": "The change request ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "integer", "const": 200 } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/change-requests\/{changeRequest}\/reject": { "post": { "operationId": "change-requests.reject", "description": "**Workspace owner only.** Rejects the queued destination change \u2014 the asset keeps its\ncurrent destination. A webhook is dispatched to all configured endpoints on\n`change_request.rejected`.", "summary": "Reject a change request", "tags": [ "ChangeRequestApi" ], "parameters": [ { "name": "changeRequest", "in": "path", "required": true, "description": "The change request ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "integer", "const": 200 } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/data-subjects\/erasure-request": { "post": { "operationId": "data-subjects.erasure-request", "tags": [ "DataSubjectApi" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "subject_email": { "type": "string", "format": "email", "maxLength": 255 }, "reason": { "type": [ "string", "null" ], "maxLength": 2000 }, "workspace_id": { "type": "integer" } }, "required": [ "subject_email", "workspace_id" ] } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string" }, "auto_approve_at": { "type": "string" } }, "required": [ "id", "status", "auto_approve_at" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/deferred\/track": { "post": { "operationId": "deferred.track", "summary": "Called by the browser JS at short-link click time.\nStores a fingerprint \u2192 target_url mapping with 24h TTL", "tags": [ "DeferredDeeplink" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "fingerprint_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "target_url": { "type": "string", "format": "uri", "maxLength": 2048 }, "accept_language": { "type": [ "string", "null" ], "maxLength": 64 }, "screen_info": { "type": [ "string", "null" ], "maxLength": 64 } }, "required": [ "fingerprint_hash", "target_url" ] } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/deferred\/match": { "post": { "operationId": "deferred.match", "summary": "Called by the native app on first launch after install.\nReturns the deeplink target if a matching fingerprint is found within 24h", "tags": [ "DeferredDeeplink" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "fingerprint_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "fingerprint_hash" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "deeplink": { "type": "string" } }, "required": [ "deeplink" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/qr-codes": { "get": { "operationId": "qrCodeApi.index", "description": "Returns a paginated list of your QR codes ordered by creation date (newest first).", "summary": "List QR codes", "tags": [ "QrCodeApi" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/LengthAwarePaginator" }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" } }, "required": [ "current_page", "per_page", "total", "last_page" ] } }, "required": [ "data", "meta" ] } } } } } }, "post": { "operationId": "qrCodeApi.store", "description": "Creates a new dynamic QR code. The `data` field holds the destination \u2014 it can be a URL,\nvCard, plain text, or any other QR-encodable payload. Dangerous URI schemes (`javascript:`,\n`data:`, `vbscript:`) are rejected with HTTP 422.", "summary": "Create a QR code", "tags": [ "QrCodeApi" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "maxLength": 50 }, "data": { "type": "string", "maxLength": 2048 }, "label": { "type": [ "string", "null" ], "maxLength": 255 }, "fg_color": { "type": [ "string", "null" ], "maxLength": 20 }, "bg_color": { "type": [ "string", "null" ], "maxLength": 20 }, "dot_style": { "type": [ "string", "null" ], "maxLength": 30 }, "corner_style": { "type": [ "string", "null" ], "maxLength": 30 }, "corner_dot_style": { "type": [ "string", "null" ], "maxLength": 30 }, "logo_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 512 } }, "required": [ "type", "data" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "integer", "const": 201 } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/qr-codes\/{id}": { "patch": { "operationId": "qrCodeApi.update", "description": "Partially updates a QR code. When a **workspace collaborator** (non-owner) changes the\n`destination` field, the change is queued for approval (HTTP 202) and the owner must approve\nit via `POST \/api\/v1\/change-requests\/{id}\/approve`. Directly updating other style fields\n(colors, logo, dot style) is always allowed.\n\nReturns HTTP 423 if the asset is frozen.", "summary": "Update a QR code", "tags": [ "QrCodeApi" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "destination": { "type": "string", "maxLength": 2048 }, "label": { "type": [ "string", "null" ], "maxLength": 255 }, "fg_color": { "type": [ "string", "null" ], "maxLength": 20 }, "bg_color": { "type": [ "string", "null" ], "maxLength": 20 }, "dot_style": { "type": [ "string", "null" ], "maxLength": 30 }, "corner_style": { "type": [ "string", "null" ], "maxLength": 30 }, "corner_dot_style": { "type": [ "string", "null" ], "maxLength": 30 }, "eye_frame_color": { "type": [ "string", "null" ], "maxLength": 20 }, "eye_dot_color": { "type": [ "string", "null" ], "maxLength": 20 }, "gradient_color": { "type": [ "string", "null" ], "maxLength": 20 }, "gradient_type": { "type": [ "string", "null" ], "maxLength": 30 }, "gradient_angle": { "type": [ "integer", "null" ] }, "error_correction": { "type": [ "string", "null" ], "maxLength": 10 }, "qr_margin": { "type": [ "integer", "null" ] }, "logo_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 512 }, "logo_scale": { "type": [ "number", "null" ] }, "logo_hide_bg_dots": { "type": "boolean" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "fallback_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 } } } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "integer", "const": 200 } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "delete": { "operationId": "qrCodeApi.destroy", "description": "Permanently deletes a QR code you own. Returns 204 No Content on success.", "summary": "Delete a QR code", "tags": [ "QrCodeApi" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "integer", "const": 204 } } } } } } }, "\/qr-codes\/{id}\/stats": { "get": { "operationId": "qrCodeApi.stats", "description": "Returns scan analytics broken down by day, country, city and device. Defaults to the last 30 days.", "summary": "Get QR code scan stats", "tags": [ "QrCodeApi" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "start_date", "in": "query", "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "label": { "type": [ "string", "null" ] }, "total_scans": { "type": "integer", "minimum": 0 }, "period": { "type": "object", "properties": { "start_date": { "type": "string" }, "end_date": { "type": "string" } }, "required": [ "start_date", "end_date" ] }, "daily": { "type": "string" }, "by_country": { "type": "string" }, "by_city": { "type": "string" }, "by_device": { "type": "string" } }, "required": [ "id", "label", "total_scans", "period", "daily", "by_country", "by_city", "by_device" ] } }, "required": [ "data" ] } } } } } } }, "\/short-links": { "get": { "operationId": "shortLinkApi.index", "description": "Returns a paginated list of your short links, ordered by creation date (newest first).", "summary": "List short links", "tags": [ "ShortLinkApi" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/LengthAwarePaginator" }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" } }, "required": [ "current_page", "per_page", "total", "last_page" ] } }, "required": [ "data", "meta" ] } } } } } }, "post": { "operationId": "shortLinkApi.store", "description": "Creates a new short link. A custom `slug` requires a Pro plan.\nThe destination is validated against the URL safety service before creation.", "summary": "Create a short link", "tags": [ "ShortLinkApi" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "destination_url": { "type": "string", "format": "uri", "maxLength": 2048 }, "type": { "type": [ "string", "null" ], "enum": [ "short_link", "onelink", "deeplink" ] }, "title": { "type": [ "string", "null" ], "maxLength": 255 }, "slug": { "type": [ "string", "null" ], "maxLength": 50 }, "target_url_mobile": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "target_url_tablet": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "target_url_desktop": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "app_label": { "type": [ "string", "null" ], "maxLength": 100 }, "app_android_package": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z][a-zA-Z0-9_.]*$", "maxLength": 255 }, "app_ios_itunes_id": { "type": [ "string", "null" ], "pattern": "^\\d+$", "maxLength": 20 }, "app_scheme": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z][a-zA-Z0-9+\\-.]*$", "maxLength": 50 }, "utm_source": { "type": [ "string", "null" ], "maxLength": 100 }, "utm_medium": { "type": [ "string", "null" ], "maxLength": 100 }, "utm_campaign": { "type": [ "string", "null" ], "maxLength": 100 }, "utm_term": { "type": [ "string", "null" ], "maxLength": 100 }, "utm_content": { "type": [ "string", "null" ], "maxLength": 100 }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "fallback_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 } }, "required": [ "destination_url" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "integer", "const": 201 } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/short-links\/{slug}": { "patch": { "operationId": "shortLinkApi.update", "description": "Partially updates a short link. When a **workspace collaborator** (non-owner) changes\n`destination_url`, the change is not applied immediately \u2014 a `AssetChangeRequest` is created\nwith status `pending` and HTTP 202 is returned. The workspace **owner** must approve it via\n`POST \/api\/v1\/change-requests\/{id}\/approve`.\n\nReturns HTTP 423 if the asset is frozen.", "summary": "Update a short link", "tags": [ "ShortLinkApi" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "destination_url": { "type": "string", "format": "uri", "maxLength": 2048 }, "title": { "type": [ "string", "null" ], "maxLength": 255 }, "is_active": { "type": "boolean" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "fallback_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "target_url_mobile": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "target_url_tablet": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "target_url_desktop": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "app_label": { "type": [ "string", "null" ], "maxLength": 100 }, "app_android_package": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z][a-zA-Z0-9_.]*$", "maxLength": 255 }, "app_ios_itunes_id": { "type": [ "string", "null" ], "pattern": "^\\d+$", "maxLength": 20 }, "app_scheme": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z][a-zA-Z0-9+\\-.]*$", "maxLength": 50 } } } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "integer", "const": 200 } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "delete": { "operationId": "shortLinkApi.destroy", "description": "Permanently deletes a short link you own. Returns 204 No Content on success.", "summary": "Delete a short link", "tags": [ "ShortLinkApi" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "integer", "const": 204 } } } } } } }, "\/short-links\/{slug}\/stats": { "get": { "operationId": "shortLinkApi.stats", "description": "Returns click analytics for the given short link broken down by day, country, city, device\nand browser. Defaults to the last 30 days.", "summary": "Get short link stats", "tags": [ "ShortLinkApi" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "slug": { "type": "string" }, "total_clicks": { "type": "integer" }, "period": { "type": "object", "properties": { "start_date": { "type": "string" }, "end_date": { "type": "string" } }, "required": [ "start_date", "end_date" ] }, "daily": { "type": "string" }, "by_country": { "type": "string" }, "by_city": { "type": "string" }, "by_device": { "type": "string" }, "by_browser": { "type": "string" } }, "required": [ "slug", "total_clicks", "period", "daily", "by_country", "by_city", "by_device", "by_browser" ] } }, "required": [ "data" ] } } } } } } }, "\/short-links\/{slug}\/leads": { "get": { "operationId": "shortLinkApi.leads", "description": "Returns a paginated list of email leads collected via the squeeze page attached to this link.", "summary": "Get squeeze-page leads", "tags": [ "ShortLinkApi" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/LengthAwarePaginator" }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" } }, "required": [ "current_page", "per_page", "total", "last_page" ] } }, "required": [ "data", "meta" ] } } } } } } }, "\/workspace": { "get": { "operationId": "workspace.index", "description": "Returns the workspace (account) metadata including the active plan, seat usage, and creation date.", "summary": "Get workspace info", "tags": [ "Workspace" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "plan": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "max_seats": { "type": "string" }, "seat_price": { "type": "string" } }, "required": [ "name", "max_seats", "seat_price" ] }, "seats": { "type": "object", "properties": { "used": { "type": "string" }, "max": { "type": "string" } }, "required": [ "used", "max" ] }, "created_at": { "type": "string" } }, "required": [ "id", "name", "slug", "plan", "seats", "created_at" ] } }, "required": [ "data" ] } } } }, "403": { "description": "An error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "example": "" } }, "required": [ "message" ] } } } } } } }, "\/workspace\/invoices": { "get": { "operationId": "workspace.invoices", "description": "Returns a paginated list of billing invoices for the workspace, ordered by date descending.\nEach invoice includes the payment gateway reference and amounts.", "summary": "List billing invoices", "tags": [ "Workspace" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/LengthAwarePaginator" }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "total" ] } }, "required": [ "data", "meta" ] } } } }, "403": { "description": "An error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "example": "" } }, "required": [ "message" ] } } } } } } }, "\/workspace\/usage": { "get": { "operationId": "workspace.usage", "description": "products, bookings, courses, and active members) for the workspace.", "summary": "Get resource usage", "tags": [ "Workspace" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "short_links": { "type": "integer", "minimum": 0 }, "qr_codes": { "type": "integer", "minimum": 0 }, "digital_products": { "type": "string" }, "bookings": { "type": "string" }, "courses": { "type": "string" }, "members": { "type": "string" } }, "required": [ "short_links", "qr_codes", "digital_products", "bookings", "courses", "members" ] } }, "required": [ "data" ] } } } }, "403": { "description": "An error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "example": "" } }, "required": [ "message" ] } } } } } } }, "\/workspace\/members": { "get": { "operationId": "workspace.members.index", "description": "Returns all active workspace members including their role, status and linked user profile.", "summary": "List workspace members", "tags": [ "WorkspaceMember" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ] } } } }, "403": { "description": "An error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "example": "" } }, "required": [ "message" ] } } } } } } }, "\/workspace\/members\/invite": { "post": { "operationId": "workspace.members.invite", "description": "Sends an email invitation to join the workspace. **Admin or owner only.**\nEnforces the seat limit defined by your plan.", "summary": "Invite a workspace member", "tags": [ "WorkspaceMember" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255 }, "role": { "type": "string", "enum": [ "admin", "member", "viewer" ] } }, "required": [ "email", "role" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "integer", "const": 201 } } } }, "403": { "description": "An error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "example": "" } }, "required": [ "message" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/workspace\/members\/{member}": { "patch": { "operationId": "workspace.members.update-role", "description": "Changes the role of an existing workspace member. **Owner only.**\nCannot change your own role.", "summary": "Update a member's role", "tags": [ "WorkspaceMember" ], "parameters": [ { "name": "member", "in": "path", "required": true, "description": "The member ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "admin", "member", "viewer" ] } }, "required": [ "role" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "integer", "const": 200 } } } }, "403": { "description": "An error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "example": "" } }, "required": [ "message" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } }, "delete": { "operationId": "workspace.members.remove", "description": "Revokes workspace access for the given member. **Admin or owner only.** Cannot remove the owner.", "summary": "Remove a workspace member", "tags": [ "WorkspaceMember" ], "parameters": [ { "name": "member", "in": "path", "required": true, "description": "The member ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "integer", "const": 204 } } } }, "403": { "description": "An error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "example": "" } }, "required": [ "message" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } } }, "components": { "securitySchemes": { "BearerToken": { "type": "http", "description": "Pass your API token in the Authorization header: `Bearer `", "scheme": "bearer", "bearerFormat": "API token" } }, "schemas": { "LengthAwarePaginator": { "type": "array", "items": {}, "title": "LengthAwarePaginator" } }, "responses": { "ValidationException": { "description": "Validation error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "ModelNotFoundException": { "description": "Not found", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } } } } }