{ "openapi": "3.0.0", "info": { "title": "RedirectBoss API", "description": "Public API for programmatic redirect and host management.\n\nAuthenticate all requests with your API key:\n`X-Api-Key: rb_live_`\n\nGenerate an API key from the RedirectBoss dashboard under Preferences → API Keys.", "version": "1.0.0" }, "components": { "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "API key from the RedirectBoss dashboard. Example: \"X-Api-Key: rb_live_\"" } }, "schemas": {} }, "paths": { "/v1/hosts/": { "get": { "tags": [ "Hosts" ], "description": "List all hosts, with optional search and pagination.", "parameters": [ { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "in": "query", "name": "offset", "required": false, "description": "Number of records to skip (for pagination)" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of records to return (for pagination)" }, { "schema": { "type": "string", "enum": [ "host", "dnsLastCheckedAt", "dnsStateLastChangedAt", "sslEnabledAt", "createdAt", "updatedAt" ], "default": "updatedAt" }, "in": "query", "name": "orderBy", "required": false, "description": "Field to order results by" }, { "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "DESC" }, "in": "query", "name": "orderDir", "required": false, "description": "Sort direction (ASC or DESC)" }, { "schema": { "type": "string" }, "in": "query", "name": "search", "required": false, "description": "Case-insensitive substring match on host" }, { "schema": { "type": "boolean" }, "in": "query", "name": "isSslEnabled", "required": false, "description": "Filter to only SSL-enabled or SSL-disabled hosts" }, { "schema": { "type": "boolean" }, "in": "query", "name": "isDnsResolving", "required": false, "description": "Filter to only DNS-resolving or non-resolving hosts" } ], "responses": { "200": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" }, "description": "Maximum requests allowed per hour (e.g. \"5000\")" }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" }, "description": "Requests remaining in the current hourly window" }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" }, "description": "Maximum write operations (POST/PUT/DELETE) allowed per day (e.g. \"1000\")" }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" }, "description": "Write operations remaining in the current daily window" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique host identifier" }, "host": { "type": "string", "format": "hostname", "description": "The domain name (e.g. \"example.com\")" }, "handleWww": { "type": "boolean", "description": "Whether the www subdomain is also handled (e.g. www.example.com)" }, "isDnsResolving": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the apex domain DNS is resolving to our servers. Null if not yet checked." }, "dnsLastCheckedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When DNS resolution was last verified. Null if not yet checked." }, "sslEnabledAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When SSL was enabled for the apex domain. Null if SSL is not enabled." }, "wwwSslEnabledAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When SSL was enabled for the www subdomain. Null if SSL is not enabled." }, "wwwDnsResolving": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the www subdomain DNS is resolving to our servers. Null if not yet checked." }, "createdAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the host was created" }, "updatedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the host was last updated" } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this request" } } }, "pagination": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Starting position in the result set" }, "limit": { "type": "integer", "description": "Maximum number of items returned per page" }, "total": { "type": "integer", "description": "Total number of items matching the query" }, "totalPages": { "type": "integer", "description": "Total number of pages available" }, "hasNext": { "type": "boolean", "description": "Whether there is a next page of results" }, "hasPrev": { "type": "boolean", "description": "Whether there is a previous page of results" } } } }, "required": [ "data", "meta", "pagination" ] } } } }, "429": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" }, "description": "Maximum requests allowed per hour (e.g. \"5000\")" }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" }, "description": "Requests remaining in the current hourly window" }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" }, "description": "Maximum write operations (POST/PUT/DELETE) allowed per day (e.g. \"1000\")" }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" }, "description": "Write operations remaining in the current daily window" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "A description of which rate limit was exceeded" }, "secondsUntilReset": { "type": "integer", "description": "Seconds until the rate limit window resets" } }, "required": [ "error" ] } } } } } }, "post": { "tags": [ "Hosts" ], "description": "Register a new host domain. A DNS check runs automatically after creation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "host" ], "properties": { "host": { "type": "string", "format": "hostname", "description": "The domain name to register (e.g. \"example.com\")" }, "handleWww": { "type": "boolean", "default": false, "description": "Also handle www subdomain traffic (e.g. www.example.com)" } } } } } }, "responses": { "201": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" }, "description": "Maximum requests allowed per hour (e.g. \"5000\")" }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" }, "description": "Requests remaining in the current hourly window" }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" }, "description": "Maximum write operations (POST/PUT/DELETE) allowed per day (e.g. \"1000\")" }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" }, "description": "Write operations remaining in the current daily window" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique host identifier" }, "host": { "type": "string", "format": "hostname", "description": "The domain name (e.g. \"example.com\")" }, "handleWww": { "type": "boolean", "description": "Whether the www subdomain is also handled (e.g. www.example.com)" }, "isDnsResolving": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the apex domain DNS is resolving to our servers. Null if not yet checked." }, "dnsLastCheckedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When DNS resolution was last verified. Null if not yet checked." }, "sslEnabledAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When SSL was enabled for the apex domain. Null if SSL is not enabled." }, "wwwSslEnabledAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When SSL was enabled for the www subdomain. Null if SSL is not enabled." }, "wwwDnsResolving": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the www subdomain DNS is resolving to our servers. Null if not yet checked." }, "createdAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the host was created" }, "updatedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the host was last updated" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this request" }, "status": { "type": "string", "enum": [ "completed", "queued", "partial_failure" ], "description": "Operation status" } } } }, "required": [ "data", "meta" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "A description of what went wrong" } }, "required": [ "error" ] } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "A description of what went wrong" } }, "required": [ "error" ] } } } }, "429": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" }, "description": "Maximum requests allowed per hour (e.g. \"5000\")" }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" }, "description": "Requests remaining in the current hourly window" }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" }, "description": "Maximum write operations (POST/PUT/DELETE) allowed per day (e.g. \"1000\")" }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" }, "description": "Write operations remaining in the current daily window" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "A description of which rate limit was exceeded" }, "secondsUntilReset": { "type": "integer", "description": "Seconds until the rate limit window resets" } }, "required": [ "error" ] } } } } } } }, "/v1/hosts/{id}": { "get": { "tags": [ "Hosts" ], "description": "Retrieve a single host, including its redirect count.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" }, "description": "Maximum requests allowed per hour (e.g. \"5000\")" }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" }, "description": "Requests remaining in the current hourly window" }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" }, "description": "Maximum write operations (POST/PUT/DELETE) allowed per day (e.g. \"1000\")" }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" }, "description": "Write operations remaining in the current daily window" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique host identifier" }, "host": { "type": "string", "format": "hostname", "description": "The domain name (e.g. \"example.com\")" }, "handleWww": { "type": "boolean", "description": "Whether the www subdomain is also handled (e.g. www.example.com)" }, "isDnsResolving": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the apex domain DNS is resolving to our servers. Null if not yet checked." }, "dnsLastCheckedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When DNS resolution was last verified. Null if not yet checked." }, "sslEnabledAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When SSL was enabled for the apex domain. Null if SSL is not enabled." }, "wwwSslEnabledAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When SSL was enabled for the www subdomain. Null if SSL is not enabled." }, "wwwDnsResolving": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the www subdomain DNS is resolving to our servers. Null if not yet checked." }, "createdAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the host was created" }, "updatedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the host was last updated" }, "redirectCount": { "type": "integer", "description": "Number of redirects configured for this host" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this request" } } } }, "required": [ "data", "meta" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "A description of what went wrong" } }, "required": [ "error" ] } } } }, "429": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" }, "description": "Maximum requests allowed per hour (e.g. \"5000\")" }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" }, "description": "Requests remaining in the current hourly window" }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" }, "description": "Maximum write operations (POST/PUT/DELETE) allowed per day (e.g. \"1000\")" }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" }, "description": "Write operations remaining in the current daily window" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "A description of which rate limit was exceeded" }, "secondsUntilReset": { "type": "integer", "description": "Seconds until the rate limit window resets" } }, "required": [ "error" ] } } } } } }, "patch": { "tags": [ "Hosts" ], "description": "Update host configuration (e.g. www subdomain handling). A DNS recheck runs automatically after the update.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "handleWww": { "type": "boolean", "description": "Whether to also handle www subdomain traffic" } }, "required": [ "handleWww" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" }, "description": "Maximum requests allowed per hour (e.g. \"5000\")" }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" }, "description": "Requests remaining in the current hourly window" }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" }, "description": "Maximum write operations (POST/PUT/DELETE) allowed per day (e.g. \"1000\")" }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" }, "description": "Write operations remaining in the current daily window" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique host identifier" }, "host": { "type": "string", "format": "hostname", "description": "The domain name (e.g. \"example.com\")" }, "handleWww": { "type": "boolean", "description": "Whether the www subdomain is also handled (e.g. www.example.com)" }, "isDnsResolving": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the apex domain DNS is resolving to our servers. Null if not yet checked." }, "dnsLastCheckedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When DNS resolution was last verified. Null if not yet checked." }, "sslEnabledAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When SSL was enabled for the apex domain. Null if SSL is not enabled." }, "wwwSslEnabledAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When SSL was enabled for the www subdomain. Null if SSL is not enabled." }, "wwwDnsResolving": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the www subdomain DNS is resolving to our servers. Null if not yet checked." }, "createdAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the host was created" }, "updatedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the host was last updated" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this request" }, "status": { "type": "string", "enum": [ "completed", "queued", "partial_failure" ], "description": "Operation status" } } } }, "required": [ "data", "meta" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "A description of what went wrong" } }, "required": [ "error" ] } } } }, "429": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" }, "description": "Maximum requests allowed per hour (e.g. \"5000\")" }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" }, "description": "Requests remaining in the current hourly window" }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" }, "description": "Maximum write operations (POST/PUT/DELETE) allowed per day (e.g. \"1000\")" }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" }, "description": "Write operations remaining in the current daily window" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "A description of which rate limit was exceeded" }, "secondsUntilReset": { "type": "integer", "description": "Seconds until the rate limit window resets" } }, "required": [ "error" ] } } } } } }, "delete": { "tags": [ "Hosts" ], "description": "Permanently removes a host and all associated redirects. This action is irreversible.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Permanently removes a host and all associated redirects. This action is irreversible.", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" }, "description": "Maximum requests allowed per hour (e.g. \"5000\")" }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" }, "description": "Requests remaining in the current hourly window" }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" }, "description": "Maximum write operations (POST/PUT/DELETE) allowed per day (e.g. \"1000\")" }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" }, "description": "Write operations remaining in the current daily window" } }, "content": { "application/json": { "schema": { "description": "Permanently removes a host and all associated redirects. This action is irreversible.", "type": "object", "properties": { "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the deletion was successful" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this request" } } } }, "required": [ "data", "meta" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "A description of what went wrong" } }, "required": [ "error" ] } } } }, "429": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" }, "description": "Maximum requests allowed per hour (e.g. \"5000\")" }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" }, "description": "Requests remaining in the current hourly window" }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" }, "description": "Maximum write operations (POST/PUT/DELETE) allowed per day (e.g. \"1000\")" }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" }, "description": "Write operations remaining in the current daily window" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "A description of which rate limit was exceeded" }, "secondsUntilReset": { "type": "integer", "description": "Seconds until the rate limit window resets" } }, "required": [ "error" ] } } } } } } }, "/v1/hosts/{id}/dns-status": { "get": { "tags": [ "Hosts" ], "description": "Run a live DNS resolution check and return the results.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" }, "description": "Maximum requests allowed per hour (e.g. \"5000\")" }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" }, "description": "Requests remaining in the current hourly window" }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" }, "description": "Maximum write operations (POST/PUT/DELETE) allowed per day (e.g. \"1000\")" }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" }, "description": "Write operations remaining in the current daily window" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "hostId": { "type": "string", "format": "uuid", "description": "Unique host identifier" }, "host": { "type": "string", "description": "The domain name" }, "isDnsResolving": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the apex domain DNS is resolving to our servers. Null if not yet checked." }, "dnsLastCheckedAt": { "type": "string", "format": "date-time", "description": "When DNS resolution was last verified" }, "wwwDnsResolving": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the www subdomain DNS is resolving to our servers. Null if not yet checked." } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this request" } } } }, "required": [ "data", "meta" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "A description of what went wrong" } }, "required": [ "error" ] } } } }, "429": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" }, "description": "Maximum requests allowed per hour (e.g. \"5000\")" }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" }, "description": "Requests remaining in the current hourly window" }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" }, "description": "Maximum write operations (POST/PUT/DELETE) allowed per day (e.g. \"1000\")" }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" }, "description": "Write operations remaining in the current daily window" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "A description of which rate limit was exceeded" }, "secondsUntilReset": { "type": "integer", "description": "Seconds until the rate limit window resets" } }, "required": [ "error" ] } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "A description of what went wrong" } }, "required": [ "error" ] } } } } } } }, "/v1/hosts/{id}/ssl-status": { "get": { "tags": [ "Hosts" ], "description": "Get the current SSL certificate status, including provisioning progress.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" }, "description": "Maximum requests allowed per hour (e.g. \"5000\")" }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" }, "description": "Requests remaining in the current hourly window" }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" }, "description": "Maximum write operations (POST/PUT/DELETE) allowed per day (e.g. \"1000\")" }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" }, "description": "Write operations remaining in the current daily window" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "hostId": { "type": "string", "format": "uuid", "description": "Unique host identifier" }, "host": { "type": "string", "description": "The domain name" }, "sslEnabled": { "type": "boolean", "description": "Whether SSL is enabled for the apex domain" }, "sslEnabledAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When SSL was enabled for the apex domain. Null if not enabled." }, "wwwSslEnabled": { "type": "boolean", "description": "Whether SSL is enabled for the www subdomain" }, "wwwSslEnabledAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When SSL was enabled for the www subdomain. Null if not enabled." }, "sslProvisioningStatus": { "oneOf": [ { "type": "string", "enum": [ "pending", "in_progress", "completed", "partial_failure", "failed" ] }, { "type": "null" } ], "description": "Current SSL provisioning status" }, "sslProvisioningMessage": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-readable provisioning status message" }, "sslProvisioningLastAttemptedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When SSL provisioning was last attempted" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this request" } } } }, "required": [ "data", "meta" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "A description of what went wrong" } }, "required": [ "error" ] } } } }, "429": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" }, "description": "Maximum requests allowed per hour (e.g. \"5000\")" }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" }, "description": "Requests remaining in the current hourly window" }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" }, "description": "Maximum write operations (POST/PUT/DELETE) allowed per day (e.g. \"1000\")" }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" }, "description": "Write operations remaining in the current daily window" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "A description of which rate limit was exceeded" }, "secondsUntilReset": { "type": "integer", "description": "Seconds until the rate limit window resets" } }, "required": [ "error" ] } } } } } } }, "/v1/hosts/{id}/enable-ssl": { "post": { "tags": [ "Hosts" ], "description": "Trigger SSL certificate provisioning. Runs asynchronously by default; poll /v1/hosts/{id}/ssl-status to track progress.", "parameters": [ { "schema": { "type": "string", "enum": [ "true", "false" ], "default": "true" }, "in": "query", "name": "async", "required": false, "description": "If true (default), SSL provisioning runs asynchronously. Set to false for synchronous behavior." }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" }, "description": "Maximum requests allowed per hour (e.g. \"5000\")" }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" }, "description": "Requests remaining in the current hourly window" }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" }, "description": "Maximum write operations (POST/PUT/DELETE) allowed per day (e.g. \"1000\")" }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" }, "description": "Write operations remaining in the current daily window" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation that SSL provisioning has been initiated or completed" }, "sslStatusUrl": { "type": "string", "description": "URL to poll for SSL provisioning status" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this request" }, "status": { "type": "string", "enum": [ "completed", "queued", "partial_failure" ], "description": "Operation status" } } } }, "required": [ "data", "meta" ] } } } }, "202": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" }, "description": "Maximum requests allowed per hour (e.g. \"5000\")" }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" }, "description": "Requests remaining in the current hourly window" }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" }, "description": "Maximum write operations (POST/PUT/DELETE) allowed per day (e.g. \"1000\")" }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" }, "description": "Write operations remaining in the current daily window" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation that SSL provisioning has been initiated or completed" }, "sslStatusUrl": { "type": "string", "description": "URL to poll for SSL provisioning status" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this request" }, "status": { "type": "string", "enum": [ "completed", "queued", "partial_failure" ], "description": "Operation status" } } } }, "required": [ "data", "meta" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "A description of what went wrong" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "A description of what went wrong" } }, "required": [ "error" ] } } } }, "429": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" }, "description": "Maximum requests allowed per hour (e.g. \"5000\")" }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" }, "description": "Requests remaining in the current hourly window" }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" }, "description": "Maximum write operations (POST/PUT/DELETE) allowed per day (e.g. \"1000\")" }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" }, "description": "Write operations remaining in the current daily window" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "A description of which rate limit was exceeded" }, "hoursUntilReset": { "type": "number", "description": "Hours until the SSL certificate rate limit resets" }, "secondsUntilReset": { "type": "integer", "description": "Seconds until the API rate limit window resets" } }, "required": [ "error" ] } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "A description of what went wrong" } }, "required": [ "error" ] } } } } } } }, "/v1/redirects/": { "get": { "tags": [ "Redirects" ], "description": "List all redirects, with optional filtering, search, and pagination.", "parameters": [ { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "in": "query", "name": "offset", "required": false, "description": "Number of records to skip (for pagination)" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of records to return (for pagination)" }, { "schema": { "type": "string", "enum": [ "matchType", "path", "destinationUrl", "statusCode", "createdAt", "updatedAt", "host" ], "default": "updatedAt" }, "in": "query", "name": "orderBy", "required": false, "description": "Field to order results by" }, { "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "DESC" }, "in": "query", "name": "orderDir", "required": false, "description": "Sort direction (ASC or DESC)" }, { "schema": { "type": "string" }, "in": "query", "name": "search", "required": false, "description": "Case-insensitive substring match on description, path, or destination URL" }, { "schema": { "type": "boolean" }, "in": "query", "name": "active", "required": false, "description": "Filter by active status. If true, return only active redirects; if false, return only inactive. Omit to return all." }, { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "hostId", "required": false, "description": "Filter redirects by host UUID" }, { "schema": { "type": "string", "format": "hostname" }, "in": "query", "name": "hostName", "required": false, "description": "Filter redirects by host domain name (e.g. \"example.com\")" }, { "schema": { "type": "string", "enum": [ "host", "exact", "prefix" ] }, "in": "query", "name": "matchType", "required": false, "description": "Filter by match type" }, { "schema": { "type": "integer", "enum": [ 301, 302, 303, 307 ] }, "in": "query", "name": "statusCode", "required": false, "description": "Filter by HTTP status code" } ], "responses": { "200": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" }, "description": "Maximum requests allowed per hour (e.g. \"5000\")" }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" }, "description": "Requests remaining in the current hourly window" }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" }, "description": "Maximum write operations (POST/PUT/DELETE) allowed per day (e.g. \"1000\")" }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" }, "description": "Write operations remaining in the current daily window" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique redirect identifier" }, "hostId": { "type": "string", "format": "uuid", "description": "The host this redirect belongs to" }, "host": { "oneOf": [ { "type": "string", "format": "hostname" }, { "type": "null" } ], "description": "The domain name of the associated host" }, "matchType": { "type": "string", "enum": [ "host", "exact", "prefix" ], "description": "How the redirect matches incoming requests: \"host\" matches any request to the domain, \"exact\" matches an exact path, \"prefix\" matches any path starting with the given prefix" }, "path": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "The path to match (e.g. \"/old-page\"). Null for \"host\" match type redirects." }, "destinationUrl": { "type": "string", "description": "The target URL that matching requests are redirected to" }, "statusCode": { "type": "integer", "enum": [ 301, 302, 303, 307 ], "description": "The HTTP status code used for the redirect (301=permanent, 302/303/307=temporary)" }, "preserveQueryString": { "type": "boolean", "description": "Whether to forward the original query string to the redirect target" }, "appendPath": { "type": "boolean", "description": "Whether to append the original request path to the redirect target" }, "description": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional note or label for this redirect" }, "active": { "type": "boolean", "description": "Whether the redirect is currently active. Inactive redirects do not process requests but remain fully configured and can be reactivated at any time via PATCH. To permanently remove a redirect, use DELETE instead." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the redirect was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the redirect was last updated" } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this request" } } }, "pagination": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Starting position in the result set" }, "limit": { "type": "integer", "description": "Maximum number of items returned per page" }, "total": { "type": "integer", "description": "Total number of items matching the query" }, "totalPages": { "type": "integer", "description": "Total number of pages available" }, "hasNext": { "type": "boolean", "description": "Whether there is a next page of results" }, "hasPrev": { "type": "boolean", "description": "Whether there is a previous page of results" } } } }, "required": [ "data", "meta", "pagination" ] } } } }, "429": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" }, "description": "Maximum requests allowed per hour (e.g. \"5000\")" }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" }, "description": "Requests remaining in the current hourly window" }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" }, "description": "Maximum write operations (POST/PUT/DELETE) allowed per day (e.g. \"1000\")" }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" }, "description": "Write operations remaining in the current daily window" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "A description of which rate limit was exceeded" }, "secondsUntilReset": { "type": "integer", "description": "Seconds until the rate limit window resets" } }, "required": [ "error" ] } } } } } }, "post": { "tags": [ "Redirects" ], "description": "Create a new redirect. Specify the target host by hostId or hostName.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "matchType", "destinationUrl", "statusCode" ], "properties": { "hostId": { "type": "string", "format": "uuid", "description": "UUID of the host to associate this redirect with. Either hostId or hostName is required." }, "hostName": { "type": "string", "format": "hostname", "description": "Domain name of the host (e.g. \"example.com\"). Used as an alternative to hostId: the host will be looked up by name. Either hostId or hostName is required." }, "matchType": { "type": "string", "enum": [ "host", "exact", "prefix" ], "description": "How to match incoming requests: \"host\" matches any request to the domain, \"exact\" matches an exact path, \"prefix\" matches any path starting with the given prefix" }, "path": { "type": "string", "nullable": true, "format": "http-path", "description": "Required for \"exact\" and \"prefix\" match types, forbidden for \"host\" match type. Must start with /", "minLength": 1, "maxLength": 4000 }, "destinationUrl": { "type": "string", "format": "redirect-url", "description": "Target URL for the redirect. Must be a valid HTTP/HTTPS URL with a proper hostname." }, "statusCode": { "type": "integer", "enum": [ 301, 302, 303, 307 ], "description": "HTTP status code for the redirect (301=permanent, 302/303/307=temporary)" }, "preserveQueryString": { "type": "boolean", "default": false, "description": "Forward the original query string to the destination URL" }, "appendPath": { "type": "boolean", "default": false, "description": "Append the original request path to the destination URL. Useful with \"host\" match type to forward all paths." }, "description": { "type": "string", "nullable": true, "description": "Optional note or label for this redirect" } }, "allOf": [ { "if": { "properties": { "matchType": { "enum": [ "host" ] } } }, "then": { "not": { "required": [ "path" ] }, "errorMessage": { "not": "path must NOT be present when matchType is \"host\"" } } }, { "if": { "properties": { "matchType": { "enum": [ "exact", "prefix" ] } } }, "then": { "required": [ "path" ], "errorMessage": { "required": { "path": "path is required for \"exact\" and \"prefix\" match types" } } } } ], "errorMessage": { "required": { "matchType": "matchType is required and must be one of \"host\", \"exact\", or \"prefix\"", "destinationUrl": "destinationUrl is required and must be a valid HTTP/HTTPS URL with a proper hostname", "statusCode": "statusCode is required and must be one of 301, 302, 303, or 307" }, "properties": { "hostId": "hostId must be a valid UUID", "hostName": "hostName must be a valid hostname", "path": "path must start with / and be a valid path with maximum length of 4000 characters", "destinationUrl": "destinationUrl must be a valid HTTP/HTTPS URL with a proper hostname (e.g., https://example.com, not https://foo)", "statusCode": "statusCode must be one of 301, 302, 303, or 307" }, "_": "Invalid request body for creating a redirect" } } } } }, "responses": { "201": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" }, "description": "Maximum requests allowed per hour (e.g. \"5000\")" }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" }, "description": "Requests remaining in the current hourly window" }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" }, "description": "Maximum write operations (POST/PUT/DELETE) allowed per day (e.g. \"1000\")" }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" }, "description": "Write operations remaining in the current daily window" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique redirect identifier" }, "hostId": { "type": "string", "format": "uuid", "description": "The host this redirect belongs to" }, "host": { "oneOf": [ { "type": "string", "format": "hostname" }, { "type": "null" } ], "description": "The domain name of the associated host" }, "matchType": { "type": "string", "enum": [ "host", "exact", "prefix" ], "description": "How the redirect matches incoming requests: \"host\" matches any request to the domain, \"exact\" matches an exact path, \"prefix\" matches any path starting with the given prefix" }, "path": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "The path to match (e.g. \"/old-page\"). Null for \"host\" match type redirects." }, "destinationUrl": { "type": "string", "description": "The target URL that matching requests are redirected to" }, "statusCode": { "type": "integer", "enum": [ 301, 302, 303, 307 ], "description": "The HTTP status code used for the redirect (301=permanent, 302/303/307=temporary)" }, "preserveQueryString": { "type": "boolean", "description": "Whether to forward the original query string to the redirect target" }, "appendPath": { "type": "boolean", "description": "Whether to append the original request path to the redirect target" }, "description": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional note or label for this redirect" }, "active": { "type": "boolean", "description": "Whether the redirect is currently active. Inactive redirects do not process requests but remain fully configured and can be reactivated at any time via PATCH. To permanently remove a redirect, use DELETE instead." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the redirect was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the redirect was last updated" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this request" }, "status": { "type": "string", "enum": [ "completed", "queued", "partial_failure" ], "description": "Operation status" } } } }, "required": [ "data", "meta" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "A description of what went wrong" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "A description of what went wrong" } }, "required": [ "error" ] } } } }, "429": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" }, "description": "Maximum requests allowed per hour (e.g. \"5000\")" }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" }, "description": "Requests remaining in the current hourly window" }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" }, "description": "Maximum write operations (POST/PUT/DELETE) allowed per day (e.g. \"1000\")" }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" }, "description": "Write operations remaining in the current daily window" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "A description of which rate limit was exceeded" }, "secondsUntilReset": { "type": "integer", "description": "Seconds until the rate limit window resets" } }, "required": [ "error" ] } } } } } } }, "/v1/redirects/{id}": { "get": { "tags": [ "Redirects" ], "description": "Retrieve a single redirect.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" }, "description": "Maximum requests allowed per hour (e.g. \"5000\")" }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" }, "description": "Requests remaining in the current hourly window" }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" }, "description": "Maximum write operations (POST/PUT/DELETE) allowed per day (e.g. \"1000\")" }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" }, "description": "Write operations remaining in the current daily window" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique redirect identifier" }, "hostId": { "type": "string", "format": "uuid", "description": "The host this redirect belongs to" }, "host": { "oneOf": [ { "type": "string", "format": "hostname" }, { "type": "null" } ], "description": "The domain name of the associated host" }, "matchType": { "type": "string", "enum": [ "host", "exact", "prefix" ], "description": "How the redirect matches incoming requests: \"host\" matches any request to the domain, \"exact\" matches an exact path, \"prefix\" matches any path starting with the given prefix" }, "path": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "The path to match (e.g. \"/old-page\"). Null for \"host\" match type redirects." }, "destinationUrl": { "type": "string", "description": "The target URL that matching requests are redirected to" }, "statusCode": { "type": "integer", "enum": [ 301, 302, 303, 307 ], "description": "The HTTP status code used for the redirect (301=permanent, 302/303/307=temporary)" }, "preserveQueryString": { "type": "boolean", "description": "Whether to forward the original query string to the redirect target" }, "appendPath": { "type": "boolean", "description": "Whether to append the original request path to the redirect target" }, "description": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional note or label for this redirect" }, "active": { "type": "boolean", "description": "Whether the redirect is currently active. Inactive redirects do not process requests but remain fully configured and can be reactivated at any time via PATCH. To permanently remove a redirect, use DELETE instead." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the redirect was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the redirect was last updated" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this request" } } } }, "required": [ "data", "meta" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "A description of what went wrong" } }, "required": [ "error" ] } } } }, "429": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" }, "description": "Maximum requests allowed per hour (e.g. \"5000\")" }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" }, "description": "Requests remaining in the current hourly window" }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" }, "description": "Maximum write operations (POST/PUT/DELETE) allowed per day (e.g. \"1000\")" }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" }, "description": "Write operations remaining in the current daily window" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "A description of which rate limit was exceeded" }, "secondsUntilReset": { "type": "integer", "description": "Seconds until the rate limit window resets" } }, "required": [ "error" ] } } } } } }, "patch": { "tags": [ "Redirects" ], "description": "Partially update one or more fields on a redirect. Set {\"active\": false} to deactivate without deleting, or {\"active\": true} to reactivate.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "active": { "type": "boolean", "description": "Set to false to deactivate the redirect (stops processing requests but preserves configuration), or true to reactivate it. To permanently remove a redirect, use DELETE instead." }, "matchType": { "type": "string", "enum": [ "host", "exact", "prefix" ], "description": "How to match incoming requests: \"host\" matches any request to the domain, \"exact\" matches an exact path, \"prefix\" matches a path prefix" }, "path": { "type": "string", "nullable": true, "format": "http-path", "minLength": 1, "maxLength": 4000, "description": "The path to match. Required for \"exact\" and \"prefix\", must be null or omitted for \"host\"." }, "destinationUrl": { "type": "string", "format": "redirect-url", "description": "Target URL for the redirect" }, "statusCode": { "type": "integer", "enum": [ 301, 302, 303, 307 ], "description": "HTTP status code (301=permanent, 302/303/307=temporary)" }, "preserveQueryString": { "type": "boolean", "description": "Forward the original query string to the destination URL" }, "appendPath": { "type": "boolean", "description": "Append the original request path to the destination URL" }, "description": { "type": "string", "nullable": true, "description": "Optional note or label for this redirect" } }, "allOf": [ { "if": { "required": [ "matchType" ], "properties": { "matchType": { "enum": [ "exact" ] } } }, "then": { "required": [ "path" ], "errorMessage": { "required": { "path": "path is required when matchType is \"exact\"" } } } }, { "if": { "required": [ "matchType" ], "properties": { "matchType": { "enum": [ "host" ] } } }, "then": { "properties": { "path": { "type": "null" } }, "errorMessage": { "properties": { "path": "path must be null or omitted when matchType is \"host\"" } } } } ], "errorMessage": { "properties": { "path": "path must start with / and be a valid path with maximum length of 4000 characters", "destinationUrl": "destinationUrl must be a valid HTTP/HTTPS URL with a proper hostname (e.g., https://example.com, not https://foo)", "statusCode": "statusCode must be one of 301, 302, 303, or 307" }, "_": "Invalid request body for updating a redirect" } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" }, "description": "Maximum requests allowed per hour (e.g. \"5000\")" }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" }, "description": "Requests remaining in the current hourly window" }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" }, "description": "Maximum write operations (POST/PUT/DELETE) allowed per day (e.g. \"1000\")" }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" }, "description": "Write operations remaining in the current daily window" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique redirect identifier" }, "hostId": { "type": "string", "format": "uuid", "description": "The host this redirect belongs to" }, "host": { "oneOf": [ { "type": "string", "format": "hostname" }, { "type": "null" } ], "description": "The domain name of the associated host" }, "matchType": { "type": "string", "enum": [ "host", "exact", "prefix" ], "description": "How the redirect matches incoming requests: \"host\" matches any request to the domain, \"exact\" matches an exact path, \"prefix\" matches any path starting with the given prefix" }, "path": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "The path to match (e.g. \"/old-page\"). Null for \"host\" match type redirects." }, "destinationUrl": { "type": "string", "description": "The target URL that matching requests are redirected to" }, "statusCode": { "type": "integer", "enum": [ 301, 302, 303, 307 ], "description": "The HTTP status code used for the redirect (301=permanent, 302/303/307=temporary)" }, "preserveQueryString": { "type": "boolean", "description": "Whether to forward the original query string to the redirect target" }, "appendPath": { "type": "boolean", "description": "Whether to append the original request path to the redirect target" }, "description": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional note or label for this redirect" }, "active": { "type": "boolean", "description": "Whether the redirect is currently active. Inactive redirects do not process requests but remain fully configured and can be reactivated at any time via PATCH. To permanently remove a redirect, use DELETE instead." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the redirect was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the redirect was last updated" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this request" }, "status": { "type": "string", "enum": [ "completed", "queued", "partial_failure" ], "description": "Operation status" } } } }, "required": [ "data", "meta" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "A description of what went wrong" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "A description of what went wrong" } }, "required": [ "error" ] } } } }, "429": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" }, "description": "Maximum requests allowed per hour (e.g. \"5000\")" }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" }, "description": "Requests remaining in the current hourly window" }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" }, "description": "Maximum write operations (POST/PUT/DELETE) allowed per day (e.g. \"1000\")" }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" }, "description": "Write operations remaining in the current daily window" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "A description of which rate limit was exceeded" }, "secondsUntilReset": { "type": "integer", "description": "Seconds until the rate limit window resets" } }, "required": [ "error" ] } } } } } }, "delete": { "tags": [ "Redirects" ], "description": "Permanently removes a redirect. This action is irreversible. To disable without deleting, use PATCH with {\"active\": false} instead.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Permanently removes a redirect. This action is irreversible. To disable without deleting, use PATCH with {\"active\": false} instead.", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" }, "description": "Maximum requests allowed per hour (e.g. \"5000\")" }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" }, "description": "Requests remaining in the current hourly window" }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" }, "description": "Maximum write operations (POST/PUT/DELETE) allowed per day (e.g. \"1000\")" }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" }, "description": "Write operations remaining in the current daily window" } }, "content": { "application/json": { "schema": { "description": "Permanently removes a redirect. This action is irreversible. To disable without deleting, use PATCH with {\"active\": false} instead.", "type": "object", "properties": { "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the deletion was successful" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this request" } } } }, "required": [ "data", "meta" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "A description of what went wrong" } }, "required": [ "error" ] } } } }, "429": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" }, "description": "Maximum requests allowed per hour (e.g. \"5000\")" }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" }, "description": "Requests remaining in the current hourly window" }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" }, "description": "Maximum write operations (POST/PUT/DELETE) allowed per day (e.g. \"1000\")" }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" }, "description": "Write operations remaining in the current daily window" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "A description of which rate limit was exceeded" }, "secondsUntilReset": { "type": "integer", "description": "Seconds until the rate limit window resets" } }, "required": [ "error" ] } } } } } } }, "/v1/analytics/hosts": { "get": { "tags": [ "Analytics" ], "description": "Per-host analytics rollup: redirect count, hits, and average response time. Defaults to month-to-date when startDate/endDate are omitted.", "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "startDate", "required": false, "description": "UTC calendar date in YYYY-MM-DD format. Defaults to the first of the current month when omitted." }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "endDate", "required": false, "description": "UTC calendar date in YYYY-MM-DD format. Defaults to today when omitted." } ], "responses": { "200": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" } }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" } }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" } }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "hostId": { "type": "string", "format": "uuid", "description": "Unique host identifier" }, "hostname": { "type": "string", "description": "The domain name (e.g. \"example.com\")" }, "redirectCount": { "type": "integer", "minimum": 0, "description": "Total redirects configured on this host" }, "activeRedirectCount": { "type": "integer", "minimum": 0, "description": "Redirects on this host that are not archived" }, "totalHits": { "type": "integer", "minimum": 0, "description": "Total redirect hits served for this host in the date range" }, "avgResponseTimeMs": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "Average response time in milliseconds across all redirects on this host. Null when there were no hits." } }, "required": [ "hostId", "hostname", "redirectCount", "activeRedirectCount", "totalHits", "avgResponseTimeMs" ] }, "description": "Per-host rollup, ordered by total hits descending" }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this request" }, "status": { "type": "string", "enum": [ "completed" ], "description": "Operation status" }, "dateRange": { "type": "object", "properties": { "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "UTC calendar date in YYYY-MM-DD format. Defaults to the first of the current month when omitted." }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "UTC calendar date in YYYY-MM-DD format. Defaults to today when omitted." } }, "required": [ "startDate", "endDate" ], "description": "Resolved UTC date range for the response" } }, "required": [ "requestId", "status", "dateRange" ] } }, "required": [ "data", "meta" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" } }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" } }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" } }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "secondsUntilReset": { "type": "integer" } }, "required": [ "error" ] } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/v1/analytics/timeseries": { "get": { "tags": [ "Analytics" ], "description": "Hits over time across all redirects on the account. Defaults to month-to-date and daily granularity.", "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "startDate", "required": false, "description": "UTC calendar date in YYYY-MM-DD format. Defaults to the first of the current month when omitted." }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "endDate", "required": false, "description": "UTC calendar date in YYYY-MM-DD format. Defaults to today when omitted." }, { "schema": { "type": "string", "enum": [ "daily", "monthly" ], "default": "daily" }, "in": "query", "name": "granularity", "required": false, "description": "Bucket size for the returned series. Daily returns one row per UTC day; monthly returns one row per calendar month." } ], "responses": { "200": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" } }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" } }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" } }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "granularity": { "type": "string", "enum": [ "daily", "monthly" ] }, "points": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "Bucket start date in YYYY-MM-DD. For monthly granularity this is the first day of the month." }, "hits": { "type": "integer", "minimum": 0, "description": "Total redirect hits in this bucket" }, "uniqueRedirectsUsed": { "type": "integer", "minimum": 0, "description": "Distinct redirects that received at least one hit in this bucket" } }, "required": [ "date", "hits", "uniqueRedirectsUsed" ] }, "description": "Time-ordered series of buckets" } }, "required": [ "granularity", "points" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this request" }, "status": { "type": "string", "enum": [ "completed" ], "description": "Operation status" }, "dateRange": { "type": "object", "properties": { "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "UTC calendar date in YYYY-MM-DD format. Defaults to the first of the current month when omitted." }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "UTC calendar date in YYYY-MM-DD format. Defaults to today when omitted." } }, "required": [ "startDate", "endDate" ], "description": "Resolved UTC date range for the response" }, "granularity": { "type": "string", "enum": [ "daily", "monthly" ], "description": "Bucket size used for the time series" } }, "required": [ "requestId", "status", "dateRange", "granularity" ] } }, "required": [ "data", "meta" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" } }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" } }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" } }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "secondsUntilReset": { "type": "integer" } }, "required": [ "error" ] } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/v1/analytics/hosts/{id}/timeseries": { "get": { "tags": [ "Analytics" ], "description": "Hits over time for a single host (all of its redirects combined). Defaults to month-to-date and daily granularity.", "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "startDate", "required": false, "description": "UTC calendar date in YYYY-MM-DD format. Defaults to the first of the current month when omitted." }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "endDate", "required": false, "description": "UTC calendar date in YYYY-MM-DD format. Defaults to today when omitted." }, { "schema": { "type": "string", "enum": [ "daily", "monthly" ], "default": "daily" }, "in": "query", "name": "granularity", "required": false, "description": "Bucket size for the returned series. Daily returns one row per UTC day; monthly returns one row per calendar month." }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" } }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" } }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" } }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "granularity": { "type": "string", "enum": [ "daily", "monthly" ] }, "points": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "Bucket start date in YYYY-MM-DD. For monthly granularity this is the first day of the month." }, "hits": { "type": "integer", "minimum": 0, "description": "Total redirect hits in this bucket" }, "uniqueRedirectsUsed": { "type": "integer", "minimum": 0, "description": "Distinct redirects that received at least one hit in this bucket" } }, "required": [ "date", "hits", "uniqueRedirectsUsed" ] }, "description": "Time-ordered series of buckets" } }, "required": [ "granularity", "points" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this request" }, "status": { "type": "string", "enum": [ "completed" ], "description": "Operation status" }, "dateRange": { "type": "object", "properties": { "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "UTC calendar date in YYYY-MM-DD format. Defaults to the first of the current month when omitted." }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "UTC calendar date in YYYY-MM-DD format. Defaults to today when omitted." } }, "required": [ "startDate", "endDate" ], "description": "Resolved UTC date range for the response" }, "granularity": { "type": "string", "enum": [ "daily", "monthly" ], "description": "Bucket size used for the time series" } }, "required": [ "requestId", "status", "dateRange", "granularity" ] } }, "required": [ "data", "meta" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" } }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" } }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" } }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "secondsUntilReset": { "type": "integer" } }, "required": [ "error" ] } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/v1/analytics/redirects/{id}": { "get": { "tags": [ "Analytics" ], "description": "Detailed analytics for a single redirect: total hits, average response time, and a daily hit breakdown for the date range.", "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "startDate", "required": false, "description": "UTC calendar date in YYYY-MM-DD format. Defaults to the first of the current month when omitted." }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "endDate", "required": false, "description": "UTC calendar date in YYYY-MM-DD format. Defaults to today when omitted." }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" } }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" } }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" } }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "redirectId": { "type": "string", "format": "uuid", "description": "Unique redirect identifier" }, "description": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional description set on the redirect" }, "sourceHost": { "type": "string", "description": "Hostname this redirect is configured on" }, "sourcePath": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Path being matched (null for host-level catch-all redirects)" }, "destination": { "type": "string", "description": "Target URL the redirect sends traffic to" }, "status": { "type": "string", "enum": [ "Active", "Inactive" ], "description": "Active when the redirect is currently serving traffic; Inactive when archived" }, "totalHits": { "type": "integer", "minimum": 0, "description": "Total redirect hits in the date range" }, "avgResponseTimeMs": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "Average response time in milliseconds. Null when there were no hits." }, "dailyStats": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "UTC calendar date (YYYY-MM-DD)" }, "hits": { "type": "integer", "minimum": 0 } }, "required": [ "date", "hits" ] }, "description": "Daily hit counts for the redirect over the date range" } }, "required": [ "redirectId", "sourceHost", "sourcePath", "destination", "status", "totalHits", "avgResponseTimeMs", "dailyStats" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this request" }, "status": { "type": "string", "enum": [ "completed" ], "description": "Operation status" }, "dateRange": { "type": "object", "properties": { "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "UTC calendar date in YYYY-MM-DD format. Defaults to the first of the current month when omitted." }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "UTC calendar date in YYYY-MM-DD format. Defaults to today when omitted." } }, "required": [ "startDate", "endDate" ], "description": "Resolved UTC date range for the response" } }, "required": [ "requestId", "status", "dateRange" ] } }, "required": [ "data", "meta" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" } }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" } }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" } }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "secondsUntilReset": { "type": "integer" } }, "required": [ "error" ] } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/v1/analytics/redirects/{id}/timeseries": { "get": { "tags": [ "Analytics" ], "description": "Hits over time for a single redirect with configurable granularity. Defaults to month-to-date and daily granularity.", "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "startDate", "required": false, "description": "UTC calendar date in YYYY-MM-DD format. Defaults to the first of the current month when omitted." }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "endDate", "required": false, "description": "UTC calendar date in YYYY-MM-DD format. Defaults to today when omitted." }, { "schema": { "type": "string", "enum": [ "daily", "monthly" ], "default": "daily" }, "in": "query", "name": "granularity", "required": false, "description": "Bucket size for the returned series. Daily returns one row per UTC day; monthly returns one row per calendar month." }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" } }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" } }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" } }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "granularity": { "type": "string", "enum": [ "daily", "monthly" ] }, "points": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "Bucket start date in YYYY-MM-DD. For monthly granularity this is the first day of the month." }, "hits": { "type": "integer", "minimum": 0, "description": "Total redirect hits in this bucket" }, "uniqueRedirectsUsed": { "type": "integer", "minimum": 0, "description": "Distinct redirects that received at least one hit in this bucket" } }, "required": [ "date", "hits", "uniqueRedirectsUsed" ] }, "description": "Time-ordered series of buckets" } }, "required": [ "granularity", "points" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this request" }, "status": { "type": "string", "enum": [ "completed" ], "description": "Operation status" }, "dateRange": { "type": "object", "properties": { "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "UTC calendar date in YYYY-MM-DD format. Defaults to the first of the current month when omitted." }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "UTC calendar date in YYYY-MM-DD format. Defaults to today when omitted." } }, "required": [ "startDate", "endDate" ], "description": "Resolved UTC date range for the response" }, "granularity": { "type": "string", "enum": [ "daily", "monthly" ], "description": "Bucket size used for the time series" } }, "required": [ "requestId", "status", "dateRange", "granularity" ] } }, "required": [ "data", "meta" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Default Response", "headers": { "X-RateLimit-Requests-Limit": { "schema": { "type": "string" } }, "X-RateLimit-Requests-Remaining": { "schema": { "type": "string" } }, "X-RateLimit-Writes-Limit": { "schema": { "type": "string" } }, "X-RateLimit-Writes-Remaining": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "secondsUntilReset": { "type": "integer" } }, "required": [ "error" ] } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } } }, "servers": [ { "url": "https://api.redirectboss.com" } ], "security": [ { "apiKeyAuth": [] } ], "externalDocs": { "url": "https://redirectboss.com/docs", "description": "Full API documentation" }, "tags": [] }