{ "openapi": "3.1.0", "info": { "title": "Hoko API", "version": "0.0.1", "description": "REST API for creating short links, managing campaign metadata, reading analytics, and recording lead and sale conversions. Successful responses return the raw documented payload. Failures use non-2xx HTTP status codes and an error object. Unknown request object properties are ignored." }, "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "servers": [ { "url": "https://hoko.to", "description": "Production" } ], "tags": [ { "name": "Links" }, { "name": "Collections" }, { "name": "Tags" }, { "name": "Partners" }, { "name": "Customers" }, { "name": "Analytics" }, { "name": "Conversion Tracking" } ], "paths": { "/api/links": { "get": { "tags": [ "Links" ], "operationId": "listLinks", "summary": "List links", "description": "Retrieves links by ID, external ID, tenant ID, or partner ID. Requires the `linksRead` scope.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Filter by resource ID." }, { "name": "externalId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by external ID." }, { "name": "tenantId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by tenant ID." }, { "name": "partnerId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Filter by partner ID." }, { "name": "take", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 50 }, "description": "Number of records to return." }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of records to skip." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort order." } ], "responses": { "200": { "description": "Links returned.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "array", "maxItems": 10000, "items": { "$ref": "#/components/schemas/Link" } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "tags": [ "Links" ], "operationId": "createLinks", "summary": "Create links", "description": "Creates one or more links. Requires the `linksWrite` scope.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "maxItems": 10000, "items": { "$ref": "#/components/schemas/LinkCreate" }, "minItems": 1 } } } }, "responses": { "201": { "description": "Links created.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "array", "maxItems": 10000, "items": { "$ref": "#/components/schemas/Link" } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "put": { "tags": [ "Links" ], "operationId": "upsertLinks", "summary": "Create or update links", "description": "Entries with an `id` are updated; entries without an `id` are inserted. Requires the `linksWrite` scope.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "maxItems": 10000, "items": { "$ref": "#/components/schemas/LinkUpsert" }, "minItems": 1 } } } }, "responses": { "200": { "description": "Links upserted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "array", "maxItems": 10000, "items": { "$ref": "#/components/schemas/Link" } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "tags": [ "Links" ], "operationId": "deleteLinks", "summary": "Delete links", "description": "Soft-deletes one or more links by ID. Requires the `linksWrite` scope.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "maxItems": 10000, "items": { "type": "string", "format": "uuid" }, "minItems": 1 } } } }, "responses": { "200": { "description": "Links deleted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "deletedIds" ], "properties": { "deletedIds": { "type": "array", "maxItems": 10000, "items": { "type": "string", "format": "uuid" } } } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/collections": { "get": { "tags": [ "Collections" ], "operationId": "listCollections", "summary": "List collections", "description": "Requires the `collectionsRead` scope.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Filter by resource ID." }, { "name": "take", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 50 }, "description": "Number of records to return." }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of records to skip." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort order." } ], "responses": { "200": { "description": "Collections returned.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "array", "maxItems": 10000, "items": { "$ref": "#/components/schemas/Collection" } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "tags": [ "Collections" ], "operationId": "createCollections", "summary": "Create collections", "description": "Creates one or more records. Requires the `collectionsWrite` scope.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "maxItems": 10000, "items": { "$ref": "#/components/schemas/CollectionCreate" }, "minItems": 1 } } } }, "responses": { "201": { "description": "Collections created.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "array", "maxItems": 10000, "items": { "$ref": "#/components/schemas/Collection" } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "put": { "tags": [ "Collections" ], "operationId": "upsertCollections", "summary": "Create or update collections", "description": "Entries with an `id` are updated; entries without an `id` are inserted. Requires the `collectionsWrite` scope.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "maxItems": 10000, "items": { "$ref": "#/components/schemas/CollectionUpsert" }, "minItems": 1 } } } }, "responses": { "200": { "description": "Collections upserted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "array", "maxItems": 10000, "items": { "$ref": "#/components/schemas/Collection" } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "tags": [ "Collections" ], "operationId": "deleteCollections", "summary": "Delete collections", "description": "Soft-deletes one or more records by ID. Requires the `collectionsWrite` scope.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "maxItems": 10000, "items": { "type": "string", "format": "uuid" }, "minItems": 1 } } } }, "responses": { "200": { "description": "Collections deleted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "deletedIds" ], "properties": { "deletedIds": { "type": "array", "maxItems": 10000, "items": { "type": "string", "format": "uuid" } } } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/tags": { "get": { "tags": [ "Tags" ], "operationId": "listTags", "summary": "List tags", "description": "Requires the `tagsRead` scope.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Filter by resource ID." }, { "name": "take", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 50 }, "description": "Number of records to return." }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of records to skip." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort order." } ], "responses": { "200": { "description": "Tags returned.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "array", "maxItems": 10000, "items": { "$ref": "#/components/schemas/Tag" } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "tags": [ "Tags" ], "operationId": "createTags", "summary": "Create tags", "description": "Creates one or more records. Requires the `tagsWrite` scope.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "maxItems": 10000, "items": { "$ref": "#/components/schemas/TagCreate" }, "minItems": 1 } } } }, "responses": { "201": { "description": "Tags created.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "array", "maxItems": 10000, "items": { "$ref": "#/components/schemas/Tag" } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "put": { "tags": [ "Tags" ], "operationId": "upsertTags", "summary": "Create or update tags", "description": "Entries with an `id` are updated; entries without an `id` are inserted. Requires the `tagsWrite` scope.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "maxItems": 10000, "items": { "$ref": "#/components/schemas/TagUpsert" }, "minItems": 1 } } } }, "responses": { "200": { "description": "Tags upserted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "array", "maxItems": 10000, "items": { "$ref": "#/components/schemas/Tag" } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "tags": [ "Tags" ], "operationId": "deleteTags", "summary": "Delete tags", "description": "Permanently deletes one or more tags by ID. Requires the `tagsWrite` scope.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "maxItems": 10000, "items": { "type": "string", "format": "uuid" }, "minItems": 1 } } } }, "responses": { "200": { "description": "Tags deleted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "deletedIds" ], "properties": { "deletedIds": { "type": "array", "maxItems": 10000, "items": { "type": "string", "format": "uuid" } } } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/partners": { "get": { "tags": [ "Partners" ], "operationId": "listPartners", "summary": "List partners", "description": "Requires the `partnersRead` scope.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Filter by resource ID." }, { "name": "take", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 50 }, "description": "Number of records to return." }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of records to skip." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort order." } ], "responses": { "200": { "description": "Partners returned.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "array", "maxItems": 10000, "items": { "$ref": "#/components/schemas/Partner" } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "tags": [ "Partners" ], "operationId": "createPartners", "summary": "Create partners", "description": "Creates one or more records. Requires the `partnersWrite` scope.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "maxItems": 10000, "items": { "$ref": "#/components/schemas/PartnerCreate" }, "minItems": 1 } } } }, "responses": { "201": { "description": "Partners created.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "array", "maxItems": 10000, "items": { "$ref": "#/components/schemas/Partner" } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "put": { "tags": [ "Partners" ], "operationId": "upsertPartners", "summary": "Create or update partners", "description": "Entries with an `id` are updated; entries without an `id` are inserted. Requires the `partnersWrite` scope.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "maxItems": 10000, "items": { "$ref": "#/components/schemas/PartnerUpsert" }, "minItems": 1 } } } }, "responses": { "200": { "description": "Partners upserted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "array", "maxItems": 10000, "items": { "$ref": "#/components/schemas/Partner" } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "tags": [ "Partners" ], "operationId": "deletePartners", "summary": "Delete partners", "description": "Soft-deletes one or more records by ID. Requires the `partnersWrite` scope.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "maxItems": 10000, "items": { "type": "string", "format": "uuid" }, "minItems": 1 } } } }, "responses": { "200": { "description": "Partners deleted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "deletedIds" ], "properties": { "deletedIds": { "type": "array", "maxItems": 10000, "items": { "type": "string", "format": "uuid" } } } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/customers": { "get": { "tags": [ "Customers" ], "operationId": "listCustomers", "summary": "List customers", "description": "Retrieves customers by ID or external ID. Requires the `customersRead` scope.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Filter by resource ID." }, { "name": "externalId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by customer external ID." }, { "name": "take", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 50 }, "description": "Number of records to return." }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of records to skip." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort order." } ], "responses": { "200": { "description": "Customers returned.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "array", "maxItems": 10000, "items": { "$ref": "#/components/schemas/Customer" } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "put": { "tags": [ "Customers" ], "operationId": "updateCustomers", "summary": "Update customers", "description": "Updates existing customers. Entries with an `id` update that customer. Entries without an `id` use `externalId` to find an existing customer. No customers are created. Requires the `customersWrite` scope.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "maxItems": 10000, "items": { "$ref": "#/components/schemas/CustomerUpdate" }, "minItems": 1 } } } }, "responses": { "200": { "description": "Customers updated.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "array", "maxItems": 10000, "items": { "$ref": "#/components/schemas/Customer" } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "tags": [ "Customers" ], "operationId": "deleteCustomers", "summary": "Delete customers", "description": "Soft-deletes one or more customers by ID. Requires the `customersWrite` scope.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "maxItems": 10000, "items": { "type": "string", "format": "uuid" }, "minItems": 1 } } } }, "responses": { "200": { "description": "Customers deleted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "deletedIds" ], "properties": { "deletedIds": { "type": "array", "maxItems": 10000, "items": { "type": "string", "format": "uuid" } } } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/analytics": { "get": { "tags": [ "Analytics" ], "operationId": "listClicks", "summary": "List click analytics", "description": "Retrieves click records by link, partner, or UTC date range. Results are limited to the authenticated workspace plan retention window and never include future clicks. Requires the `analyticsRead` scope.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "linkId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Filter by link ID." }, { "name": "partnerId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Filter by partner ID." }, { "name": "startDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$" }, "description": "Inclusive UTC ISO date-time lower bound. Use a trailing Z timestamp." }, { "name": "endDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$" }, "description": "Inclusive UTC ISO date-time upper bound. Use a trailing Z timestamp." }, { "name": "take", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 50 }, "description": "Number of records to return." }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of records to skip." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort order." } ], "responses": { "200": { "description": "Clicks returned.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "array", "maxItems": 10000, "items": { "$ref": "#/components/schemas/Click" } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/track/lead": { "post": { "tags": [ "Conversion Tracking" ], "operationId": "trackLead", "summary": "Track a lead conversion", "description": "Creates a lead event and upserts the customer. Requires the `conversionsWrite` scope.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadTrackRequest" } } } }, "responses": { "201": { "description": "Lead tracked.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadTrackResponse" } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/track/sale": { "post": { "tags": [ "Conversion Tracking" ], "operationId": "trackSale", "summary": "Track a sale conversion", "description": "Creates a sale event and upserts the customer. Requires the `conversionsWrite` scope.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaleTrackRequest" } } } }, "responses": { "201": { "description": "Sale tracked.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaleTrackResponse" } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Hoko API key. Send as `Authorization: Bearer `." } }, "headers": { "XRateLimitLimit": { "description": "Maximum requests allowed per minute for the workspace plan.", "schema": { "type": "integer" } }, "XRateLimitRemaining": { "description": "Requests remaining in the current rate-limit window.", "schema": { "type": "integer" } }, "XRateLimitReset": { "description": "Unix timestamp, in seconds, when the current window resets.", "schema": { "type": "integer" } } }, "schemas": { "LocalizedMessage": { "type": "object", "required": [ "en", "ar" ], "properties": { "en": { "type": "string" }, "ar": { "type": "string" } } }, "ApiError": { "type": "object", "required": [ "error" ], "properties": { "error": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/LocalizedMessage" } ] }, "missingScopes": { "type": "array", "maxItems": 10000, "items": { "type": "string" } }, "retryAfter": { "type": "integer", "minimum": 0 } } }, "Utm": { "type": "object", "properties": { "source": { "type": "string" }, "medium": { "type": "string" }, "campaign": { "type": "string" }, "term": { "type": "string" }, "content": { "type": "string" }, "referral": { "type": "string" } } }, "UtmCreate": { "type": "object", "properties": { "source": { "type": "string" }, "medium": { "type": "string" }, "campaign": { "type": "string" }, "term": { "type": "string" }, "content": { "type": "string" }, "referral": { "type": "string" } } }, "UtmUpdate": { "type": "object", "description": "UTM fields to update. Send null for an individual field to clear it.", "properties": { "source": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "medium": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "campaign": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "term": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "referral": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } } }, "GeoTargeting": { "type": "object", "description": "Country-code destination map. Use uppercase ISO 3166-1 alpha-2 keys such as SA or US. Geo targeting runs after iOS and Android checks.", "propertyNames": { "type": "string", "pattern": "^[A-Z]{2}$" }, "additionalProperties": { "type": "string", "format": "uri", "pattern": "^[Hh][Tt][Tt][Pp][Ss]://" } }, "Link": { "type": "object", "required": [ "id", "url", "shortUrl", "qrCode", "title", "description", "image", "utm", "expiresAt", "expiredUrl", "password", "cloaked", "ios", "android", "geo", "collectionId", "tagIds", "externalId", "tenantId", "partnerId", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri", "pattern": "^[Hh][Tt][Tt][Pp][Ss]://" }, "shortUrl": { "type": "string", "format": "uri", "pattern": "^[Hh][Tt][Tt][Pp][Ss]://" }, "qrCode": { "type": "string", "format": "uri", "pattern": "^[Hh][Tt][Tt][Pp][Ss]://" }, "title": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "oneOf": [ { "type": "string", "format": "uri", "pattern": "^[Hh][Tt][Tt][Pp][Ss]://" }, { "type": "null" } ] }, "utm": { "oneOf": [ { "$ref": "#/components/schemas/Utm" }, { "type": "null" } ] }, "expiresAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO date-time with timezone offset. When the current server time is later than this value, the link is expired." }, "expiredUrl": { "oneOf": [ { "type": "string", "format": "uri", "pattern": "^[Hh][Tt][Tt][Pp][Ss]://" }, { "type": "null" } ], "description": "Destination URL used after expiration. Expired links skip device and geo targeting." }, "password": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Password visitors must enter before Hoko resolves the final destination." }, "cloaked": { "type": "boolean", "description": "When true, Hoko renders the resolved destination in a full-page iframe. Create and update requests preflight the destination and return 400 when the current destination blocks iframe rendering." }, "ios": { "oneOf": [ { "type": "string", "format": "uri", "pattern": "^[Hh][Tt][Tt][Pp][Ss]://" }, { "type": "null" } ], "description": "iOS-specific destination selected from best-effort User-Agent detection. iOS and Android checks run before geo targeting." }, "android": { "oneOf": [ { "type": "string", "format": "uri", "pattern": "^[Hh][Tt][Tt][Pp][Ss]://" }, { "type": "null" } ], "description": "Android-specific destination selected from best-effort User-Agent detection. iOS and Android checks run before geo targeting." }, "geo": { "oneOf": [ { "$ref": "#/components/schemas/GeoTargeting" }, { "type": "null" } ], "description": "Country-code destination map. Use uppercase ISO 3166-1 alpha-2 keys such as SA or US. Geo targeting runs after iOS and Android checks." }, "collectionId": { "type": "string", "format": "uuid" }, "tagIds": { "type": "array", "maxItems": 10000, "items": { "type": "string", "format": "uuid" }, "description": "Existing tag IDs assigned to the link. Every tag ID must belong to the authenticated workspace." }, "externalId": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "tenantId": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "partnerId": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } } }, "LinkCreate": { "type": "object", "required": [ "url", "collectionId" ], "properties": { "url": { "type": "string", "format": "uri", "pattern": "^[Hh][Tt][Tt][Pp][Ss]://" }, "title": { "type": "string" }, "description": { "type": "string" }, "image": { "type": "string", "format": "uri", "pattern": "^[Hh][Tt][Tt][Pp][Ss]://" }, "utm": { "$ref": "#/components/schemas/UtmCreate" }, "expiresAt": { "type": "string", "format": "date-time", "description": "ISO date-time with timezone offset. When the current server time is later than this value, the link is expired." }, "expiredUrl": { "type": "string", "format": "uri", "pattern": "^[Hh][Tt][Tt][Pp][Ss]://", "description": "Destination URL used after expiration. Expired links skip device and geo targeting." }, "password": { "type": "string", "description": "Password visitors must enter before Hoko resolves the final destination." }, "cloaked": { "type": "boolean", "default": false, "description": "When true, Hoko renders the resolved destination in a full-page iframe. Create and update requests preflight the destination and return 400 when the current destination blocks iframe rendering." }, "ios": { "type": "string", "format": "uri", "pattern": "^[Hh][Tt][Tt][Pp][Ss]://", "description": "iOS-specific destination selected from best-effort User-Agent detection. iOS and Android checks run before geo targeting." }, "android": { "type": "string", "format": "uri", "pattern": "^[Hh][Tt][Tt][Pp][Ss]://", "description": "Android-specific destination selected from best-effort User-Agent detection. iOS and Android checks run before geo targeting." }, "geo": { "oneOf": [ { "$ref": "#/components/schemas/GeoTargeting" }, { "type": "null" } ], "description": "Country-code destination map. Use uppercase ISO 3166-1 alpha-2 keys such as SA or US. Geo targeting runs after iOS and Android checks. Send null or omit the field for no geo targeting." }, "collectionId": { "type": "string", "format": "uuid" }, "tagIds": { "type": "array", "maxItems": 10000, "items": { "type": "string", "format": "uuid" }, "description": "Existing tag IDs assigned to the link. Every tag ID must belong to the authenticated workspace." }, "externalId": { "type": "string" }, "tenantId": { "type": "string" }, "partnerId": { "type": "string", "format": "uuid" } } }, "LinkUpdate": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri", "pattern": "^[Hh][Tt][Tt][Pp][Ss]://" }, "title": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "oneOf": [ { "type": "string", "format": "uri", "pattern": "^[Hh][Tt][Tt][Pp][Ss]://" }, { "type": "null" } ] }, "utm": { "$ref": "#/components/schemas/UtmUpdate" }, "expiresAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO date-time with timezone offset. When the current server time is later than this value, the link is expired. Send null to clear." }, "expiredUrl": { "oneOf": [ { "type": "string", "format": "uri", "pattern": "^[Hh][Tt][Tt][Pp][Ss]://" }, { "type": "null" } ], "description": "Destination URL used after expiration. Expired links skip device and geo targeting. Send null to clear." }, "password": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Password visitors must enter before Hoko resolves the final destination. Send null to clear." }, "cloaked": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "When true, Hoko renders the resolved destination in a full-page iframe. Create and update requests preflight the destination and return 400 when the current destination blocks iframe rendering. Send false or null to disable." }, "ios": { "oneOf": [ { "type": "string", "format": "uri", "pattern": "^[Hh][Tt][Tt][Pp][Ss]://" }, { "type": "null" } ], "description": "iOS-specific destination selected from best-effort User-Agent detection. iOS and Android checks run before geo targeting. Send null to clear." }, "android": { "oneOf": [ { "type": "string", "format": "uri", "pattern": "^[Hh][Tt][Tt][Pp][Ss]://" }, { "type": "null" } ], "description": "Android-specific destination selected from best-effort User-Agent detection. iOS and Android checks run before geo targeting. Send null to clear." }, "geo": { "oneOf": [ { "$ref": "#/components/schemas/GeoTargeting" }, { "type": "null" } ], "description": "Country-code destination map. Use uppercase ISO 3166-1 alpha-2 keys such as SA or US. Geo targeting runs after iOS and Android checks. Send null to clear." }, "collectionId": { "type": "string", "format": "uuid" }, "tagIds": { "type": "array", "maxItems": 10000, "items": { "type": "string", "format": "uuid" }, "description": "When provided, replaces the link tag assignments with this exact list. Send an empty array to clear all tags." }, "externalId": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "tenantId": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "partnerId": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } }, "anyOf": [ { "required": [ "url" ] }, { "required": [ "title" ] }, { "required": [ "description" ] }, { "required": [ "image" ] }, { "required": [ "utm" ], "properties": { "utm": { "type": "object", "anyOf": [ { "required": [ "source" ] }, { "required": [ "medium" ] }, { "required": [ "campaign" ] }, { "required": [ "term" ] }, { "required": [ "content" ] }, { "required": [ "referral" ] } ] } } }, { "required": [ "expiresAt" ] }, { "required": [ "expiredUrl" ] }, { "required": [ "password" ] }, { "required": [ "cloaked" ] }, { "required": [ "ios" ] }, { "required": [ "android" ] }, { "required": [ "geo" ] }, { "required": [ "collectionId" ] }, { "required": [ "tagIds" ] }, { "required": [ "externalId" ] }, { "required": [ "tenantId" ] }, { "required": [ "partnerId" ] } ] }, "LinkUpsert": { "anyOf": [ { "$ref": "#/components/schemas/LinkCreate" }, { "$ref": "#/components/schemas/LinkUpdate" } ] }, "Collection": { "type": "object", "required": [ "id", "name", "description", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CollectionCreate": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" } } }, "CollectionUpdate": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1 }, "description": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "anyOf": [ { "required": [ "name" ] }, { "required": [ "description" ] } ] }, "CollectionPutCreate": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } } }, "CollectionUpsert": { "anyOf": [ { "$ref": "#/components/schemas/CollectionPutCreate" }, { "$ref": "#/components/schemas/CollectionUpdate" } ] }, "Tag": { "type": "object", "required": [ "id", "name", "color" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ] } } }, "TagCreate": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1 }, "color": { "type": "string", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "default": "slate" } } }, "TagUpdate": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1 }, "color": { "type": "string", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ] } }, "anyOf": [ { "required": [ "name" ] }, { "required": [ "color" ] } ] }, "TagUpsert": { "anyOf": [ { "$ref": "#/components/schemas/TagCreate" }, { "$ref": "#/components/schemas/TagUpdate" } ] }, "Partner": { "type": "object", "required": [ "id", "name", "email", "phone", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "PartnerCreate": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" } } }, "PartnerUpdate": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1 }, "email": { "oneOf": [ { "type": "string", "format": "email" }, { "type": "null" } ], "description": "Send null to clear when the same payload also provides a non-null email or phone value." }, "phone": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Send null to clear when the same payload also provides a non-null email or phone value." } }, "anyOf": [ { "required": [ "name" ] }, { "required": [ "email" ] }, { "required": [ "phone" ] } ], "allOf": [ { "not": { "required": [ "email" ], "properties": { "email": { "type": "null" }, "phone": { "not": { "type": "string" } } } } }, { "not": { "required": [ "phone" ], "properties": { "phone": { "type": "null" }, "email": { "not": { "type": "string" } } } } } ] }, "PartnerPutCreate": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1 }, "email": { "oneOf": [ { "type": "string", "format": "email" }, { "type": "null" } ], "description": "Nullable on PUT insert only when another contact field in the same payload is non-null." }, "phone": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Nullable on PUT insert only when another contact field in the same payload is non-null." } }, "allOf": [ { "not": { "required": [ "email" ], "properties": { "email": { "type": "null" }, "phone": { "not": { "type": "string" } } } } }, { "not": { "required": [ "phone" ], "properties": { "phone": { "type": "null" }, "email": { "not": { "type": "string" } } } } } ] }, "PartnerUpsert": { "anyOf": [ { "$ref": "#/components/schemas/PartnerPutCreate" }, { "$ref": "#/components/schemas/PartnerUpdate" } ] }, "Customer": { "type": "object", "required": [ "id", "externalId", "avatar", "name", "email", "phone", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "externalId": { "type": "string" }, "avatar": { "oneOf": [ { "type": "string", "format": "uri", "pattern": "^[Hh][Tt][Tt][Pp][Ss]://" }, { "type": "null" } ] }, "name": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CustomerUpdateById": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "externalId": { "type": "string", "minLength": 1, "maxLength": 100 }, "name": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "oneOf": [ { "type": "string", "format": "email" }, { "type": "null" } ] }, "phone": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "avatar": { "oneOf": [ { "type": "string", "format": "uri", "pattern": "^[Hh][Tt][Tt][Pp][Ss]://" }, { "type": "null" } ] } }, "anyOf": [ { "required": [ "externalId" ] }, { "required": [ "name" ] }, { "required": [ "email" ] }, { "required": [ "phone" ] }, { "required": [ "avatar" ] } ] }, "CustomerUpdateByExternalId": { "type": "object", "required": [ "externalId" ], "properties": { "externalId": { "type": "string", "minLength": 1, "maxLength": 100 }, "name": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "oneOf": [ { "type": "string", "format": "email" }, { "type": "null" } ] }, "phone": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "avatar": { "oneOf": [ { "type": "string", "format": "uri", "pattern": "^[Hh][Tt][Tt][Pp][Ss]://" }, { "type": "null" } ] } }, "anyOf": [ { "required": [ "name" ] }, { "required": [ "email" ] }, { "required": [ "phone" ] }, { "required": [ "avatar" ] } ] }, "CustomerUpdate": { "anyOf": [ { "$ref": "#/components/schemas/CustomerUpdateById" }, { "$ref": "#/components/schemas/CustomerUpdateByExternalId" } ] }, "ConversionCustomer": { "type": "object", "required": [ "id", "name", "email", "phone", "avatar", "externalId" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "avatar": { "oneOf": [ { "type": "string", "format": "uri", "pattern": "^[Hh][Tt][Tt][Pp][Ss]://" }, { "type": "null" } ] }, "externalId": { "type": "string" } } }, "Click": { "type": "object", "required": [ "id", "linkId", "partnerId", "visitorId", "visitorSessionId", "referrer", "destination", "shortId", "utm", "externalId", "tenantId", "expired", "secured", "scanned", "geoTargeted", "iosTargeted", "androidTargeted", "origin", "pathname", "search", "browserLanguageCode", "browserLanguageRegion", "browserName", "browserVersion", "osName", "osVersion", "deviceVendor", "deviceModel", "deviceType", "ipAddress", "continent", "country", "countryCode", "region", "city", "district", "zip", "latitude", "longitude", "mobile", "proxy", "hosting", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "linkId": { "type": "string", "format": "uuid" }, "partnerId": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "visitorId": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "visitorSessionId": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "referrer": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "destination": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "shortId": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "utm": { "oneOf": [ { "$ref": "#/components/schemas/Utm" }, { "type": "null" } ] }, "externalId": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "tenantId": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "expired": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "secured": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "scanned": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "geoTargeted": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "iosTargeted": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "androidTargeted": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "origin": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "pathname": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "search": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "browserLanguageCode": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "browserLanguageRegion": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "browserName": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "browserVersion": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "osName": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "osVersion": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "deviceVendor": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "deviceModel": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "deviceType": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "ipAddress": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "continent": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "countryCode": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "region": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "district": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "zip": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "latitude": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "longitude": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "mobile": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "proxy": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "hosting": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } } }, "LeadTrackRequest": { "type": "object", "required": [ "clickId", "eventName", "customerExternalId", "customerName" ], "properties": { "clickId": { "type": "string", "description": "Click ID, or an empty string to use deferred tracking from the customer history." }, "eventName": { "type": "string", "minLength": 1, "maxLength": 255 }, "customerExternalId": { "type": "string", "minLength": 1, "maxLength": 100 }, "customerName": { "type": "string", "minLength": 1, "maxLength": 100 }, "customerEmail": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 100 }, { "type": "null" } ] }, "customerAvatar": { "oneOf": [ { "type": "string", "format": "uri", "pattern": "^[Hh][Tt][Tt][Pp][Ss]://" }, { "type": "null" } ] }, "metadata": { "type": "object", "additionalProperties": true } } }, "SaleTrackRequest": { "type": "object", "required": [ "customerExternalId", "amount", "customerName" ], "properties": { "customerExternalId": { "type": "string", "minLength": 1, "maxLength": 100 }, "amount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "currency": { "type": "string", "default": "usd" }, "eventName": { "type": "string", "maxLength": 255, "default": "Purchase" }, "metadata": { "type": "object", "additionalProperties": true }, "leadEventName": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "clickId": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "customerName": { "type": "string", "minLength": 1, "maxLength": 100 }, "customerEmail": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 100 }, { "type": "null" } ] }, "customerAvatar": { "oneOf": [ { "type": "string", "format": "uri", "pattern": "^[Hh][Tt][Tt][Pp][Ss]://" }, { "type": "null" } ] } } }, "LeadTrackResponse": { "type": "object", "required": [ "click", "link", "lead", "customer" ], "properties": { "click": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" } } }, "link": { "oneOf": [ { "$ref": "#/components/schemas/Link" }, { "type": "null" } ] }, "lead": { "type": "object", "required": [ "id", "eventName", "metadata" ], "properties": { "id": { "type": "string", "format": "uuid" }, "eventName": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } }, "customer": { "$ref": "#/components/schemas/ConversionCustomer" } } }, "SaleTrackResponse": { "type": "object", "required": [ "click", "link", "customer", "sale" ], "properties": { "click": { "oneOf": [ { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" } } }, { "type": "null" } ] }, "link": { "oneOf": [ { "$ref": "#/components/schemas/Link" }, { "type": "null" } ] }, "sale": { "type": "object", "required": [ "id", "eventName", "amount", "currency", "metadata" ], "properties": { "id": { "type": "string", "format": "uuid" }, "eventName": { "type": "string" }, "amount": { "type": "integer" }, "currency": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } }, "customer": { "$ref": "#/components/schemas/ConversionCustomer" } } } } } }