{ "openapi": "3.1.0", "info": { "title": "Node4 API", "version": "1.0.0", "description": "Programmatic access to your Node4 proxies, usage, subscription, IP whitelist and webhooks.\n\nAuthenticate with an API key created in the dashboard under Settings. Send it as `Authorization: Bearer ` or `X-API-Key: `. Keys begin `n4k_`.\n\nEvery key carries an explicit permission list, and every endpoint states the permission it needs. Requests are limited to 60 requests per minute per key.", "contact": { "name": "Node4 support", "url": "https://node4.io/support", "email": "hello@node4.io" } }, "servers": [ { "url": "https://node4.io/api/v1", "description": "Production" } ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ { "name": "Proxies", "description": "List and refresh the proxies on your account." }, { "name": "Usage", "description": "Bandwidth and request history." }, { "name": "Account", "description": "Subscription, profile, orders and notifications." }, { "name": "IP whitelist", "description": "Addresses allowed to use IP-authenticated proxies." }, { "name": "Webhooks", "description": "Outbound event delivery." }, { "name": "Support (restricted)", "description": "Ticket administration. Unlike every other endpoint here, these are NOT self-scoped: they require admin permissions and operate across accounts. An ordinary customer key cannot call them." } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer n4k_..." }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key" } } }, "paths": { "/proxies": { "get": { "tags": [ "Proxies" ], "summary": "List every proxy on the account", "description": "Requires the `read:proxies` permission on the API key. Includes suspended and expired proxies, so `total` and `active` can differ. An integration that only saw active rows could not tell why capacity had dropped.", "responses": { "200": { "description": "The account's proxies.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "total": { "type": "integer" }, "active": { "type": "integer" }, "proxies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string", "description": "shared, premium_private, residential, rotating_shared or rotating_premium." }, "protocol": { "type": "string", "enum": [ "http", "socks5" ] }, "host": { "type": "string" }, "port": { "type": "integer" }, "username": { "type": "string", "description": "Empty for free-tier proxies, which use the account credential." }, "password": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "suspended", "expired" ] }, "country": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } } } } } }, "required": [ "success", "data" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "The key is revoked, or lacks the permission this endpoint needs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. 60 requests per minute per API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/proxies/list": { "get": { "tags": [ "Proxies" ], "summary": "Active proxies in a compact form", "description": "Requires the `read:proxies` permission on the API key. Active proxies only. Intended for feeding automation directly.", "parameters": [ { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "txt", "text" ], "default": "json" }, "description": "`txt` returns `text/plain`, one `host:port:username:password` per line." } ], "responses": { "200": { "description": "Active proxies, as JSON or as plain text depending on `format`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "host": { "type": "string" }, "port": { "type": "integer" }, "username": { "type": "string" }, "password": { "type": "string" }, "protocol": { "type": "string" }, "type": { "type": "string" }, "country": { "type": "string", "nullable": true } } } } } } }, "text/plain": { "schema": { "type": "string", "example": "46.173.64.10:4443:user:pass" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "The key is revoked, or lacks the permission this endpoint needs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. 60 requests per minute per API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/proxies/refresh": { "post": { "tags": [ "Proxies" ], "summary": "Replace a proxy's IP address", "description": "Requires the `write:proxies` permission on the API key. Swaps the exit IP for a fresh one from the pool. Subject to a per-period refresh allowance, returned in the response.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "proxyId": { "type": "integer" } }, "required": [ "proxyId" ] } } } }, "responses": { "200": { "description": "The proxy's new address and credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "proxyId": { "type": "integer" }, "oldIp": { "type": "string" }, "newIp": { "type": "string" }, "newPort": { "type": "integer" }, "newUsername": { "type": "string" }, "newPassword": { "type": "string" }, "refreshesUsed": { "type": "integer" }, "refreshLimit": { "type": "integer" } } } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Missing or malformed proxyId.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "The key is revoked, or lacks the permission this endpoint needs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "No such proxy on this account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. 60 requests per minute per API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "No replacement address available in the pool right now.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/usage": { "get": { "tags": [ "Usage" ], "summary": "Bandwidth totals and recent request logs", "description": "Requires the `read:usage` permission on the API key.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Number of recent log entries. Clamped to 200." } ], "responses": { "200": { "description": "Monthly and all-time bandwidth, plus recent logs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "bandwidth": { "type": "object", "description": "Current calendar month." }, "allTimeBandwidth": { "type": "object" }, "recentLogs": { "type": "array", "items": { "type": "object" } } } } }, "required": [ "success", "data" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "The key is revoked, or lacks the permission this endpoint needs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. 60 requests per minute per API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/usage/bandwidth": { "get": { "tags": [ "Usage" ], "summary": "Bandwidth time series", "description": "Requires the `read:usage` permission on the API key.", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 30 }, "description": "Length of the window, in days." } ], "responses": { "200": { "description": "Hourly snapshots over the window.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "period": { "type": "object" }, "snapshots": { "type": "array", "items": { "type": "object" } } } } }, "required": [ "success", "data" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "The key is revoked, or lacks the permission this endpoint needs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. 60 requests per minute per API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/usage/analytics": { "get": { "tags": [ "Usage" ], "summary": "Monthly usage totals", "description": "Requires the `read:usage` permission on the API key.", "parameters": [ { "name": "months", "in": "query", "required": false, "schema": { "type": "integer", "default": 6 }, "description": "How many months back to include." } ], "responses": { "200": { "description": "Per-month totals.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "monthly": { "type": "array", "items": { "type": "object" } } } } }, "required": [ "success", "data" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "The key is revoked, or lacks the permission this endpoint needs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. 60 requests per minute per API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/subscription": { "get": { "tags": [ "Account" ], "summary": "Current plan and subscription state", "description": "Requires the `read:subscription` permission on the API key.", "responses": { "200": { "description": "The account's subscription." }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "The key is revoked, or lacks the permission this endpoint needs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. 60 requests per minute per API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/profile": { "get": { "tags": [ "Account" ], "summary": "The account this key belongs to", "description": "Requires the `read:profile` permission on the API key.", "responses": { "200": { "description": "Account profile.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email" }, "role": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } } }, "required": [ "success", "data" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "The key is revoked, or lacks the permission this endpoint needs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "The account no longer exists.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. 60 requests per minute per API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/orders": { "get": { "tags": [ "Account" ], "summary": "Order history", "description": "Requires the `read:orders` permission on the API key.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Orders, newest first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "orders": { "type": "array", "items": { "type": "object" } } } } }, "required": [ "success", "data" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "The key is revoked, or lacks the permission this endpoint needs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. 60 requests per minute per API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/notifications": { "get": { "tags": [ "Account" ], "summary": "Account notifications", "description": "Requires the `read:notifications` permission on the API key.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 } } ], "responses": { "200": { "description": "Notifications, newest first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "notifications": { "type": "array", "items": { "type": "object" } } } } }, "required": [ "success", "data" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "The key is revoked, or lacks the permission this endpoint needs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. 60 requests per minute per API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/ip-whitelist": { "get": { "tags": [ "IP whitelist" ], "summary": "List whitelisted addresses", "description": "Requires the `read:profile` permission on the API key.", "responses": { "200": { "description": "Whitelisted addresses.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "total": { "type": "integer" }, "ips": { "type": "array", "items": { "type": "object" } } } } }, "required": [ "success", "data" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "The key is revoked, or lacks the permission this endpoint needs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. 60 requests per minute per API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } }, "post": { "tags": [ "IP whitelist" ], "summary": "Whitelist an address", "description": "Requires the `write:ip-whitelist` permission on the API key. The address must be a publicly routable unicast IPv4 address. Proxy endpoints are IPv4, so IPv6 addresses are refused: they would save without ever matching a connection. Private, loopback, link-local and reserved ranges are refused, as are CIDR blocks.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ipAddress": { "type": "string", "description": "A single public IPv4 address." }, "label": { "type": "string", "nullable": true } }, "required": [ "ipAddress" ] } } } }, "responses": { "200": { "description": "The new entry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "ipAddress": { "type": "string" }, "label": { "type": "string", "nullable": true } } } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Not a public address, already whitelisted, or the plan's slot limit is reached.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "The key is revoked, or lacks the permission this endpoint needs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. 60 requests per minute per API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/ip-whitelist/{id}": { "delete": { "tags": [ "IP whitelist" ], "summary": "Remove a whitelisted address", "description": "Requires the `write:ip-whitelist` permission on the API key.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Removed." }, "400": { "description": "Malformed id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "The key is revoked, or lacks the permission this endpoint needs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. 60 requests per minute per API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List webhooks", "description": "Requires the `write:webhooks` permission on the API key.", "responses": { "200": { "description": "Configured webhooks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "type": "object" } } } } }, "required": [ "success", "data" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "The key is revoked, or lacks the permission this endpoint needs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. 60 requests per minute per API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } }, "post": { "tags": [ "Webhooks" ], "summary": "Create a webhook", "description": "Requires the `write:webhooks` permission on the API key. The URL is resolved and refused if it points at a non-public address, so internal hosts cannot be reached through delivery.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "url", "events" ] } } } }, "responses": { "200": { "description": "The created webhook.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string" } } } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Missing fields, or a destination that is not publicly routable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "The key is revoked, or lacks the permission this endpoint needs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. 60 requests per minute per API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Destination could not be verified.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/webhooks/{id}": { "delete": { "tags": [ "Webhooks" ], "summary": "Delete a webhook", "description": "Requires the `write:webhooks` permission on the API key.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted." }, "400": { "description": "Malformed id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "The key is revoked, or lacks the permission this endpoint needs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "No such webhook on this account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. 60 requests per minute per API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/tickets": { "get": { "tags": [ "Support (restricted)" ], "summary": "List support tickets", "description": "Requires the `admin:tickets:read` permission on the API key. Admin only. Not available to customer keys.", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "priority", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "needsReply", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Matching tickets." }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "The key is revoked, or lacks the permission this endpoint needs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. 60 requests per minute per API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/tickets/{id}": { "get": { "tags": [ "Support (restricted)" ], "summary": "Read one ticket with its messages", "description": "Requires the `admin:tickets:read` permission on the API key. Admin only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The ticket and its thread." }, "400": { "description": "Malformed id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "The key is revoked, or lacks the permission this endpoint needs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "No such ticket.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. 60 requests per minute per API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } }, "patch": { "tags": [ "Support (restricted)" ], "summary": "Update a ticket", "description": "Requires the `admin:tickets:write` permission on the API key. Admin only. Status, priority, category and assignment.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "The updated ticket." }, "400": { "description": "Nothing to update, or a malformed field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "The key is revoked, or lacks the permission this endpoint needs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "No such ticket.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. 60 requests per minute per API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/tickets/{id}/reply": { "post": { "tags": [ "Support (restricted)" ], "summary": "Reply to a ticket", "description": "Requires the `admin:tickets:write` permission on the API key. Admin only. Posts a message on the thread and emails the customer.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "The posted reply." }, "400": { "description": "Empty message.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "The key is revoked, or lacks the permission this endpoint needs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "No such ticket.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. 60 requests per minute per API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } } } }