{ "openapi": "3.1.1", "info": { "title": "HTML/CSS to Image API", "description": "Capture website screenshots, render HTML/CSS, or create templated graphics. Use MCP with AI, no-code automation, or the REST API. No browsers needed.", "version": "1.0.0" }, "servers": [ { "url": "https://hcti.io" } ], "paths": { "/v1/api-keys": { "post": { "tags": [ "API Keys" ], "summary": "Create an API key", "description": "Creates a key with explicit permissions no broader than the calling key's current grants. Save api_key securely: only this response includes the secret.\n\n**Rate limit:** 20 requests per minute per organization, shared across all operations in the `api-key:write` group and all API keys belonging to that organization.", "operationId": "create-api-key", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrUpdateApiKeyRequest" } } }, "required": true }, "responses": { "429": { "description": "Too Many Requests", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"api-key:write\";q=20;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"api-key:write\";r=0" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "200": { "description": "OK", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"api-key:write\";q=20;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"api-key:write\";r=19" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyWithSecret" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires api_keys:create_update", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "api_keys:create_update" ], "x-rate-limit": { "group": "api-key:write", "limit": 20, "window_seconds": 60, "scope": "organization" } }, "get": { "tags": [ "API Keys" ], "summary": "List API keys", "description": "Returns keys in descending creation order. Disabled keys are excluded unless include_disabled=true. with_permission filters use all-of matching. Follow pagination.next_page_start until null. Secrets are never returned.\n\n**Rate limit:** 100 requests per minute per organization, shared across all operations in the `api-key:read` group and all API keys belonging to that organization.", "operationId": "list-api-keys", "parameters": [ { "name": "count", "in": "query", "description": "Maximum number of keys to return, from 1 to 100. Defaults to 10.", "schema": { "maximum": 100, "minimum": 1, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 10 } }, { "name": "page_start", "in": "query", "description": "pagination.next_page_start from the previous response. Omit for the first page.", "schema": { "type": "string" } }, { "name": "include_disabled", "in": "query", "description": "Include disabled keys. Defaults to false.", "schema": { "type": "boolean", "default": false } }, { "name": "with_permission", "in": "query", "description": "Return keys allowing every specified permission, including wildcard grants. Repeat this query parameter for multiple permissions; do not separate names with spaces or commas.", "schema": { "type": "array", "items": { "enum": [ "api_keys:create_update", "api_keys:delete", "api_keys:read", "images:create", "images:delete", "images:read", "images:store", "og_configs:create_update", "og_configs:delete", "og_configs:read", "proxies:create_update", "proxies:delete", "proxies:read", "storage_destinations:create_update", "storage_destinations:delete", "storage_destinations:read", "templates:create_update", "templates:delete", "templates:read", "usage:read" ], "type": "string" } } } ], "responses": { "429": { "description": "Too Many Requests", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"api-key:read\";q=100;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"api-key:read\";r=0" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "200": { "description": "OK", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"api-key:read\";q=100;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"api-key:read\";r=99" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedListBaseOfApiKeyAndstring" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires api_keys:read", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "api_keys:read" ], "x-rate-limit": { "group": "api-key:read", "limit": 100, "window_seconds": 60, "scope": "organization" } } }, "/v1/api-keys/{id}": { "post": { "tags": [ "API Keys" ], "summary": "Update an API key", "description": "Replaces the key's name, description, disabled state, and permissions. The caller must be able to grant both the existing and requested permissions. This also applies when disabling or re-enabling a key. Does not rotate or return the secret. Use id, not api_id.\n\n**Rate limit:** 20 requests per minute per organization, shared across all operations in the `api-key:write` group and all API keys belonging to that organization.", "operationId": "update-api-key", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrUpdateApiKeyRequest" } } }, "required": true }, "responses": { "429": { "description": "Too Many Requests", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"api-key:write\";q=20;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"api-key:write\";r=0" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "200": { "description": "OK", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"api-key:write\";q=20;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"api-key:write\";r=19" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires api_keys:create_update", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "api_keys:create_update" ], "x-rate-limit": { "group": "api-key:write", "limit": 20, "window_seconds": 60, "scope": "organization" } }, "get": { "tags": [ "API Keys" ], "summary": "Get an API key", "description": "Returns the key's metadata and permissions, including for disabled keys. Does not return the secret. Use id, not api_id.\n\n**Rate limit:** 100 requests per minute per organization, shared across all operations in the `api-key:read` group and all API keys belonging to that organization.", "operationId": "get-api-key", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "429": { "description": "Too Many Requests", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"api-key:read\";q=100;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"api-key:read\";r=0" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "200": { "description": "OK", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"api-key:read\";q=100;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"api-key:read\";r=99" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires api_keys:read", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "api_keys:read" ], "x-rate-limit": { "group": "api-key:read", "limit": 100, "window_seconds": 60, "scope": "organization" } }, "delete": { "tags": [ "API Keys" ], "summary": "Delete an API key", "description": "Disables the API key; it is not permanently deleted. The caller must be able to grant all of the key's existing permissions. The key remains retrievable and appears in list results with include_disabled=true. It can be re-enabled through update, subject to permission checks. Deleting an already disabled key succeeds when authorized. Use id, not api_id.\n\n**Rate limit:** 20 requests per minute per organization, shared across all operations in the `api-key:write` group and all API keys belonging to that organization.", "operationId": "delete-api-key", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "429": { "description": "Too Many Requests", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"api-key:write\";q=20;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"api-key:write\";r=0" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "204": { "description": "No Content", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"api-key:write\";q=20;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"api-key:write\";r=19" } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires api_keys:delete", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "api_keys:delete" ], "x-rate-limit": { "group": "api-key:write", "limit": 20, "window_seconds": 60, "scope": "organization" } } }, "/v1/image": { "post": { "tags": [ "Images" ], "summary": "Create an image", "operationId": "create-image", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageRequest" } }, "multipart/form-data": { "schema": { "type": "object", "anyOf": [ { "$ref": "#/components/schemas/ImageRequestImageRequest_HtmlCss" }, { "title": "URL Image Request", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Public HTTP or HTTPS URL to capture. Required for URL image requests." }, "css": { "type": [ "null", "string" ], "description": "CSS injected into the loaded URL to override styles on the page." }, "device_scale": { "maximum": 3, "minimum": 0.1, "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "description": "Adjusts the pixel ratio used for the screenshot. Minimum: 0.1. Maximum: 3. HTML and template renders default to 2; URL renders default to 1.", "format": "double" }, "full_screen": { "type": [ "null", "boolean" ], "description": "Take a screenshot of the entire screen after scrolling down and back to the top." }, "max_wait_ms": { "maximum": 10000, "minimum": 500, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Sets a limit on how long to wait before taking the screenshot when the page continues loading irrelevant content. Minimum: 500. Maximum: 10000 and subject to the account plan limit.", "format": "int32" }, "metadata": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "Custom key-value metadata stored with the image." }, "ms_delay": { "maximum": 10000, "minimum": 0, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Adds extra time in milliseconds before taking the screenshot so JavaScript can execute. Minimum: 0. Maximum: 10000.", "format": "int32", "default": 0 }, "render_when_ready": { "type": [ "null", "boolean" ], "description": "Waits until the page signals that the screenshot is ready. The image fails if the readiness signal is never sent." }, "selector": { "type": [ "null", "string" ], "description": "A CSS selector for an element in the HTML. We’ll crop the image to this specific element." }, "viewport_height": { "maximum": 6000, "minimum": 1, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Sets the height of Chrome's viewport and disables automatic cropping. Minimum: 1. Maximum: 6000. Both viewport dimensions must be supplied together.", "format": "int32" }, "viewport_width": { "maximum": 6000, "minimum": 1, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Sets the width of Chrome's viewport and disables automatic cropping. Minimum: 1. Maximum: 6000. Both viewport dimensions must be supplied together.", "format": "int32" }, "pdf_options": { "oneOf": [ { "type": "null" }, { "description": "Options used when generating a PDF instead of an image. Page dimensions and margins must include supported PDF units; margins must contain either zero or four values; scale must be between 0.1 and 2.", "$ref": "#/components/schemas/PDFOptions" } ] }, "disable_twemoji": { "type": [ "null", "boolean" ], "description": "Set explicitly to false to inject Twemoji into the loaded page. Omitted, null, or true leaves the page's emoji handling unchanged and does not disable the website's own emoji scripts." }, "dedupe_duration_s": { "maximum": 31536000, "minimum": 0, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Reuse an existing image with identical content if it was created within this many seconds. Minimum: 0. Maximum: 31536000. Availability and maximum effective duration depend on the account plan.", "format": "int32" }, "max_render_once": { "type": [ "null", "boolean" ], "description": "Ensure the image is only ever rendered and saved one time. This is an advanced option not applicable to most requests." }, "color_scheme": { "oneOf": [ { "type": "null" }, { "description": "Sets Chrome's preferred color scheme. Valid values: light or dark.", "$ref": "#/components/schemas/ColorSchemeType" } ] }, "timezone": { "type": [ "null", "string" ], "description": "Sets the IANA timezone used by Chrome while rendering. Must be a recognized IANA timezone identifier." }, "block_consent_banners": { "type": [ "null", "boolean" ], "description": "Attempt to block cookie/consent banners from displaying." }, "identify_as_hcti": { "type": [ "null", "boolean" ], "description": "Identify the top-level page navigation as an HCTI screenshot request using the X-HCTI-SCREENSHOT header." }, "headers": { "type": "array", "items": { "pattern": "^[^:]+:.*$", "type": "string", "description": "A header encoded as name:value. The first colon separates the name from the value." }, "description": "HTTP headers to include on top-level page navigations to the requested URL's origin and any additional_header_origins. Supports up to 20 headers with names up to 512 ASCII characters and values up to 8192 UTF-8 bytes. For GET and form-encoded requests, repeat this parameter using the format `headers=name:value`." }, "additional_header_origins": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Additional exact HTTP or HTTPS origins allowed to receive custom headers. Supports up to 20 unique origins of up to 512 UTF-8 bytes each. Origins must use the format scheme://host[:port] without a path; duplicates are ignored. For GET and form-encoded requests, repeat this parameter for each origin." }, "include_headers_on_subrequests": { "type": [ "null", "boolean" ], "description": "Include custom headers on subrequests to the requested URL's origin and any additional_header_origins. Defaults to false. Requires at least one header." }, "viewport_mobile": { "type": [ "null", "boolean" ], "description": "Specifies whether the page uses mobile viewport behavior, including its viewport meta tag." }, "viewport_landscape": { "type": [ "null", "boolean" ], "description": "Specifies whether the emulated viewport is in landscape orientation." }, "viewport_touch": { "type": [ "null", "boolean" ], "description": "Specifies whether the emulated viewport supports touch events." }, "media_type": { "oneOf": [ { "type": "null" }, { "description": "Sets the CSS media type used while rendering the page. Valid values: print or screen.", "$ref": "#/components/schemas/MediaType" } ] }, "proxy_id": { "type": [ "null", "string" ], "description": "Specifies which configured organization proxy to use when rendering." }, "storage_destination_id": { "type": [ "null", "string" ], "description": "Specifies which configured organization storage destination receives the rendered image." }, "jumbo_max_height": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Maximum height of the rendered image in jumbo mode. Jumbo rendering consumes additional renders and requires jumbo_max_width. Supply both jumbo dimensions. Each must be greater than 0 and no more than 80000; at least one must exceed 8000; total area cannot exceed 400000000 pixels.", "format": "int32" }, "jumbo_max_width": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Maximum width of the rendered image in jumbo mode. Jumbo rendering consumes additional renders and requires jumbo_max_height. Supply both jumbo dimensions. Each must be greater than 0 and no more than 80000; at least one must exceed 8000; total area cannot exceed 400000000 pixels.", "format": "int32" }, "transparent_background": { "type": [ "null", "boolean" ], "description": "Specifies whether the image is rendered with a transparent background." }, "format": { "oneOf": [ { "type": "null" }, { "description": "Sets the file extension on the URL returned by the image creation request. It does not change the stored source image or restrict later rendering to this format. Valid values: png, jpg, jpeg, webp, or pdf. This parameter is accepted only in POST request bodies.", "$ref": "#/components/schemas/ImageFormat" } ] }, "request_overrides": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/RequestOverride" }, "description": "Rules that override browser network requests. The block action blocks requests matching a URL wildcard pattern and/or resource types. When both matchers are supplied, both must match. A request is blocked if any block rule matches. Omitted, null, or an empty array adds no overrides. Requires a paid plan. Accepts a JSON array in JSON requests or a JSON-encoded array string in form requests. Maximum 100 rules and 512 characters per URL pattern. Each block rule requires a nonempty URL pattern or at least one resource type; supplied matchers cannot be empty. Not supported in query strings." } } }, { "$ref": "#/components/schemas/ImageRequestImageRequest_Templated" } ], "discriminator": { "propertyName": "$type" } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "anyOf": [ { "$ref": "#/components/schemas/ImageRequestImageRequest_HtmlCss" }, { "title": "URL Image Request", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Public HTTP or HTTPS URL to capture. Required for URL image requests." }, "css": { "type": [ "null", "string" ], "description": "CSS injected into the loaded URL to override styles on the page." }, "device_scale": { "maximum": 3, "minimum": 0.1, "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "description": "Adjusts the pixel ratio used for the screenshot. Minimum: 0.1. Maximum: 3. HTML and template renders default to 2; URL renders default to 1.", "format": "double" }, "full_screen": { "type": [ "null", "boolean" ], "description": "Take a screenshot of the entire screen after scrolling down and back to the top." }, "max_wait_ms": { "maximum": 10000, "minimum": 500, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Sets a limit on how long to wait before taking the screenshot when the page continues loading irrelevant content. Minimum: 500. Maximum: 10000 and subject to the account plan limit.", "format": "int32" }, "metadata": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "Custom key-value metadata stored with the image." }, "ms_delay": { "maximum": 10000, "minimum": 0, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Adds extra time in milliseconds before taking the screenshot so JavaScript can execute. Minimum: 0. Maximum: 10000.", "format": "int32", "default": 0 }, "render_when_ready": { "type": [ "null", "boolean" ], "description": "Waits until the page signals that the screenshot is ready. The image fails if the readiness signal is never sent." }, "selector": { "type": [ "null", "string" ], "description": "A CSS selector for an element in the HTML. We’ll crop the image to this specific element." }, "viewport_height": { "maximum": 6000, "minimum": 1, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Sets the height of Chrome's viewport and disables automatic cropping. Minimum: 1. Maximum: 6000. Both viewport dimensions must be supplied together.", "format": "int32" }, "viewport_width": { "maximum": 6000, "minimum": 1, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Sets the width of Chrome's viewport and disables automatic cropping. Minimum: 1. Maximum: 6000. Both viewport dimensions must be supplied together.", "format": "int32" }, "pdf_options": { "oneOf": [ { "type": "null" }, { "description": "Options used when generating a PDF instead of an image. Page dimensions and margins must include supported PDF units; margins must contain either zero or four values; scale must be between 0.1 and 2.", "$ref": "#/components/schemas/PDFOptions" } ] }, "disable_twemoji": { "type": [ "null", "boolean" ], "description": "Set explicitly to false to inject Twemoji into the loaded page. Omitted, null, or true leaves the page's emoji handling unchanged and does not disable the website's own emoji scripts." }, "dedupe_duration_s": { "maximum": 31536000, "minimum": 0, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Reuse an existing image with identical content if it was created within this many seconds. Minimum: 0. Maximum: 31536000. Availability and maximum effective duration depend on the account plan.", "format": "int32" }, "max_render_once": { "type": [ "null", "boolean" ], "description": "Ensure the image is only ever rendered and saved one time. This is an advanced option not applicable to most requests." }, "color_scheme": { "oneOf": [ { "type": "null" }, { "description": "Sets Chrome's preferred color scheme. Valid values: light or dark.", "$ref": "#/components/schemas/ColorSchemeType" } ] }, "timezone": { "type": [ "null", "string" ], "description": "Sets the IANA timezone used by Chrome while rendering. Must be a recognized IANA timezone identifier." }, "block_consent_banners": { "type": [ "null", "boolean" ], "description": "Attempt to block cookie/consent banners from displaying." }, "identify_as_hcti": { "type": [ "null", "boolean" ], "description": "Identify the top-level page navigation as an HCTI screenshot request using the X-HCTI-SCREENSHOT header." }, "headers": { "type": "array", "items": { "pattern": "^[^:]+:.*$", "type": "string", "description": "A header encoded as name:value. The first colon separates the name from the value." }, "description": "HTTP headers to include on top-level page navigations to the requested URL's origin and any additional_header_origins. Supports up to 20 headers with names up to 512 ASCII characters and values up to 8192 UTF-8 bytes. For GET and form-encoded requests, repeat this parameter using the format `headers=name:value`." }, "additional_header_origins": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Additional exact HTTP or HTTPS origins allowed to receive custom headers. Supports up to 20 unique origins of up to 512 UTF-8 bytes each. Origins must use the format scheme://host[:port] without a path; duplicates are ignored. For GET and form-encoded requests, repeat this parameter for each origin." }, "include_headers_on_subrequests": { "type": [ "null", "boolean" ], "description": "Include custom headers on subrequests to the requested URL's origin and any additional_header_origins. Defaults to false. Requires at least one header." }, "viewport_mobile": { "type": [ "null", "boolean" ], "description": "Specifies whether the page uses mobile viewport behavior, including its viewport meta tag." }, "viewport_landscape": { "type": [ "null", "boolean" ], "description": "Specifies whether the emulated viewport is in landscape orientation." }, "viewport_touch": { "type": [ "null", "boolean" ], "description": "Specifies whether the emulated viewport supports touch events." }, "media_type": { "oneOf": [ { "type": "null" }, { "description": "Sets the CSS media type used while rendering the page. Valid values: print or screen.", "$ref": "#/components/schemas/MediaType" } ] }, "proxy_id": { "type": [ "null", "string" ], "description": "Specifies which configured organization proxy to use when rendering." }, "storage_destination_id": { "type": [ "null", "string" ], "description": "Specifies which configured organization storage destination receives the rendered image." }, "jumbo_max_height": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Maximum height of the rendered image in jumbo mode. Jumbo rendering consumes additional renders and requires jumbo_max_width. Supply both jumbo dimensions. Each must be greater than 0 and no more than 80000; at least one must exceed 8000; total area cannot exceed 400000000 pixels.", "format": "int32" }, "jumbo_max_width": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Maximum width of the rendered image in jumbo mode. Jumbo rendering consumes additional renders and requires jumbo_max_height. Supply both jumbo dimensions. Each must be greater than 0 and no more than 80000; at least one must exceed 8000; total area cannot exceed 400000000 pixels.", "format": "int32" }, "transparent_background": { "type": [ "null", "boolean" ], "description": "Specifies whether the image is rendered with a transparent background." }, "format": { "oneOf": [ { "type": "null" }, { "description": "Sets the file extension on the URL returned by the image creation request. It does not change the stored source image or restrict later rendering to this format. Valid values: png, jpg, jpeg, webp, or pdf. This parameter is accepted only in POST request bodies.", "$ref": "#/components/schemas/ImageFormat" } ] }, "request_overrides": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/RequestOverride" }, "description": "Rules that override browser network requests. The block action blocks requests matching a URL wildcard pattern and/or resource types. When both matchers are supplied, both must match. A request is blocked if any block rule matches. Omitted, null, or an empty array adds no overrides. Requires a paid plan. Accepts a JSON array in JSON requests or a JSON-encoded array string in form requests. Maximum 100 rules and 512 characters per URL pattern. Each block rule requires a nonempty URL pattern or at least one resource type; supplied matchers cannot be empty. Not supported in query strings." } } }, { "$ref": "#/components/schemas/ImageRequestImageRequest_Templated" } ], "discriminator": { "propertyName": "$type" } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageResultWithId" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires images:create", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "images:create" ] } }, "/v1/image/{id}": { "get": { "tags": [ "Images" ], "summary": "Render an image", "operationId": "render-image", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "width", "in": "query", "description": "Width to resize the rendered image", "schema": { "maximum": 5000, "minimum": 1, "type": [ "null", "integer" ], "format": "int32" } }, { "name": "height", "in": "query", "description": "Height to resize the rendered image", "schema": { "maximum": 5000, "minimum": 1, "type": [ "null", "integer" ], "format": "int32" } }, { "name": "dpi", "in": "query", "description": "DPI to specify in rendered image's metadata.", "schema": { "maximum": 600, "minimum": 30, "type": [ "null", "integer" ], "format": "int32" } }, { "name": "dl", "in": "query", "description": "Add this to cause the rendered image to be downloaded as a file instead of being displayed", "schema": { "enum": [ "1", "0" ], "type": [ "null", "string" ], "default": "0" } }, { "name": "aspect_ratio", "in": "query", "description": "Define an aspect ratio to crop the rendered image to. Specify the value as x_y. When using aspect_ratio, you must include one of: [x_1 & x_2], [y_1 & y_2], [x_1 & crop_width], [y_1 & crop_height], [crop_width] or [crop_height].", "schema": { "type": [ "null", "string" ] } }, { "name": "x_origin", "in": "query", "description": "Define the origin for cropping along the x axis. When using aspect_ratio, you can only specify one of x_origin or y_origin.", "schema": { "pattern": "^-?\\d+(\\.\\d+)?(%|px)?$", "type": [ "null", "string" ] }, "examples": { "Numeric": { "description": "Numbers without a unit specified are assumed to be pixel measurements.", "value": 159 }, "PX": { "description": "230 px", "value": "230px" }, "Percentage": { "description": "71%", "value": "71%" }, "NegativeNumeric": { "description": "Negative numbers without a unit specified are assumed to be pixel measurements from the end of the axis.", "value": -88 }, "NegativePX": { "description": "230 px from the end of the axis.", "value": "-230px" } } }, { "name": "y_origin", "in": "query", "description": "Define the origin for cropping along the y axis. When using aspect_ratio, you can only specify one of x_origin or y_origin.", "schema": { "pattern": "^-?\\d+(\\.\\d+)?(%|px)?$", "type": [ "null", "string" ] }, "examples": { "Numeric": { "description": "Numbers without a unit specified are assumed to be pixel measurements.", "value": 72 }, "PX": { "description": "160 px", "value": "160px" }, "Percentage": { "description": "88%", "value": "88%" }, "NegativeNumeric": { "description": "Negative numbers without a unit specified are assumed to be pixel measurements from the end of the axis.", "value": -16 }, "NegativePX": { "description": "160 px from the end of the axis.", "value": "-160px" } } }, { "name": "x_1", "in": "query", "description": "Define the x_1 position for cropping. You can specify either x_1 & x_2 or x_1 and crop_width.", "schema": { "pattern": "^-?\\d+(\\.\\d+)?(%|px)?$", "type": [ "null", "string" ] }, "examples": { "Numeric": { "description": "Numbers without a unit specified are assumed to be pixel measurements.", "value": 145 }, "PX": { "description": "222 px", "value": "222px" }, "Percentage": { "description": "77%", "value": "77%" }, "NegativeNumeric": { "description": "Negative numbers without a unit specified are assumed to be pixel measurements from the end of the axis.", "value": -68 }, "NegativePX": { "description": "222 px from the end of the axis.", "value": "-222px" } } }, { "name": "x_2", "in": "query", "description": "Define the x_2 position for cropping. Cannot be specified with crop_width, and must have an x_1 specified.", "schema": { "pattern": "^-?\\d+(\\.\\d+)?(%|px)?$", "type": [ "null", "string" ] }, "examples": { "Numeric": { "description": "Numbers without a unit specified are assumed to be pixel measurements.", "value": 231 }, "PX": { "description": "242 px", "value": "242px" }, "Percentage": { "description": "11%", "value": "11%" }, "NegativeNumeric": { "description": "Negative numbers without a unit specified are assumed to be pixel measurements from the end of the axis.", "value": -220 }, "NegativePX": { "description": "242 px from the end of the axis.", "value": "-242px" } } }, { "name": "y_1", "in": "query", "description": "Define the y_1 position for cropping. You can specify either y_1 & y_2 or y_1 and crop_height.", "schema": { "pattern": "^-?\\d+(\\.\\d+)?(%|px)?$", "type": [ "null", "string" ] }, "examples": { "Numeric": { "description": "Numbers without a unit specified are assumed to be pixel measurements.", "value": 123 }, "PX": { "description": "168 px", "value": "168px" }, "Percentage": { "description": "45%", "value": "45%" }, "NegativeNumeric": { "description": "Negative numbers without a unit specified are assumed to be pixel measurements from the end of the axis.", "value": -78 }, "NegativePX": { "description": "168 px from the end of the axis.", "value": "-168px" } } }, { "name": "y_2", "in": "query", "description": "Define the y_2 position for cropping. Cannot be specified with crop_height, and must have a y_1 specified.", "schema": { "pattern": "^-?\\d+(\\.\\d+)?(%|px)?$", "type": [ "null", "string" ] }, "examples": { "Numeric": { "description": "Numbers without a unit specified are assumed to be pixel measurements.", "value": 100 }, "PX": { "description": "133 px", "value": "133px" }, "Percentage": { "description": "33%", "value": "33%" }, "NegativeNumeric": { "description": "Negative numbers without a unit specified are assumed to be pixel measurements from the end of the axis.", "value": -67 }, "NegativePX": { "description": "133 px from the end of the axis.", "value": "-133px" } } }, { "name": "crop_width", "in": "query", "description": "Define the width for cropping. Cannot be specified with crop_height, and must have a x_1 specified.", "schema": { "pattern": "^\\d+(\\.\\d+)?(%|px)?$", "type": [ "null", "string" ], "description": "Use either a number, a percentage like 30.5% or a px measure like 100px." }, "examples": { "Numeric": { "description": "Numbers without a unit specified are assumed to be pixel measurements.", "value": 19 }, "PX": { "description": "100 px wide", "value": "100px" }, "Percentage": { "description": "81% of the image's width", "value": "81%" } } }, { "name": "crop_height", "in": "query", "description": "Define the x_2 position for cropping. Cannot be specified with crop_width, and must have a y_1 specified.", "schema": { "pattern": "^\\d+(\\.\\d+)?(%|px)?$", "type": [ "null", "string" ] }, "examples": { "Numeric": { "description": "Numbers without a unit specified are assumed to be pixel measurements.", "value": 44 }, "PX": { "description": "96 px high", "value": "96px" }, "Percentage": { "description": "52% of the image's height", "value": "52%" } } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "410": { "description": "Gone", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "408": { "description": "Request Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "security": [ ] }, "delete": { "tags": [ "Images" ], "summary": "Delete an image", "operationId": "delete-image", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted" }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires images:delete", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "images:delete" ] } }, "/v1/image/{id}.{format}": { "get": { "tags": [ "Images" ], "summary": "Render an image with a specific format", "operationId": "render-image-format", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "path", "required": true, "schema": { "enum": [ "png", "jpg", "jpeg", "webp", "pdf" ], "type": "string" } }, { "name": "width", "in": "query", "description": "Width to resize the rendered image", "schema": { "maximum": 5000, "minimum": 1, "type": [ "null", "integer" ], "format": "int32" } }, { "name": "height", "in": "query", "description": "Height to resize the rendered image", "schema": { "maximum": 5000, "minimum": 1, "type": [ "null", "integer" ], "format": "int32" } }, { "name": "dpi", "in": "query", "description": "DPI to specify in rendered image's metadata.", "schema": { "maximum": 600, "minimum": 30, "type": [ "null", "integer" ], "format": "int32" } }, { "name": "dl", "in": "query", "description": "Add this to cause the rendered image to be downloaded as a file instead of being displayed", "schema": { "enum": [ "1", "0" ], "type": [ "null", "string" ], "default": "0" } }, { "name": "aspect_ratio", "in": "query", "description": "Define an aspect ratio to crop the rendered image to. Specify the value as x_y. When using aspect_ratio, you must include one of: [x_1 & x_2], [y_1 & y_2], [x_1 & crop_width], [y_1 & crop_height], [crop_width] or [crop_height].", "schema": { "type": [ "null", "string" ] } }, { "name": "x_origin", "in": "query", "description": "Define the origin for cropping along the x axis. When using aspect_ratio, you can only specify one of x_origin or y_origin.", "schema": { "pattern": "^-?\\d+(\\.\\d+)?(%|px)?$", "type": [ "null", "string" ] }, "examples": { "Numeric": { "description": "Numbers without a unit specified are assumed to be pixel measurements.", "value": 159 }, "PX": { "description": "230 px", "value": "230px" }, "Percentage": { "description": "71%", "value": "71%" }, "NegativeNumeric": { "description": "Negative numbers without a unit specified are assumed to be pixel measurements from the end of the axis.", "value": -88 }, "NegativePX": { "description": "230 px from the end of the axis.", "value": "-230px" } } }, { "name": "y_origin", "in": "query", "description": "Define the origin for cropping along the y axis. When using aspect_ratio, you can only specify one of x_origin or y_origin.", "schema": { "pattern": "^-?\\d+(\\.\\d+)?(%|px)?$", "type": [ "null", "string" ] }, "examples": { "Numeric": { "description": "Numbers without a unit specified are assumed to be pixel measurements.", "value": 72 }, "PX": { "description": "160 px", "value": "160px" }, "Percentage": { "description": "88%", "value": "88%" }, "NegativeNumeric": { "description": "Negative numbers without a unit specified are assumed to be pixel measurements from the end of the axis.", "value": -16 }, "NegativePX": { "description": "160 px from the end of the axis.", "value": "-160px" } } }, { "name": "x_1", "in": "query", "description": "Define the x_1 position for cropping. You can specify either x_1 & x_2 or x_1 and crop_width.", "schema": { "pattern": "^-?\\d+(\\.\\d+)?(%|px)?$", "type": [ "null", "string" ] }, "examples": { "Numeric": { "description": "Numbers without a unit specified are assumed to be pixel measurements.", "value": 145 }, "PX": { "description": "222 px", "value": "222px" }, "Percentage": { "description": "77%", "value": "77%" }, "NegativeNumeric": { "description": "Negative numbers without a unit specified are assumed to be pixel measurements from the end of the axis.", "value": -68 }, "NegativePX": { "description": "222 px from the end of the axis.", "value": "-222px" } } }, { "name": "x_2", "in": "query", "description": "Define the x_2 position for cropping. Cannot be specified with crop_width, and must have an x_1 specified.", "schema": { "pattern": "^-?\\d+(\\.\\d+)?(%|px)?$", "type": [ "null", "string" ] }, "examples": { "Numeric": { "description": "Numbers without a unit specified are assumed to be pixel measurements.", "value": 231 }, "PX": { "description": "242 px", "value": "242px" }, "Percentage": { "description": "11%", "value": "11%" }, "NegativeNumeric": { "description": "Negative numbers without a unit specified are assumed to be pixel measurements from the end of the axis.", "value": -220 }, "NegativePX": { "description": "242 px from the end of the axis.", "value": "-242px" } } }, { "name": "y_1", "in": "query", "description": "Define the y_1 position for cropping. You can specify either y_1 & y_2 or y_1 and crop_height.", "schema": { "pattern": "^-?\\d+(\\.\\d+)?(%|px)?$", "type": [ "null", "string" ] }, "examples": { "Numeric": { "description": "Numbers without a unit specified are assumed to be pixel measurements.", "value": 123 }, "PX": { "description": "168 px", "value": "168px" }, "Percentage": { "description": "45%", "value": "45%" }, "NegativeNumeric": { "description": "Negative numbers without a unit specified are assumed to be pixel measurements from the end of the axis.", "value": -78 }, "NegativePX": { "description": "168 px from the end of the axis.", "value": "-168px" } } }, { "name": "y_2", "in": "query", "description": "Define the y_2 position for cropping. Cannot be specified with crop_height, and must have a y_1 specified.", "schema": { "pattern": "^-?\\d+(\\.\\d+)?(%|px)?$", "type": [ "null", "string" ] }, "examples": { "Numeric": { "description": "Numbers without a unit specified are assumed to be pixel measurements.", "value": 100 }, "PX": { "description": "133 px", "value": "133px" }, "Percentage": { "description": "33%", "value": "33%" }, "NegativeNumeric": { "description": "Negative numbers without a unit specified are assumed to be pixel measurements from the end of the axis.", "value": -67 }, "NegativePX": { "description": "133 px from the end of the axis.", "value": "-133px" } } }, { "name": "crop_width", "in": "query", "description": "Define the width for cropping. Cannot be specified with crop_height, and must have a x_1 specified.", "schema": { "pattern": "^\\d+(\\.\\d+)?(%|px)?$", "type": [ "null", "string" ], "description": "Use either a number, a percentage like 30.5% or a px measure like 100px." }, "examples": { "Numeric": { "description": "Numbers without a unit specified are assumed to be pixel measurements.", "value": 19 }, "PX": { "description": "100 px wide", "value": "100px" }, "Percentage": { "description": "81% of the image's width", "value": "81%" } } }, { "name": "crop_height", "in": "query", "description": "Define the x_2 position for cropping. Cannot be specified with crop_width, and must have a y_1 specified.", "schema": { "pattern": "^\\d+(\\.\\d+)?(%|px)?$", "type": [ "null", "string" ] }, "examples": { "Numeric": { "description": "Numbers without a unit specified are assumed to be pixel measurements.", "value": 44 }, "PX": { "description": "96 px high", "value": "96px" }, "Percentage": { "description": "52% of the image's height", "value": "52%" } } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "410": { "description": "Gone", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "408": { "description": "Request Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "security": [ ] } }, "/v1/image/batch": { "post": { "tags": [ "Images" ], "summary": "Create a batch of images", "operationId": "create-image-batch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchImageRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchImageResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires images:create", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "images:create" ] }, "delete": { "tags": [ "Images" ], "summary": "Delete a batch of images", "operationId": "delete-image-batch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchDeleteRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires images:delete", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "images:delete" ] } }, "/v1/image/create-and-render/{api_id}/{token}/{format}": { "get": { "tags": [ "Images" ], "summary": "Create and render an image", "operationId": "create-and-render", "parameters": [ { "name": "api_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "token", "in": "path", "description": "An HMAC encoded token of your API key and the parameters specified in your query params. See https://docs.htmlcsstoimage.com/getting-started/create-and-render/#understanding-hmac-authentication for more information.", "required": true, "schema": { "title": "Token", "type": "string" } }, { "name": "format", "in": "path", "description": "The format of the image to return. If this field is omitted, it defaults to `png`.", "schema": { "title": "Format", "enum": [ "png", "jpg", "webp", "pdf" ], "type": [ "null", "string" ], "default": "png" } }, { "name": "css", "in": "query", "description": "CSS used to style the rendered HTML.", "schema": { "type": [ "null", "string" ] } }, { "name": "device_scale", "in": "query", "description": "Adjusts the pixel ratio used for the screenshot.", "schema": { "maximum": 3, "minimum": 0.1, "type": [ "null", "number" ], "format": "double" } }, { "name": "full_screen", "in": "query", "description": "Take a screenshot of the entire screen after scrolling down and back to the top.", "schema": { "type": [ "null", "boolean" ] } }, { "name": "google_fonts", "in": "query", "description": "Google fonts to load. Separate multiple fonts with a pipe, such as 'Roboto|OpenSans', and set font-family in the CSS to use them.", "schema": { "type": [ "null", "string" ] } }, { "name": "html", "in": "query", "description": "HTML to render and take a screenshot of. HTML fragments are rendered in a wrapper document unless a complete HTML document is supplied.", "schema": { "type": [ "null", "string" ] } }, { "name": "max_wait_ms", "in": "query", "description": "Sets a limit on how long to wait before taking the screenshot when the page continues loading irrelevant content.", "schema": { "maximum": 10000, "minimum": 500, "type": [ "null", "integer" ], "format": "int32" } }, { "name": "ms_delay", "in": "query", "description": "Adds extra time in milliseconds before taking the screenshot so JavaScript can execute.", "schema": { "maximum": 10000, "minimum": 0, "type": [ "null", "integer" ], "format": "int32" } }, { "name": "render_when_ready", "in": "query", "description": "Waits until the page signals that the screenshot is ready. The image fails if the readiness signal is never sent.", "schema": { "type": [ "null", "boolean" ] } }, { "name": "selector", "in": "query", "description": "A CSS selector for an element in the HTML. We’ll crop the image to this specific element.", "schema": { "type": [ "null", "string" ] } }, { "name": "url", "in": "query", "description": "Public HTTP or HTTPS URL to capture.", "schema": { "type": [ "null", "string" ] } }, { "name": "viewport_height", "in": "query", "description": "Sets the height of Chrome's viewport and disables automatic cropping.", "schema": { "maximum": 6000, "minimum": 1, "type": [ "null", "integer" ], "format": "int32" } }, { "name": "viewport_width", "in": "query", "description": "Sets the width of Chrome's viewport and disables automatic cropping.", "schema": { "maximum": 6000, "minimum": 1, "type": [ "null", "integer" ], "format": "int32" } }, { "name": "disable_twemoji", "in": "query", "description": "Twemoji is enabled by default. Set true to disable automatic emoji replacement and use the supplied fonts or native emoji fonts instead. Omitted, null, or false keeps Twemoji enabled.", "schema": { "type": [ "null", "boolean" ] } }, { "name": "max_render_once", "in": "query", "description": "Ensure the image is only ever rendered and saved one time. This is an advanced option not applicable to most requests.", "schema": { "type": [ "null", "boolean" ] } }, { "name": "color_scheme", "in": "query", "description": "Sets Chrome's preferred color scheme.", "schema": { "enum": [ "light", "dark" ], "type": [ "null", "string" ] } }, { "name": "timezone", "in": "query", "description": "Sets the IANA timezone used by Chrome while rendering.", "schema": { "type": [ "null", "string" ] } }, { "name": "block_consent_banners", "in": "query", "description": "Attempt to block cookie/consent banners from displaying.", "schema": { "type": [ "null", "boolean" ] } }, { "name": "identify_as_hcti", "in": "query", "description": "Identify the top-level page navigation as an HCTI screenshot request using the X-HCTI-SCREENSHOT header.", "schema": { "type": [ "null", "boolean" ] } }, { "name": "headers", "in": "query", "description": "HTTP headers to include on top-level page navigations to the requested URL's origin and any additional_header_origins. Supports up to 20 headers with names up to 512 ASCII characters and values up to 8192 UTF-8 bytes. For GET and form-encoded requests, repeat this parameter using the format `headers=name:value`.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "additional_header_origins", "in": "query", "description": "Additional exact HTTP or HTTPS origins allowed to receive custom headers. Supports up to 20 unique origins of up to 512 UTF-8 bytes each. Origins must use the format scheme://host[:port] without a path; duplicates are ignored. For GET and form-encoded requests, repeat this parameter for each origin.", "schema": { "type": "array", "items": { "type": "string", "format": "uri" } } }, { "name": "include_headers_on_subrequests", "in": "query", "description": "Include custom headers on subrequests to the requested URL's origin and any additional_header_origins. Defaults to false.", "schema": { "type": [ "null", "boolean" ] } }, { "name": "viewport_mobile", "in": "query", "description": "Specifies whether the page uses mobile viewport behavior, including its viewport meta tag.", "schema": { "type": [ "null", "boolean" ] } }, { "name": "viewport_landscape", "in": "query", "description": "Specifies whether the emulated viewport is in landscape orientation.", "schema": { "type": [ "null", "boolean" ] } }, { "name": "viewport_touch", "in": "query", "description": "Specifies whether the emulated viewport supports touch events.", "schema": { "type": [ "null", "boolean" ] } }, { "name": "media_type", "in": "query", "description": "Sets the CSS media type used while rendering the page.", "schema": { "enum": [ "print", "screen" ], "type": [ "null", "string" ] } }, { "name": "proxy_id", "in": "query", "description": "Specifies which configured organization proxy to use when rendering.", "schema": { "type": [ "null", "string" ] } }, { "name": "storage_destination_id", "in": "query", "description": "Specifies which configured organization storage destination receives the rendered image.", "schema": { "type": [ "null", "string" ] } }, { "name": "jumbo_max_height", "in": "query", "description": "Maximum height of the rendered image in jumbo mode. Jumbo rendering consumes additional renders and requires jumbo_max_width.", "schema": { "type": [ "null", "integer" ], "format": "int32" } }, { "name": "jumbo_max_width", "in": "query", "description": "Maximum width of the rendered image in jumbo mode. Jumbo rendering consumes additional renders and requires jumbo_max_height.", "schema": { "type": [ "null", "integer" ], "format": "int32" } }, { "name": "transparent_background", "in": "query", "description": "Specifies whether the image is rendered with a transparent background.", "schema": { "type": [ "null", "boolean" ] } } ], "responses": { "301": { "description": "Moved Permanently" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "security": [ ], "x-badges": [ { "name": "Requires images:create", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "images:create" ] } }, "/v1/images": { "get": { "tags": [ "Images" ], "summary": "List created images", "operationId": "list-images", "parameters": [ { "name": "page_token", "in": "query", "description": "The page token to use to get the next page of results. If this field is omitted, it defaults to the first page.", "schema": { "type": "string" } }, { "name": "count", "in": "query", "schema": { "maximum": 50, "minimum": 1, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImagePageResult" } } } }, "401": { "description": "Unauthorized" }, "400": { "description": "Bad Request" }, "500": { "description": "Internal Server Error" } }, "x-badges": [ { "name": "Requires images:read", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "images:read" ] } }, "/v1/images/{id}": { "get": { "tags": [ "Images" ], "summary": "Retrieve metadata about a specific image", "operationId": "get-image-metadata", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageBase" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires images:read", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "images:read" ] } }, "/v1/og-configs": { "post": { "tags": [ "OG Configs" ], "summary": "Create an OG configuration", "description": "**Rate limit:** 20 requests per minute per organization, shared across all operations in the `og-config:write` group and all API keys belonging to that organization.", "operationId": "create-og-config", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrUpdateOgConfigRequest" } } }, "required": true }, "responses": { "429": { "description": "Too Many Requests", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"og-config:write\";q=20;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"og-config:write\";r=0" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "200": { "description": "OK", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"og-config:write\";q=20;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"og-config:write\";r=19" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OgConfig" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires og_configs:create_update", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "og_configs:create_update" ], "x-rate-limit": { "group": "og-config:write", "limit": 20, "window_seconds": 60, "scope": "organization" } }, "get": { "tags": [ "OG Configs" ], "summary": "List OG configurations", "description": "Returns configurations in descending creation order, including disabled configurations. Pass pagination.next_page_start as page_start to continue; null indicates the final page.\n\n**Rate limit:** 100 requests per minute per organization, shared across all operations in the `og-config:read` group and all API keys belonging to that organization.", "operationId": "list-og-configs", "parameters": [ { "name": "count", "in": "query", "description": "Maximum number of configurations to return, from 1 to 100. Defaults to 10.", "schema": { "maximum": 100, "minimum": 1, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 10 } }, { "name": "page_start", "in": "query", "description": "pagination.next_page_start from the previous response. Omit for the first page.", "schema": { "type": "string" } } ], "responses": { "429": { "description": "Too Many Requests", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"og-config:read\";q=100;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"og-config:read\";r=0" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "200": { "description": "OK", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"og-config:read\";q=100;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"og-config:read\";r=99" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedListBaseOfOgConfigAndstring" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires og_configs:read", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "og_configs:read" ], "x-rate-limit": { "group": "og-config:read", "limit": 100, "window_seconds": 60, "scope": "organization" } } }, "/v1/og-configs/{id}": { "post": { "tags": [ "OG Configs" ], "summary": "Update an OG configuration", "description": "**Rate limit:** 20 requests per minute per organization, shared across all operations in the `og-config:write` group and all API keys belonging to that organization.", "operationId": "update-og-config", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrUpdateOgConfigRequest" } } }, "required": true }, "responses": { "429": { "description": "Too Many Requests", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"og-config:write\";q=20;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"og-config:write\";r=0" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "200": { "description": "OK", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"og-config:write\";q=20;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"og-config:write\";r=19" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OgConfig" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires og_configs:create_update", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "og_configs:create_update" ], "x-rate-limit": { "group": "og-config:write", "limit": 20, "window_seconds": 60, "scope": "organization" } }, "get": { "tags": [ "OG Configs" ], "summary": "Get an OG configuration", "description": "**Rate limit:** 100 requests per minute per organization, shared across all operations in the `og-config:read` group and all API keys belonging to that organization.", "operationId": "get-og-config", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "429": { "description": "Too Many Requests", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"og-config:read\";q=100;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"og-config:read\";r=0" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "200": { "description": "OK", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"og-config:read\";q=100;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"og-config:read\";r=99" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OgConfig" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires og_configs:read", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "og_configs:read" ], "x-rate-limit": { "group": "og-config:read", "limit": 100, "window_seconds": 60, "scope": "organization" } }, "delete": { "tags": [ "OG Configs" ], "summary": "Delete an OG configuration", "description": "**Rate limit:** 20 requests per minute per organization, shared across all operations in the `og-config:write` group and all API keys belonging to that organization.", "operationId": "delete-og-config", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "429": { "description": "Too Many Requests", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"og-config:write\";q=20;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"og-config:write\";r=0" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "204": { "description": "No Content", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"og-config:write\";q=20;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"og-config:write\";r=19" } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires og_configs:delete", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "og_configs:delete" ], "x-rate-limit": { "group": "og-config:write", "limit": 20, "window_seconds": 60, "scope": "organization" } } }, "/v1/proxies": { "post": { "tags": [ "Proxies" ], "summary": "Create a new Proxy", "description": "**Rate limit:** 20 requests per minute per organization, shared across all operations in the `proxy:write` group and all API keys belonging to that organization.", "operationId": "create-proxy", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrUpdateProxyRequest" } } }, "required": true }, "responses": { "429": { "description": "Too Many Requests", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"proxy:write\";q=20;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"proxy:write\";r=0" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "200": { "description": "OK", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"proxy:write\";q=20;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"proxy:write\";r=19" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Proxy" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires proxies:create_update", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "proxies:create_update" ], "x-rate-limit": { "group": "proxy:write", "limit": 20, "window_seconds": 60, "scope": "organization" } }, "get": { "tags": [ "Proxies" ], "summary": "List proxies", "description": "Returns a page of the organization's proxies in descending creation ID order, including disabled proxies and excluding deleted proxies. Pass pagination.next_page_start as page_start to continue; null indicates the final page.\n\n**Rate limit:** 100 requests per minute per organization, shared across all operations in the `proxy:read` group and all API keys belonging to that organization.", "operationId": "list-proxies", "parameters": [ { "name": "count", "in": "query", "description": "Maximum number of proxies to return, from 1 to 100. Defaults to 10.", "schema": { "maximum": 100, "minimum": 1, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 10 } }, { "name": "page_start", "in": "query", "description": "The opaque pagination.next_page_start string from the previous response. Omit for the first page.", "schema": { "type": "string" } } ], "responses": { "429": { "description": "Too Many Requests", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"proxy:read\";q=100;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"proxy:read\";r=0" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "200": { "description": "OK", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"proxy:read\";q=100;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"proxy:read\";r=99" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedListBaseOfProxyAndstring" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires proxies:read", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "proxies:read" ], "x-rate-limit": { "group": "proxy:read", "limit": 100, "window_seconds": 60, "scope": "organization" } } }, "/v1/proxies/{id}": { "post": { "tags": [ "Proxies" ], "summary": "Update a proxy", "description": "Replaces the complete proxy configuration. Omitted optional settings are cleared or reset. Within authentication, an omitted password requires retain_password: true and an unchanged username. Omitted or null authentication removes credentials.\n\n**Rate limit:** 20 requests per minute per organization, shared across all operations in the `proxy:write` group and all API keys belonging to that organization.", "operationId": "update-proxy", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrUpdateProxyRequest" } } }, "required": true }, "responses": { "429": { "description": "Too Many Requests", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"proxy:write\";q=20;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"proxy:write\";r=0" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "200": { "description": "OK", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"proxy:write\";q=20;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"proxy:write\";r=19" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Proxy" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires proxies:create_update", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "proxies:create_update" ], "x-rate-limit": { "group": "proxy:write", "limit": 20, "window_seconds": 60, "scope": "organization" } }, "get": { "tags": [ "Proxies" ], "summary": "Get a proxy", "description": "**Rate limit:** 100 requests per minute per organization, shared across all operations in the `proxy:read` group and all API keys belonging to that organization.", "operationId": "get-proxy", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "429": { "description": "Too Many Requests", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"proxy:read\";q=100;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"proxy:read\";r=0" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "200": { "description": "OK", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"proxy:read\";q=100;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"proxy:read\";r=99" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Proxy" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires proxies:read", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "proxies:read" ], "x-rate-limit": { "group": "proxy:read", "limit": 100, "window_seconds": 60, "scope": "organization" } }, "delete": { "tags": [ "Proxies" ], "summary": "Delete a proxy", "description": "**Rate limit:** 20 requests per minute per organization, shared across all operations in the `proxy:write` group and all API keys belonging to that organization.", "operationId": "delete-proxy", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "429": { "description": "Too Many Requests", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"proxy:write\";q=20;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"proxy:write\";r=0" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "204": { "description": "No Content", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"proxy:write\";q=20;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"proxy:write\";r=19" } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires proxies:delete", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "proxies:delete" ], "x-rate-limit": { "group": "proxy:write", "limit": 20, "window_seconds": 60, "scope": "organization" } } }, "/v1/storage-destinations": { "post": { "tags": [ "Storage Destinations" ], "summary": "Create a storage destination", "description": "Tests the connection before saving. Enabled destinations require a successful write test. Explicitly disabled destinations may be saved after a failed test; the response includes the test result. Secret access keys are never returned.\n\n**Rate limit:** 20 requests per minute per organization, shared across all operations in the `storage-destination:write` group and all API keys belonging to that organization.", "operationId": "create-storage-destination", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrUpdateStorageDestinationRequest" } } }, "required": true }, "responses": { "429": { "description": "Too Many Requests", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"storage-destination:write\";q=20;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"storage-destination:write\";r=0" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "200": { "description": "OK", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"storage-destination:write\";q=20;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"storage-destination:write\";r=19" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageDestination" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires storage_destinations:create_update", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "storage_destinations:create_update" ], "x-rate-limit": { "group": "storage-destination:write", "limit": 20, "window_seconds": 60, "scope": "organization" } }, "get": { "tags": [ "Storage Destinations" ], "summary": "List storage destinations", "description": "Returns destinations in descending creation order, including disabled destinations. Pass pagination.next_page_start as page_start to continue; null indicates the final page. Secret access keys are never returned.\n\n**Rate limit:** 100 requests per minute per organization, shared across all operations in the `storage-destination:read` group and all API keys belonging to that organization.", "operationId": "list-storage-destinations", "parameters": [ { "name": "count", "in": "query", "description": "Maximum number of destinations to return, from 1 to 100. Defaults to 10.", "schema": { "maximum": 100, "minimum": 1, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 10 } }, { "name": "page_start", "in": "query", "description": "pagination.next_page_start from the previous response. Omit for the first page.", "schema": { "type": "string" } } ], "responses": { "429": { "description": "Too Many Requests", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"storage-destination:read\";q=100;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"storage-destination:read\";r=0" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "200": { "description": "OK", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"storage-destination:read\";q=100;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"storage-destination:read\";r=99" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedListBaseOfStorageDestinationAndstring" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires storage_destinations:read", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "storage_destinations:read" ], "x-rate-limit": { "group": "storage-destination:read", "limit": 100, "window_seconds": 60, "scope": "organization" } } }, "/v1/storage-destinations/{id}": { "post": { "tags": [ "Storage Destinations" ], "summary": "Update a storage destination", "description": "Replaces the configuration. Omitted optional settings are cleared or reset, except a secret explicitly retained using retain_secret_access_key: true with unchanged provider and access key ID. Changed connections and re-enabling trigger a write test; an enabled request is not saved if that test fails. Metadata-only changes do not require a test. After a plan downgrade, only disabling is accepted and other submitted changes are ignored.\n\n**Rate limit:** 20 requests per minute per organization, shared across all operations in the `storage-destination:write` group and all API keys belonging to that organization.", "operationId": "update-storage-destination", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrUpdateStorageDestinationRequest" } } }, "required": true }, "responses": { "429": { "description": "Too Many Requests", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"storage-destination:write\";q=20;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"storage-destination:write\";r=0" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "200": { "description": "OK", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"storage-destination:write\";q=20;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"storage-destination:write\";r=19" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageDestination" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires storage_destinations:create_update", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "storage_destinations:create_update" ], "x-rate-limit": { "group": "storage-destination:write", "limit": 20, "window_seconds": 60, "scope": "organization" } }, "get": { "tags": [ "Storage Destinations" ], "summary": "Get a storage destination", "description": "**Rate limit:** 100 requests per minute per organization, shared across all operations in the `storage-destination:read` group and all API keys belonging to that organization.", "operationId": "get-storage-destination", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "429": { "description": "Too Many Requests", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"storage-destination:read\";q=100;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"storage-destination:read\";r=0" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "200": { "description": "OK", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"storage-destination:read\";q=100;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"storage-destination:read\";r=99" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageDestination" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires storage_destinations:read", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "storage_destinations:read" ], "x-rate-limit": { "group": "storage-destination:read", "limit": 100, "window_seconds": 60, "scope": "organization" } }, "delete": { "tags": [ "Storage Destinations" ], "summary": "Delete a storage destination", "description": "**Rate limit:** 20 requests per minute per organization, shared across all operations in the `storage-destination:write` group and all API keys belonging to that organization.", "operationId": "delete-storage-destination", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "429": { "description": "Too Many Requests", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"storage-destination:write\";q=20;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"storage-destination:write\";r=0" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "204": { "description": "No Content", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"storage-destination:write\";q=20;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"storage-destination:write\";r=19" } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires storage_destinations:delete", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "storage_destinations:delete" ], "x-rate-limit": { "group": "storage-destination:write", "limit": 20, "window_seconds": 60, "scope": "organization" } } }, "/v1/storage-destinations/aws-external-id": { "get": { "tags": [ "Storage Destinations" ], "summary": "Get the AWS storage external ID", "description": "Returns the current organization's external_id and HCTI writer_role_arn for configuring an AWS IAM role trust policy. Use external_id as sts:ExternalId and writer_role_arn as Principal.AWS. No storage destination ID is required.\n\n**Rate limit:** 100 requests per minute per organization, shared across all operations in the `storage-destination:read` group and all API keys belonging to that organization.", "operationId": "get-aws-storage-external-id", "responses": { "429": { "description": "Too Many Requests", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"storage-destination:read\";q=100;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"storage-destination:read\";r=0" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "200": { "description": "OK", "headers": { "RateLimit-Policy": { "description": "The shared organization quota policy: policy name, request allowance (q), and sliding-window length in seconds (w).", "schema": { "type": "string" }, "example": "\"storage-destination:read\";q=100;w=60" }, "RateLimit": { "description": "The policy name and remaining requests (r) after this rate-limit check. Concurrent requests share this allowance; it does not guarantee subsequent requests will be accepted.", "schema": { "type": "string" }, "example": "\"storage-destination:read\";r=99" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AwsStorageExternalId" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires storage_destinations:create_update", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "storage_destinations:create_update" ], "x-rate-limit": { "group": "storage-destination:read", "limit": 100, "window_seconds": 60, "scope": "organization" } } }, "/v1/store/{id}": { "put": { "tags": [ "Images" ], "summary": "Render and store an image in its configured storage destination", "operationId": "store-image", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "width", "in": "query", "description": "Width to resize the rendered image", "schema": { "maximum": 5000, "minimum": 1, "type": [ "null", "integer" ], "format": "int32" } }, { "name": "height", "in": "query", "description": "Height to resize the rendered image", "schema": { "maximum": 5000, "minimum": 1, "type": [ "null", "integer" ], "format": "int32" } }, { "name": "dpi", "in": "query", "description": "DPI to specify in rendered image's metadata.", "schema": { "maximum": 600, "minimum": 30, "type": [ "null", "integer" ], "format": "int32" } }, { "name": "aspect_ratio", "in": "query", "description": "Define an aspect ratio to crop the rendered image to. Specify the value as x_y. When using aspect_ratio, you must include one of: [x_1 & x_2], [y_1 & y_2], [x_1 & crop_width], [y_1 & crop_height], [crop_width] or [crop_height].", "schema": { "type": [ "null", "string" ] } }, { "name": "x_origin", "in": "query", "description": "Define the origin for cropping along the x axis. When using aspect_ratio, you can only specify one of x_origin or y_origin.", "schema": { "pattern": "^-?\\d+(\\.\\d+)?(%|px)?$", "type": [ "null", "string" ] }, "examples": { "Numeric": { "description": "Numbers without a unit specified are assumed to be pixel measurements.", "value": 159 }, "PX": { "description": "230 px", "value": "230px" }, "Percentage": { "description": "71%", "value": "71%" }, "NegativeNumeric": { "description": "Negative numbers without a unit specified are assumed to be pixel measurements from the end of the axis.", "value": -88 }, "NegativePX": { "description": "230 px from the end of the axis.", "value": "-230px" } } }, { "name": "y_origin", "in": "query", "description": "Define the origin for cropping along the y axis. When using aspect_ratio, you can only specify one of x_origin or y_origin.", "schema": { "pattern": "^-?\\d+(\\.\\d+)?(%|px)?$", "type": [ "null", "string" ] }, "examples": { "Numeric": { "description": "Numbers without a unit specified are assumed to be pixel measurements.", "value": 72 }, "PX": { "description": "160 px", "value": "160px" }, "Percentage": { "description": "88%", "value": "88%" }, "NegativeNumeric": { "description": "Negative numbers without a unit specified are assumed to be pixel measurements from the end of the axis.", "value": -16 }, "NegativePX": { "description": "160 px from the end of the axis.", "value": "-160px" } } }, { "name": "x_1", "in": "query", "description": "Define the x_1 position for cropping. You can specify either x_1 & x_2 or x_1 and crop_width.", "schema": { "pattern": "^-?\\d+(\\.\\d+)?(%|px)?$", "type": [ "null", "string" ] }, "examples": { "Numeric": { "description": "Numbers without a unit specified are assumed to be pixel measurements.", "value": 145 }, "PX": { "description": "222 px", "value": "222px" }, "Percentage": { "description": "77%", "value": "77%" }, "NegativeNumeric": { "description": "Negative numbers without a unit specified are assumed to be pixel measurements from the end of the axis.", "value": -68 }, "NegativePX": { "description": "222 px from the end of the axis.", "value": "-222px" } } }, { "name": "x_2", "in": "query", "description": "Define the x_2 position for cropping. Cannot be specified with crop_width, and must have an x_1 specified.", "schema": { "pattern": "^-?\\d+(\\.\\d+)?(%|px)?$", "type": [ "null", "string" ] }, "examples": { "Numeric": { "description": "Numbers without a unit specified are assumed to be pixel measurements.", "value": 231 }, "PX": { "description": "242 px", "value": "242px" }, "Percentage": { "description": "11%", "value": "11%" }, "NegativeNumeric": { "description": "Negative numbers without a unit specified are assumed to be pixel measurements from the end of the axis.", "value": -220 }, "NegativePX": { "description": "242 px from the end of the axis.", "value": "-242px" } } }, { "name": "y_1", "in": "query", "description": "Define the y_1 position for cropping. You can specify either y_1 & y_2 or y_1 and crop_height.", "schema": { "pattern": "^-?\\d+(\\.\\d+)?(%|px)?$", "type": [ "null", "string" ] }, "examples": { "Numeric": { "description": "Numbers without a unit specified are assumed to be pixel measurements.", "value": 123 }, "PX": { "description": "168 px", "value": "168px" }, "Percentage": { "description": "45%", "value": "45%" }, "NegativeNumeric": { "description": "Negative numbers without a unit specified are assumed to be pixel measurements from the end of the axis.", "value": -78 }, "NegativePX": { "description": "168 px from the end of the axis.", "value": "-168px" } } }, { "name": "y_2", "in": "query", "description": "Define the y_2 position for cropping. Cannot be specified with crop_height, and must have a y_1 specified.", "schema": { "pattern": "^-?\\d+(\\.\\d+)?(%|px)?$", "type": [ "null", "string" ] }, "examples": { "Numeric": { "description": "Numbers without a unit specified are assumed to be pixel measurements.", "value": 100 }, "PX": { "description": "133 px", "value": "133px" }, "Percentage": { "description": "33%", "value": "33%" }, "NegativeNumeric": { "description": "Negative numbers without a unit specified are assumed to be pixel measurements from the end of the axis.", "value": -67 }, "NegativePX": { "description": "133 px from the end of the axis.", "value": "-133px" } } }, { "name": "crop_width", "in": "query", "description": "Define the width for cropping. Cannot be specified with crop_height, and must have a x_1 specified.", "schema": { "pattern": "^\\d+(\\.\\d+)?(%|px)?$", "type": [ "null", "string" ], "description": "Use either a number, a percentage like 30.5% or a px measure like 100px." }, "examples": { "Numeric": { "description": "Numbers without a unit specified are assumed to be pixel measurements.", "value": 19 }, "PX": { "description": "100 px wide", "value": "100px" }, "Percentage": { "description": "81% of the image's width", "value": "81%" } } }, { "name": "crop_height", "in": "query", "description": "Define the x_2 position for cropping. Cannot be specified with crop_width, and must have a y_1 specified.", "schema": { "pattern": "^\\d+(\\.\\d+)?(%|px)?$", "type": [ "null", "string" ] }, "examples": { "Numeric": { "description": "Numbers without a unit specified are assumed to be pixel measurements.", "value": 44 }, "PX": { "description": "96 px high", "value": "96px" }, "Percentage": { "description": "52% of the image's height", "value": "52%" } } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreImageResult" } } } }, "424": { "description": "Failed Dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreImageResult" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "410": { "description": "Gone", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "408": { "description": "Request Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires images:store", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "images:store" ] } }, "/v1/store/{id}.{format}": { "put": { "tags": [ "Images" ], "summary": "Render and store an image with a specific format in its configured storage destination", "operationId": "store-image-format", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "path", "required": true, "schema": { "enum": [ "png", "jpg", "jpeg", "webp", "pdf" ], "type": "string" } }, { "name": "width", "in": "query", "description": "Width to resize the rendered image", "schema": { "maximum": 5000, "minimum": 1, "type": [ "null", "integer" ], "format": "int32" } }, { "name": "height", "in": "query", "description": "Height to resize the rendered image", "schema": { "maximum": 5000, "minimum": 1, "type": [ "null", "integer" ], "format": "int32" } }, { "name": "dpi", "in": "query", "description": "DPI to specify in rendered image's metadata.", "schema": { "maximum": 600, "minimum": 30, "type": [ "null", "integer" ], "format": "int32" } }, { "name": "aspect_ratio", "in": "query", "description": "Define an aspect ratio to crop the rendered image to. Specify the value as x_y. When using aspect_ratio, you must include one of: [x_1 & x_2], [y_1 & y_2], [x_1 & crop_width], [y_1 & crop_height], [crop_width] or [crop_height].", "schema": { "type": [ "null", "string" ] } }, { "name": "x_origin", "in": "query", "description": "Define the origin for cropping along the x axis. When using aspect_ratio, you can only specify one of x_origin or y_origin.", "schema": { "pattern": "^-?\\d+(\\.\\d+)?(%|px)?$", "type": [ "null", "string" ] }, "examples": { "Numeric": { "description": "Numbers without a unit specified are assumed to be pixel measurements.", "value": 159 }, "PX": { "description": "230 px", "value": "230px" }, "Percentage": { "description": "71%", "value": "71%" }, "NegativeNumeric": { "description": "Negative numbers without a unit specified are assumed to be pixel measurements from the end of the axis.", "value": -88 }, "NegativePX": { "description": "230 px from the end of the axis.", "value": "-230px" } } }, { "name": "y_origin", "in": "query", "description": "Define the origin for cropping along the y axis. When using aspect_ratio, you can only specify one of x_origin or y_origin.", "schema": { "pattern": "^-?\\d+(\\.\\d+)?(%|px)?$", "type": [ "null", "string" ] }, "examples": { "Numeric": { "description": "Numbers without a unit specified are assumed to be pixel measurements.", "value": 72 }, "PX": { "description": "160 px", "value": "160px" }, "Percentage": { "description": "88%", "value": "88%" }, "NegativeNumeric": { "description": "Negative numbers without a unit specified are assumed to be pixel measurements from the end of the axis.", "value": -16 }, "NegativePX": { "description": "160 px from the end of the axis.", "value": "-160px" } } }, { "name": "x_1", "in": "query", "description": "Define the x_1 position for cropping. You can specify either x_1 & x_2 or x_1 and crop_width.", "schema": { "pattern": "^-?\\d+(\\.\\d+)?(%|px)?$", "type": [ "null", "string" ] }, "examples": { "Numeric": { "description": "Numbers without a unit specified are assumed to be pixel measurements.", "value": 145 }, "PX": { "description": "222 px", "value": "222px" }, "Percentage": { "description": "77%", "value": "77%" }, "NegativeNumeric": { "description": "Negative numbers without a unit specified are assumed to be pixel measurements from the end of the axis.", "value": -68 }, "NegativePX": { "description": "222 px from the end of the axis.", "value": "-222px" } } }, { "name": "x_2", "in": "query", "description": "Define the x_2 position for cropping. Cannot be specified with crop_width, and must have an x_1 specified.", "schema": { "pattern": "^-?\\d+(\\.\\d+)?(%|px)?$", "type": [ "null", "string" ] }, "examples": { "Numeric": { "description": "Numbers without a unit specified are assumed to be pixel measurements.", "value": 231 }, "PX": { "description": "242 px", "value": "242px" }, "Percentage": { "description": "11%", "value": "11%" }, "NegativeNumeric": { "description": "Negative numbers without a unit specified are assumed to be pixel measurements from the end of the axis.", "value": -220 }, "NegativePX": { "description": "242 px from the end of the axis.", "value": "-242px" } } }, { "name": "y_1", "in": "query", "description": "Define the y_1 position for cropping. You can specify either y_1 & y_2 or y_1 and crop_height.", "schema": { "pattern": "^-?\\d+(\\.\\d+)?(%|px)?$", "type": [ "null", "string" ] }, "examples": { "Numeric": { "description": "Numbers without a unit specified are assumed to be pixel measurements.", "value": 123 }, "PX": { "description": "168 px", "value": "168px" }, "Percentage": { "description": "45%", "value": "45%" }, "NegativeNumeric": { "description": "Negative numbers without a unit specified are assumed to be pixel measurements from the end of the axis.", "value": -78 }, "NegativePX": { "description": "168 px from the end of the axis.", "value": "-168px" } } }, { "name": "y_2", "in": "query", "description": "Define the y_2 position for cropping. Cannot be specified with crop_height, and must have a y_1 specified.", "schema": { "pattern": "^-?\\d+(\\.\\d+)?(%|px)?$", "type": [ "null", "string" ] }, "examples": { "Numeric": { "description": "Numbers without a unit specified are assumed to be pixel measurements.", "value": 100 }, "PX": { "description": "133 px", "value": "133px" }, "Percentage": { "description": "33%", "value": "33%" }, "NegativeNumeric": { "description": "Negative numbers without a unit specified are assumed to be pixel measurements from the end of the axis.", "value": -67 }, "NegativePX": { "description": "133 px from the end of the axis.", "value": "-133px" } } }, { "name": "crop_width", "in": "query", "description": "Define the width for cropping. Cannot be specified with crop_height, and must have a x_1 specified.", "schema": { "pattern": "^\\d+(\\.\\d+)?(%|px)?$", "type": [ "null", "string" ], "description": "Use either a number, a percentage like 30.5% or a px measure like 100px." }, "examples": { "Numeric": { "description": "Numbers without a unit specified are assumed to be pixel measurements.", "value": 19 }, "PX": { "description": "100 px wide", "value": "100px" }, "Percentage": { "description": "81% of the image's width", "value": "81%" } } }, { "name": "crop_height", "in": "query", "description": "Define the x_2 position for cropping. Cannot be specified with crop_width, and must have a y_1 specified.", "schema": { "pattern": "^\\d+(\\.\\d+)?(%|px)?$", "type": [ "null", "string" ] }, "examples": { "Numeric": { "description": "Numbers without a unit specified are assumed to be pixel measurements.", "value": 44 }, "PX": { "description": "96 px high", "value": "96px" }, "Percentage": { "description": "52% of the image's height", "value": "52%" } } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreImageResult" } } } }, "424": { "description": "Failed Dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreImageResult" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "410": { "description": "Gone", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "408": { "description": "Request Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires images:store", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "images:store" ] } }, "/v1/template": { "post": { "tags": [ "Templates" ], "summary": "Create a new template", "operationId": "create-template", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateCreateResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires templates:create_update", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "templates:create_update" ] }, "get": { "tags": [ "Templates" ], "summary": "List templates", "operationId": "list-templates", "parameters": [ { "name": "count", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 10 } }, { "name": "max_version", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64", "default": 9223372036854775807 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOfTemplates" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires templates:read", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "templates:read" ] } }, "/v1/template/{id}": { "post": { "tags": [ "Templates" ], "summary": "Create a new version for an existing template", "operationId": "create-template-version", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateCreateResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires templates:create_update", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "templates:create_update" ] }, "get": { "tags": [ "Templates" ], "summary": "List template versions for a template", "operationId": "list-template-versions", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "count", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 10 } }, { "name": "max_version", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64", "default": 9223372036854775807 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOfTemplates" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires templates:read", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "templates:read" ] }, "delete": { "tags": [ "Templates" ], "summary": "Remove a template", "description": "Remove a template and clear all of its contents. Images already rendered with this template may still be cached, but rendering an image with this template, which was never rendered before will fail.", "operationId": "remove-template", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires templates:delete", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "templates:delete" ] } }, "/v1/usage": { "get": { "tags": [ "Usage" ], "summary": "Get organization usage", "description": "Returns usage information for the authenticated organization, including image totals by billing period.", "operationId": "get-usage", "parameters": [ { "name": "skipCache", "in": "query", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageDataReturn" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResult" } } } } }, "x-badges": [ { "name": "Requires usage:read", "position": "after", "color": "#64748b" } ], "x-required-permissions": [ "usage:read" ] } } }, "components": { "schemas": { "ApiErrorResult": { "required": [ "error", "message", "statusCode" ], "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string" }, "validationErrors": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/ValidationError" } }, "referenceId": { "type": [ "null", "string" ] }, "message": { "type": "string" }, "statusCode": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } }, "ApiKey": { "required": [ "id", "api_id", "name", "permissions" ], "type": "object", "properties": { "id": { "type": "string", "description": "ID used to retrieve, update, or delete this API key." }, "api_id": { "type": "string", "description": "API ID used as the username when authenticating API requests." }, "name": { "type": "string", "description": "Display name for the key." }, "description": { "type": [ "null", "string" ], "description": "Description of the key's purpose, if provided." }, "enabled": { "type": "boolean", "description": "Whether the key is enabled." }, "all_future_permissions": { "type": "boolean", "description": "Whether the key automatically receives all current and future permissions." }, "permissions": { "type": "array", "items": { "enum": [ "api_keys:create_update", "api_keys:delete", "api_keys:read", "images:create", "images:delete", "images:read", "images:store", "og_configs:create_update", "og_configs:delete", "og_configs:read", "proxies:create_update", "proxies:delete", "proxies:read", "storage_destinations:create_update", "storage_destinations:delete", "storage_destinations:read", "templates:create_update", "templates:delete", "templates:read", "usage:read" ], "type": "string" } }, "created_at": { "type": "string", "description": "When the key was created, in UTC.", "format": "date-time" }, "updated_at": { "type": "string", "description": "When the key was last updated, in UTC.", "format": "date-time" } }, "description": "An API key's identifiers, metadata, and permissions. Does not include the secret key." }, "ApiKeyWithSecret": { "required": [ "api_key", "id", "api_id", "name", "permissions" ], "type": "object", "properties": { "api_key": { "type": "string", "description": "Secret API key used as the password when authenticating API requests. Store it securely; subsequent API responses do not include it." }, "id": { "type": "string", "description": "ID used to retrieve, update, or delete this API key." }, "api_id": { "type": "string", "description": "API ID used as the username when authenticating API requests." }, "name": { "type": "string", "description": "Display name for the key." }, "description": { "type": [ "null", "string" ], "description": "Description of the key's purpose, if provided." }, "enabled": { "type": "boolean", "description": "Whether the key is enabled." }, "all_future_permissions": { "type": "boolean", "description": "Whether the key automatically receives all current and future permissions." }, "permissions": { "type": "array", "items": { "enum": [ "api_keys:create_update", "api_keys:delete", "api_keys:read", "images:create", "images:delete", "images:read", "images:store", "og_configs:create_update", "og_configs:delete", "og_configs:read", "proxies:create_update", "proxies:delete", "proxies:read", "storage_destinations:create_update", "storage_destinations:delete", "storage_destinations:read", "templates:create_update", "templates:delete", "templates:read", "usage:read" ], "type": "string" } }, "created_at": { "type": "string", "description": "When the key was created, in UTC.", "format": "date-time" }, "updated_at": { "type": "string", "description": "When the key was last updated, in UTC.", "format": "date-time" } }, "description": "A newly created API key, including its secret. The secret is returned only when creating a key; store it securely." }, "AwsStorageExternalId": { "type": "object", "properties": { "external_id": { "type": "string", "description": "Use this value for sts:ExternalId in the IAM role trust policy that grants HCTI access to your S3 bucket." }, "writer_role_arn": { "type": "string", "description": "Use this HCTI writer role ARN as Principal.AWS in the IAM role trust policy that grants HCTI access to your S3 bucket." } }, "description": "The organization's external ID and HCTI writer role ARN for an AWS IAM role trust policy." }, "AwsStorageRegion": { "enum": [ "af-south-1", "ap-east-1", "ap-east-2", "ap-northeast-1", "ap-northeast-2", "ap-northeast-3", "ap-south-1", "ap-south-2", "ap-southeast-1", "ap-southeast-2", "ap-southeast-3", "ap-southeast-4", "ap-southeast-5", "ap-southeast-6", "ap-southeast-7", "ca-central-1", "ca-west-1", "eu-central-1", "eu-central-2", "eu-north-1", "eu-south-1", "eu-south-2", "eu-west-1", "eu-west-2", "eu-west-3", "il-central-1", "me-central-1", "me-south-1", "mx-central-1", "sa-east-1", "us-east-1", "us-east-2", "us-west-1", "us-west-2" ] }, "BackblazeStorageRegion": { "enum": [ "us-west-000", "us-west-001", "us-west-002", "us-west-004", "us-east-005", "ca-east-006", "eu-central-003" ] }, "BaseImageRequest": { "title": "Base Image Request", "type": "object", "properties": { "css": { "type": [ "null", "string" ], "description": "Optional CSS for either image source. With `html`, it styles the supplied markup; with `url`, it is injected after the page loads to override page styles." }, "device_scale": { "maximum": 3, "minimum": 0.1, "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "description": "Adjusts the pixel ratio used for the screenshot. Minimum: 0.1. Maximum: 3. HTML and template renders default to 2; URL renders default to 1.", "format": "double" }, "full_screen": { "type": [ "null", "boolean" ], "description": "Take a screenshot of the entire screen after scrolling down and back to the top." }, "google_fonts": { "type": [ "null", "string" ], "description": "Google fonts to load. Separate multiple fonts with a pipe, such as 'Roboto|OpenSans', and set font-family in the CSS to use them." }, "html": { "type": [ "null", "string" ], "description": "HTML to render and take a screenshot of. HTML fragments are rendered in a wrapper document unless a complete HTML document is supplied. Required for HTML image requests." }, "max_wait_ms": { "maximum": 10000, "minimum": 500, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Sets a limit on how long to wait before taking the screenshot when the page continues loading irrelevant content. Minimum: 500. Maximum: 10000 and subject to the account plan limit.", "format": "int32" }, "metadata": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "Custom key-value metadata stored with the image." }, "ms_delay": { "maximum": 10000, "minimum": 0, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Adds extra time in milliseconds before taking the screenshot so JavaScript can execute. Minimum: 0. Maximum: 10000.", "format": "int32", "default": 0 }, "render_when_ready": { "type": [ "null", "boolean" ], "description": "Waits until the page signals that the screenshot is ready. The image fails if the readiness signal is never sent." }, "selector": { "type": [ "null", "string" ], "description": "A CSS selector for an element in the HTML. We’ll crop the image to this specific element." }, "template_values": { "oneOf": [ { "type": "null" }, { "description": "Values substituted into the template for this render. Must be a non-empty JSON object. Include the values needed by the template.", "$ref": "#/components/schemas/JsonObject" } ] }, "url": { "type": [ "null", "string" ], "description": "URL to capture for this batch item. After default options and a variation are merged, a non-empty `url` takes precedence over `html`; omit it to render the merged `html` instead." }, "viewport_height": { "maximum": 6000, "minimum": 1, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Sets the height of Chrome's viewport and disables automatic cropping. Minimum: 1. Maximum: 6000. Both viewport dimensions must be supplied together.", "format": "int32" }, "viewport_width": { "maximum": 6000, "minimum": 1, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Sets the width of Chrome's viewport and disables automatic cropping. Minimum: 1. Maximum: 6000. Both viewport dimensions must be supplied together.", "format": "int32" }, "pdf_options": { "oneOf": [ { "type": "null" }, { "description": "Options used when generating a PDF instead of an image. Page dimensions and margins must include supported PDF units; margins must contain either zero or four values; scale must be between 0.1 and 2.", "$ref": "#/components/schemas/PDFOptions" } ] }, "disable_twemoji": { "type": [ "null", "boolean" ], "description": "HTML/CSS images use Twemoji by default; set `disable_twemoji: true` to disable it. URL images inject Twemoji only with explicit `disable_twemoji: false`; omitted, null, or true leaves the page's emoji handling unchanged." }, "dedupe_duration_s": { "maximum": 31536000, "minimum": 0, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Reuse an existing image with identical content if it was created within this many seconds. Minimum: 0. Maximum: 31536000. Availability and maximum effective duration depend on the account plan.", "format": "int32" }, "max_render_once": { "type": [ "null", "boolean" ], "description": "Ensure the image is only ever rendered and saved one time. This is an advanced option not applicable to most requests." }, "color_scheme": { "oneOf": [ { "type": "null" }, { "description": "Sets Chrome's preferred color scheme. Valid values: light or dark.", "$ref": "#/components/schemas/ColorSchemeType" } ] }, "timezone": { "type": [ "null", "string" ], "description": "Sets the IANA timezone used by Chrome while rendering. Must be a recognized IANA timezone identifier." }, "block_consent_banners": { "type": [ "null", "boolean" ], "description": "Attempt to block cookie/consent banners from displaying." }, "identify_as_hcti": { "type": [ "null", "boolean" ], "description": "Identify the top-level page navigation as an HCTI screenshot request using the X-HCTI-SCREENSHOT header." }, "headers": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "HTTP headers to include on top-level page navigations to the requested URL's origin and any additional_header_origins. Supports up to 20 headers with names up to 512 ASCII characters and values up to 8192 UTF-8 bytes. For GET and form-encoded requests, repeat this parameter using the format `headers=name:value`." }, "additional_header_origins": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Additional exact HTTP or HTTPS origins allowed to receive custom headers. Supports up to 20 unique origins of up to 512 UTF-8 bytes each. Origins must use the format scheme://host[:port] without a path; duplicates are ignored. For GET and form-encoded requests, repeat this parameter for each origin." }, "include_headers_on_subrequests": { "type": [ "null", "boolean" ], "description": "Include custom headers on subrequests to the requested URL's origin and any additional_header_origins. Defaults to false. Requires at least one header." }, "viewport_mobile": { "type": [ "null", "boolean" ], "description": "Specifies whether the page uses mobile viewport behavior, including its viewport meta tag." }, "viewport_landscape": { "type": [ "null", "boolean" ], "description": "Specifies whether the emulated viewport is in landscape orientation." }, "viewport_touch": { "type": [ "null", "boolean" ], "description": "Specifies whether the emulated viewport supports touch events." }, "media_type": { "oneOf": [ { "type": "null" }, { "description": "Sets the CSS media type used while rendering the page. Valid values: print or screen.", "$ref": "#/components/schemas/MediaType" } ] }, "proxy_id": { "type": [ "null", "string" ], "description": "Specifies which configured organization proxy to use when rendering." }, "storage_destination_id": { "type": [ "null", "string" ], "description": "Specifies which configured organization storage destination receives the rendered image." }, "jumbo_max_height": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Maximum height of the rendered image in jumbo mode. Jumbo rendering consumes additional renders and requires jumbo_max_width. Supply both jumbo dimensions. Each must be greater than 0 and no more than 80000; at least one must exceed 8000; total area cannot exceed 400000000 pixels.", "format": "int32" }, "jumbo_max_width": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Maximum width of the rendered image in jumbo mode. Jumbo rendering consumes additional renders and requires jumbo_max_height. Supply both jumbo dimensions. Each must be greater than 0 and no more than 80000; at least one must exceed 8000; total area cannot exceed 400000000 pixels.", "format": "int32" }, "transparent_background": { "type": [ "null", "boolean" ], "description": "Specifies whether the image is rendered with a transparent background." }, "format": { "oneOf": [ { "type": "null" }, { "description": "Sets the file extension on the URL returned by the image creation request. It does not change the stored source image or restrict later rendering to this format. Valid values: png, jpg, jpeg, webp, or pdf. This parameter is accepted only in POST request bodies.", "$ref": "#/components/schemas/ImageFormat" } ] }, "request_overrides": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/RequestOverride" }, "description": "Rules that override browser network requests. The block action blocks requests matching a URL wildcard pattern and/or resource types. When both matchers are supplied, both must match. A request is blocked if any block rule matches. Omitted, null, or an empty array adds no overrides. Requires a paid plan. Accepts a JSON array in JSON requests or a JSON-encoded array string in form requests. Maximum 100 rules and 512 characters per URL pattern. Each block rule requires a nonempty URL pattern or at least one resource type; supplied matchers cannot be empty. Not supported in query strings." } }, "description": "Image request containing all available properties. Batch variations override matching values supplied here." }, "BatchDeleteRequest": { "required": [ "ids" ], "type": "object", "properties": { "ids": { "title": "Image Ids", "maxItems": 25, "minItems": 1, "type": "array", "items": { "type": "string" }, "description": "Up to 25 ids of images to delete." } } }, "BatchImageRequest": { "type": "object", "properties": { "default_options": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BaseImageRequest" } ] }, "variations": { "type": "array", "items": { "$ref": "#/components/schemas/ImageRequest" } } } }, "BatchImageResult": { "required": [ "images" ], "type": "object", "properties": { "images": { "type": "array", "items": { "$ref": "#/components/schemas/ImageResultWithId" } } } }, "CloudflareStorageJurisdiction": { "enum": [ "eu", "fedramp", null ] }, "ColorSchemeType": { "enum": [ "light", "dark", null ] }, "CreateOrUpdateApiKeyRequest": { "required": [ "permissions" ], "type": "object", "properties": { "name": { "maxLength": 255, "type": [ "null", "string" ], "description": "Display name for the key, up to 255 characters. Omitted, null, or blank names use Key created YYYY-MM-DD HH:mm:ss, based on the key's original creation time in UTC." }, "description": { "maxLength": 2000, "type": [ "null", "string" ], "description": "Optional description of the key's purpose, up to 2000 characters. Omitted, null, or blank clears the description." }, "disabled": { "type": "boolean", "description": "Whether the key is disabled. Disabled keys cannot authenticate requests. Defaults to false.", "default": false }, "all_future_permissions": { "type": "boolean", "description": "Grant all current and future permissions. Only callers with this authority can enable it. Defaults to false.", "default": false }, "permissions": { "type": "array", "items": { "enum": [ "api_keys:create_update", "api_keys:delete", "api_keys:read", "images:create", "images:delete", "images:read", "images:store", "og_configs:create_update", "og_configs:delete", "og_configs:read", "proxies:create_update", "proxies:delete", "proxies:read", "storage_destinations:create_update", "storage_destinations:delete", "storage_destinations:read", "templates:create_update", "templates:delete", "templates:read", "usage:read" ], "type": "string" }, "description": "Complete list of current permissions to grant, for example images:create or templates:read. Ignored when all_future_permissions is true; supply an empty array in that case. Otherwise, an empty array grants no product permissions. Permissions cannot exceed the caller's authority." } }, "description": "Configuration for creating or updating an API key. Updates replace the configuration; omitted optional settings are cleared or reset to their defaults." }, "CreateOrUpdateOgConfigRequest": { "title": "Create or Update OG Config Request", "required": [ "config_type" ], "type": "object", "anyOf": [ { "$ref": "#/components/schemas/CreateOrUpdateOgConfigRequestCreateOrUpdateOgConfigRequest_HtmlCss" }, { "$ref": "#/components/schemas/CreateOrUpdateOgConfigRequestCreateOrUpdateOgConfigRequest_Templated" } ], "description": "Settings for creating or updating an Open Graph image configuration.", "discriminator": { "propertyName": "config_type", "mapping": { "html_css": "#/components/schemas/CreateOrUpdateOgConfigRequestCreateOrUpdateOgConfigRequest_HtmlCss", "templated": "#/components/schemas/CreateOrUpdateOgConfigRequestCreateOrUpdateOgConfigRequest_Templated" } } }, "CreateOrUpdateOgConfigRequestCreateOrUpdateOgConfigRequest_HtmlCss": { "title": "HTML/CSS OG Config Request", "required": [ "name", "base_url" ], "properties": { "config_type": { "enum": [ "html_css" ], "type": "string" }, "default_options": { "oneOf": [ { "type": "null" }, { "description": "Default image rendering options for pages served by this configuration. Any extracted values will override these defaults.", "$ref": "#/components/schemas/OgDefaultImageOptions" } ] }, "extract_values": { "type": "boolean", "description": "Whether to extract image options from page metadata. When disabled, only the configured defaults are used." }, "name": { "maxLength": 255, "type": "string", "description": "Display name for the configuration, up to 255 characters." }, "description": { "maxLength": 1023, "type": [ "null", "string" ], "description": "Optional description of the configuration, up to 1023 characters." }, "base_url": { "maxLength": 2048, "type": "string", "description": "HTTPS origin of the source website, such as https://example.com. Do not include a path, query string, fragment, or credentials." }, "optimization_mode": { "description": "How images are sized for social platforms: keep their original dimensions, adapt them after rendering, or set the viewport before rendering. Defaults to post_process.", "$ref": "#/components/schemas/OgSocialSizeOptimizationMode" }, "disabled": { "type": "boolean", "description": "Whether this configuration is disabled from serving Open Graph images. Defaults to false.", "default": false }, "refresh_interval_s": { "maximum": 31536000, "minimum": 1800, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Interval in seconds before cached images are eligible for refresh. The minimum depends on your plan; the maximum is one year.", "format": "uint32", "default": 86400 } }, "description": "Settings for an Open Graph configuration that renders page HTML/CSS." }, "CreateOrUpdateOgConfigRequestCreateOrUpdateOgConfigRequest_Templated": { "title": "Templated OG Config Request", "required": [ "template_id", "name", "base_url" ], "properties": { "config_type": { "enum": [ "templated" ], "type": "string" }, "template_id": { "type": "string", "description": "ID of the template used to render images." }, "template_version": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Template version to use. Omit or set to null to use the latest version.", "format": "int64" }, "template_values_mapping": { "maxItems": 32, "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/OgTemplateValueMapping" }, "description": "Up to 32 mappings from page metadata to template fields. Each mapping supplies either a meta_key or a fallback." }, "headers": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "HTTP headers to include on top-level page navigations to the requested URL's origin and any additional_header_origins. Supports up to 20 headers with names up to 512 ASCII characters and values up to 8192 UTF-8 bytes." }, "additional_header_origins": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Additional exact HTTP or HTTPS origins allowed to receive custom headers. Supports up to 20 unique origins of up to 512 UTF-8 bytes each. Origins must use the format scheme://host[:port] without a path; duplicates are ignored." }, "name": { "maxLength": 255, "type": "string", "description": "Display name for the configuration, up to 255 characters." }, "description": { "maxLength": 1023, "type": [ "null", "string" ], "description": "Optional description of the configuration, up to 1023 characters." }, "base_url": { "maxLength": 2048, "type": "string", "description": "HTTPS origin of the source website, such as https://example.com. Do not include a path, query string, fragment, or credentials." }, "optimization_mode": { "description": "How images are sized for social platforms: keep their original dimensions, adapt them after rendering, or set the viewport before rendering. Defaults to post_process.", "$ref": "#/components/schemas/OgSocialSizeOptimizationMode" }, "disabled": { "type": "boolean", "description": "Whether this configuration is disabled from serving Open Graph images. Defaults to false.", "default": false }, "refresh_interval_s": { "maximum": 31536000, "minimum": 1800, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Interval in seconds before cached images are eligible for refresh. The minimum depends on your plan; the maximum is one year.", "format": "uint32", "default": 86400 } }, "description": "Settings for an Open Graph configuration that renders a template using values extracted from page metadata." }, "CreateOrUpdateProxyRequest": { "required": [ "name", "url" ], "type": "object", "properties": { "name": { "maxLength": 500, "minLength": 3, "type": "string", "description": "Display name for the proxy, between 3 and 500 characters. Leading and trailing whitespace is removed; the resulting name must contain at least 3 characters." }, "url": { "maxLength": 512, "type": "string", "description": "Absolute HTTP or HTTPS proxy server URL, up to 512 characters, for example https://proxy.example.com. Supply the port and credentials in their separate fields. Paths other than /, query strings, and fragments are not allowed.", "format": "uri" }, "port": { "maximum": 65535, "minimum": 1, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Proxy server port, from 1 to 65535. Omitted or null uses the URL scheme's default port: 80 for HTTP or 443 for HTTPS.", "format": "uint16" }, "disabled": { "type": "boolean", "description": "Whether the proxy is disabled. Defaults to false.", "default": false }, "authentication": { "oneOf": [ { "type": "null" }, { "description": "Proxy credentials. Supply a username and either a password or retention instructions. Omitted or null means no authentication and removes existing credentials on update.", "$ref": "#/components/schemas/ProxyAuthentication" } ] }, "bypass_hosts": { "maxItems": 100, "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Up to 100 hosts that should bypass the proxy. Entries may be hostnames, IP addresses, or absolute URLs; URLs are reduced to their hostnames. Hosts are normalized to lowercase and duplicates removed. Replaces the complete list; omitted, null, or [] clears it." } }, "description": "Complete configuration for creating or updating an organization proxy. Updates replace the configuration; omitted optional settings are cleared or reset, except a password retained through authentication.retain_password." }, "CreateOrUpdateStorageDestinationRequest": { "required": [ "name", "connection_info" ], "type": "object", "properties": { "name": { "maxLength": 255, "minLength": 3, "type": "string", "description": "Display name for the destination, between 3 and 255 characters." }, "disabled": { "type": "boolean", "description": "Whether this destination is disabled. Defaults to false. Enabling requires a successful connection test.", "default": false }, "hcti_storage_disabled": { "type": "boolean", "description": "Whether to disable HCTI storage for images saved to this destination. When true, rendered files have no public HCTI URL and are not cached by the HCTI CDN. Defaults to false." }, "connection_info": { "description": "Bucket, provider settings, and credentials used to write images to this destination.", "$ref": "#/components/schemas/StorageDestinationConnectionRequest" } }, "description": "Complete configuration for creating or updating a storage destination. Omitted optional settings are cleared or reset, except a secret explicitly retained using retain_secret_access_key: true. Connection settings are verified before enabling the destination." }, "DigitalOceanStorageRegion": { "enum": [ "nyc3", "ams3", "sfo2", "sfo3", "sgp1", "lon1", "fra1", "tor1", "blr1", "syd1", "atl1", "ric1", "mkc1" ] }, "HandlebarsHelperKind": { "enum": [ "UNKNOWN", "None", "If", "Unless", "With", "Each" ] }, "ImageBase": { "required": [ "image_type" ], "type": "object", "anyOf": [ { "$ref": "#/components/schemas/ImageBaseImage_HtmlCss" }, { "$ref": "#/components/schemas/ImageBaseImage_Url" }, { "$ref": "#/components/schemas/ImageBaseImage_Templated" } ], "description": "Metadata shared by all images. The image_type discriminator identifies the response as html_css, url, or templated.", "discriminator": { "propertyName": "image_type", "mapping": { "html_css": "#/components/schemas/ImageBaseImage_HtmlCss", "url": "#/components/schemas/ImageBaseImage_Url", "templated": "#/components/schemas/ImageBaseImage_Templated" } } }, "ImageBaseImage_HtmlCss": { "title": "HTML/CSS Image", "properties": { "image_type": { "enum": [ "html_css" ], "type": "string" }, "css": { "type": [ "null", "string" ], "description": "CSS used to style the rendered HTML." }, "device_scale": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "description": "Screenshot pixel ratio. A value of 2 produces two output pixels per CSS pixel in each dimension.", "format": "double" }, "google_fonts": { "type": [ "null", "string" ], "description": "Google Font families to load, separated by a pipe, for example Roboto|Open Sans." }, "html": { "type": "string", "description": "HTML source supplied for rendering the image." }, "max_wait_ms": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Maximum loading wait in milliseconds before capture when the page continues loading content.", "format": "int32" }, "metadata": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "Custom key-value metadata stored with the image." }, "ms_delay": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Additional delay in milliseconds before taking the screenshot.", "format": "int32" }, "render_when_ready": { "type": [ "null", "boolean" ], "description": "Whether capture waits for the page to call ScreenshotReady(). Rendering fails if the readiness signal is not received." }, "selector": { "type": [ "null", "string" ], "description": "CSS selector of the element to capture. When set, the image is cropped to the matching element." }, "viewport_height": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Browser viewport height in CSS pixels.", "format": "int32" }, "viewport_width": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Browser viewport width in CSS pixels.", "format": "int32" }, "pdf_options": { "oneOf": [ { "type": "null" }, { "description": "Page size, margins, scale, and background settings used when rendering a PDF.", "$ref": "#/components/schemas/PDFOptions" } ] }, "disable_twemoji": { "type": [ "null", "boolean" ], "description": "HTML/CSS images use Twemoji by default; set true to disable it. URL images inject Twemoji only when explicitly set to false. For URLs, omitted, null, or true leaves the page's emoji handling unchanged." }, "max_render_once": { "type": [ "null", "boolean" ], "description": "Whether the image is restricted to being rendered and saved at most once." }, "color_scheme": { "oneOf": [ { "type": "null" }, { "description": "Sets Chrome's preferred color scheme.", "$ref": "#/components/schemas/ColorSchemeType" } ] }, "timezone": { "type": [ "null", "string" ], "description": "Sets the IANA timezone used by Chrome while rendering." }, "viewport_mobile": { "type": [ "null", "boolean" ], "description": "Whether the browser viewport emulates a mobile device." }, "viewport_landscape": { "type": [ "null", "boolean" ], "description": "Whether the browser viewport emulates landscape orientation." }, "viewport_touch": { "type": [ "null", "boolean" ], "description": "Whether the browser emulates support for touch input." }, "media_type": { "oneOf": [ { "type": "null" }, { "description": "CSS media type emulated when rendering, such as screen or print.", "$ref": "#/components/schemas/MediaType" } ] }, "proxy_id": { "type": [ "null", "string" ], "description": "ID of the proxy configured for browser requests, or null when no proxy is configured." }, "storage_destination_id": { "type": [ "null", "string" ], "description": "ID of the storage destination configured for this image, or null when none is configured." }, "jumbo_max_height": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Maximum output height in pixels for jumbo rendering. Used together with jumbo_max_width.", "format": "int32" }, "jumbo_max_width": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Maximum output width in pixels for jumbo rendering. Used together with jumbo_max_height.", "format": "int32" }, "transparent_background": { "type": [ "null", "boolean" ], "description": "Whether the default browser background is transparent. Backgrounds explicitly set by the page still apply." }, "request_overrides": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/RequestOverride" }, "description": "Browser request overrides. Block rules match URL wildcard patterns and/or resource types; supplied matchers must all match." }, "id": { "type": "string", "description": "Unique image ID. Use this value to retrieve image metadata or render the image." }, "created_at": { "type": "string", "description": "Date and time the image was created, in UTC.", "format": "date-time" }, "last_render_stored_at": { "type": [ "null", "string" ], "description": "Last recorded date and time a rendered image was stored by HCTI, in UTC. Null when no stored render timestamp is available. This value can change after rendering again or be cleared when the stored render is removed.", "format": "date-time" }, "og_config_id": { "type": [ "null", "string" ], "description": "ID of the Open Graph configuration that created this image, or null when the image is not associated with one." }, "og_config_content_version": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Content version of the Open Graph configuration associated with this image, or null when unavailable.", "format": "int64" }, "saved_to_storage_destination_at": { "type": [ "null", "string" ], "description": "Recorded date and time the base image was saved to its configured storage destination, in UTC. Null until a save is recorded; does not describe saves of resized or reformatted variants.", "format": "date-time" }, "storage_destination_hcti_storage_disabled": { "type": [ "null", "boolean" ], "description": "Whether HCTI storage is disabled for this image, recorded from the storage destination when the image was created. When true, rendered files are saved to the configured storage destination without a public HCTI image URL or HCTI CDN caching." } }, "description": "An image created from HTML and CSS, including its source content and stored rendering settings. The image_type is html_css." }, "ImageBaseImage_Templated": { "title": "Templated Image", "properties": { "image_type": { "enum": [ "templated" ], "type": "string" }, "template_id": { "type": "string", "description": "ID of the template used to create this image." }, "template_version": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Version of the template used to create this image.", "format": "int64" }, "template_values": { "description": "Resolved values supplied to the template for this image, keyed by template variable name.", "$ref": "#/components/schemas/JsonObject" }, "id": { "type": "string", "description": "Unique image ID. Use this value to retrieve image metadata or render the image." }, "created_at": { "type": "string", "description": "Date and time the image was created, in UTC.", "format": "date-time" }, "last_render_stored_at": { "type": [ "null", "string" ], "description": "Last recorded date and time a rendered image was stored by HCTI, in UTC. Null when no stored render timestamp is available. This value can change after rendering again or be cleared when the stored render is removed.", "format": "date-time" }, "og_config_id": { "type": [ "null", "string" ], "description": "ID of the Open Graph configuration that created this image, or null when the image is not associated with one." }, "og_config_content_version": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Content version of the Open Graph configuration associated with this image, or null when unavailable.", "format": "int64" }, "saved_to_storage_destination_at": { "type": [ "null", "string" ], "description": "Recorded date and time the base image was saved to its configured storage destination, in UTC. Null until a save is recorded; does not describe saves of resized or reformatted variants.", "format": "date-time" }, "storage_destination_hcti_storage_disabled": { "type": [ "null", "boolean" ], "description": "Whether HCTI storage is disabled for this image, recorded from the storage destination when the image was created. When true, rendered files are saved to the configured storage destination without a public HCTI image URL or HCTI CDN caching." } }, "description": "An image created from a specific template version and resolved template values. The image_type is templated." }, "ImageBaseImage_Url": { "title": "URL Image", "properties": { "image_type": { "enum": [ "url" ], "type": "string" }, "css": { "type": [ "null", "string" ], "description": "CSS injected into the loaded URL to override styles on the page." }, "device_scale": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "description": "Screenshot pixel ratio. A value of 2 produces two output pixels per CSS pixel in each dimension.", "format": "double" }, "full_screen": { "type": [ "null", "boolean" ], "description": "Whether the screenshot captures the entire scrollable page after scrolling down and back to the top." }, "max_wait_ms": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Maximum loading wait in milliseconds before capture when the page continues loading content.", "format": "int32" }, "metadata": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "Custom key-value metadata stored with the image." }, "ms_delay": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Additional delay in milliseconds before taking the screenshot.", "format": "int32" }, "render_when_ready": { "type": [ "null", "boolean" ], "description": "Whether capture waits for the page to call ScreenshotReady(). Rendering fails if the readiness signal is not received." }, "selector": { "type": [ "null", "string" ], "description": "CSS selector of the element to capture. When set, the image is cropped to the matching element." }, "url": { "type": "string", "description": "Source URL of the web page to capture." }, "viewport_height": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Browser viewport height in CSS pixels.", "format": "int32" }, "viewport_width": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Browser viewport width in CSS pixels.", "format": "int32" }, "pdf_options": { "oneOf": [ { "type": "null" }, { "description": "Page size, margins, scale, and background settings used when rendering a PDF.", "$ref": "#/components/schemas/PDFOptions" } ] }, "disable_twemoji": { "type": [ "null", "boolean" ], "description": "HTML/CSS images use Twemoji by default; set true to disable it. URL images inject Twemoji only when explicitly set to false. For URLs, omitted, null, or true leaves the page's emoji handling unchanged." }, "max_render_once": { "type": [ "null", "boolean" ], "description": "Whether the image is restricted to being rendered and saved at most once." }, "color_scheme": { "oneOf": [ { "type": "null" }, { "description": "Sets Chrome's preferred color scheme.", "$ref": "#/components/schemas/ColorSchemeType" } ] }, "timezone": { "type": [ "null", "string" ], "description": "Sets the IANA timezone used by Chrome while rendering." }, "block_consent_banners": { "type": [ "null", "boolean" ], "description": "Whether the browser attempts to block cookie and consent banners before capture." }, "identify_as_hcti": { "type": [ "null", "boolean" ], "description": "Whether top-level page navigation includes the X-HCTI-SCREENSHOT: 1 header to identify the request as an HCTI screenshot." }, "headers": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "Custom HTTP headers sent on top-level page navigations to the source URL's origin and any additional_header_origins." }, "additional_header_origins": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Additional exact HTTP or HTTPS origins allowed to receive custom headers, in the form scheme://host[:port] without a path." }, "include_headers_on_subrequests": { "type": [ "null", "boolean" ], "description": "Whether custom headers are also sent on subrequests to the source URL's origin and any additional_header_origins." }, "viewport_mobile": { "type": [ "null", "boolean" ], "description": "Whether the browser viewport emulates a mobile device." }, "viewport_landscape": { "type": [ "null", "boolean" ], "description": "Whether the browser viewport emulates landscape orientation." }, "viewport_touch": { "type": [ "null", "boolean" ], "description": "Whether the browser emulates support for touch input." }, "media_type": { "oneOf": [ { "type": "null" }, { "description": "CSS media type emulated when rendering, such as screen or print.", "$ref": "#/components/schemas/MediaType" } ] }, "proxy_id": { "type": [ "null", "string" ], "description": "ID of the proxy configured for browser requests, or null when no proxy is configured." }, "storage_destination_id": { "type": [ "null", "string" ], "description": "ID of the storage destination configured for this image, or null when none is configured." }, "jumbo_max_height": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Maximum output height in pixels for jumbo rendering. Used together with jumbo_max_width.", "format": "int32" }, "jumbo_max_width": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Maximum output width in pixels for jumbo rendering. Used together with jumbo_max_height.", "format": "int32" }, "transparent_background": { "type": [ "null", "boolean" ], "description": "Whether the default browser background is transparent. Backgrounds explicitly set by the page still apply." }, "request_overrides": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/RequestOverride" }, "description": "Browser request overrides. Block rules match URL wildcard patterns and/or resource types; supplied matchers must all match." }, "id": { "type": "string", "description": "Unique image ID. Use this value to retrieve image metadata or render the image." }, "created_at": { "type": "string", "description": "Date and time the image was created, in UTC.", "format": "date-time" }, "last_render_stored_at": { "type": [ "null", "string" ], "description": "Last recorded date and time a rendered image was stored by HCTI, in UTC. Null when no stored render timestamp is available. This value can change after rendering again or be cleared when the stored render is removed.", "format": "date-time" }, "og_config_id": { "type": [ "null", "string" ], "description": "ID of the Open Graph configuration that created this image, or null when the image is not associated with one." }, "og_config_content_version": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Content version of the Open Graph configuration associated with this image, or null when unavailable.", "format": "int64" }, "saved_to_storage_destination_at": { "type": [ "null", "string" ], "description": "Recorded date and time the base image was saved to its configured storage destination, in UTC. Null until a save is recorded; does not describe saves of resized or reformatted variants.", "format": "date-time" }, "storage_destination_hcti_storage_disabled": { "type": [ "null", "boolean" ], "description": "Whether HCTI storage is disabled for this image, recorded from the storage destination when the image was created. When true, rendered files are saved to the configured storage destination without a public HCTI image URL or HCTI CDN caching." } }, "description": "An image created by capturing a web page, including its source URL and stored rendering settings. The image_type is url." }, "ImageFormat": { "enum": [ "png", "jpg", "jpeg", "webp", "pdf", null ] }, "ImagePageResult": { "required": [ "next_page_token" ], "type": "object", "properties": { "images": { "type": "array", "items": { "$ref": "#/components/schemas/SimpleImage" }, "description": "Image summaries returned on this page." }, "next_page_token": { "type": "string", "description": "Opaque continuation token. Pass this value as page_token to retrieve the next page when has_next_page is true." }, "has_next_page": { "type": "boolean", "description": "Whether another page of results is available." } }, "description": "A page of created images belonging to the authenticated organization, excluding deleted images." }, "ImageRequest": { "type": "object", "anyOf": [ { "$ref": "#/components/schemas/ImageRequestImageRequest_HtmlCss" }, { "$ref": "#/components/schemas/ImageRequestImageRequest_Url" }, { "$ref": "#/components/schemas/ImageRequestImageRequest_Templated" } ], "discriminator": { "propertyName": "$type" } }, "ImageRequestImageRequest_HtmlCss": { "title": "HTML/CSS Image Request", "required": [ "html" ], "properties": { "html": { "type": "string", "description": "HTML to render and take a screenshot of. HTML fragments are rendered in a wrapper document unless a complete HTML document is supplied. Required for HTML image requests." }, "css": { "type": [ "null", "string" ], "description": "CSS used to style the rendered HTML." }, "device_scale": { "maximum": 3, "minimum": 0.1, "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "description": "Adjusts the pixel ratio used for the screenshot. Minimum: 0.1. Maximum: 3. HTML and template renders default to 2; URL renders default to 1.", "format": "double" }, "google_fonts": { "type": [ "null", "string" ], "description": "Google fonts to load. Separate multiple fonts with a pipe, such as 'Roboto|OpenSans', and set font-family in the CSS to use them." }, "max_wait_ms": { "maximum": 10000, "minimum": 500, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Sets a limit on how long to wait before taking the screenshot when the page continues loading irrelevant content. Minimum: 500. Maximum: 10000 and subject to the account plan limit.", "format": "int32" }, "metadata": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "Custom key-value metadata stored with the image." }, "ms_delay": { "maximum": 10000, "minimum": 0, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Adds extra time in milliseconds before taking the screenshot so JavaScript can execute. Minimum: 0. Maximum: 10000.", "format": "int32", "default": 0 }, "render_when_ready": { "type": [ "null", "boolean" ], "description": "Waits until the page signals that the screenshot is ready. The image fails if the readiness signal is never sent." }, "selector": { "type": [ "null", "string" ], "description": "A CSS selector for an element in the HTML. We’ll crop the image to this specific element." }, "viewport_height": { "maximum": 6000, "minimum": 1, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Sets the height of Chrome's viewport and disables automatic cropping. Minimum: 1. Maximum: 6000. Both viewport dimensions must be supplied together.", "format": "int32" }, "viewport_width": { "maximum": 6000, "minimum": 1, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Sets the width of Chrome's viewport and disables automatic cropping. Minimum: 1. Maximum: 6000. Both viewport dimensions must be supplied together.", "format": "int32" }, "pdf_options": { "oneOf": [ { "type": "null" }, { "description": "Options used when generating a PDF instead of an image. Page dimensions and margins must include supported PDF units; margins must contain either zero or four values; scale must be between 0.1 and 2.", "$ref": "#/components/schemas/PDFOptions" } ] }, "disable_twemoji": { "type": [ "null", "boolean" ], "description": "Twemoji is enabled by default. Set true to disable automatic emoji replacement and use the supplied fonts or native emoji fonts instead. Omitted, null, or false keeps Twemoji enabled." }, "dedupe_duration_s": { "maximum": 31536000, "minimum": 0, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Reuse an existing image with identical content if it was created within this many seconds. Minimum: 0. Maximum: 31536000. Availability and maximum effective duration depend on the account plan.", "format": "int32" }, "max_render_once": { "type": [ "null", "boolean" ], "description": "Ensure the image is only ever rendered and saved one time. This is an advanced option not applicable to most requests." }, "color_scheme": { "oneOf": [ { "type": "null" }, { "description": "Sets Chrome's preferred color scheme. Valid values: light or dark.", "$ref": "#/components/schemas/ColorSchemeType" } ] }, "timezone": { "type": [ "null", "string" ], "description": "Sets the IANA timezone used by Chrome while rendering. Must be a recognized IANA timezone identifier." }, "viewport_mobile": { "type": [ "null", "boolean" ], "description": "Specifies whether the page uses mobile viewport behavior, including its viewport meta tag." }, "viewport_landscape": { "type": [ "null", "boolean" ], "description": "Specifies whether the emulated viewport is in landscape orientation." }, "viewport_touch": { "type": [ "null", "boolean" ], "description": "Specifies whether the emulated viewport supports touch events." }, "media_type": { "oneOf": [ { "type": "null" }, { "description": "Sets the CSS media type used while rendering the page. Valid values: print or screen.", "$ref": "#/components/schemas/MediaType" } ] }, "proxy_id": { "type": [ "null", "string" ], "description": "Specifies which configured organization proxy to use when rendering." }, "storage_destination_id": { "type": [ "null", "string" ], "description": "Specifies which configured organization storage destination receives the rendered image." }, "jumbo_max_height": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Maximum height of the rendered image in jumbo mode. Jumbo rendering consumes additional renders and requires jumbo_max_width. Supply both jumbo dimensions. Each must be greater than 0 and no more than 80000; at least one must exceed 8000; total area cannot exceed 400000000 pixels.", "format": "int32" }, "jumbo_max_width": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Maximum width of the rendered image in jumbo mode. Jumbo rendering consumes additional renders and requires jumbo_max_height. Supply both jumbo dimensions. Each must be greater than 0 and no more than 80000; at least one must exceed 8000; total area cannot exceed 400000000 pixels.", "format": "int32" }, "transparent_background": { "type": [ "null", "boolean" ], "description": "Specifies whether the image is rendered with a transparent background." }, "format": { "oneOf": [ { "type": "null" }, { "description": "Sets the file extension on the URL returned by the image creation request. It does not change the stored source image or restrict later rendering to this format. Valid values: png, jpg, jpeg, webp, or pdf. This parameter is accepted only in POST request bodies.", "$ref": "#/components/schemas/ImageFormat" } ] }, "request_overrides": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/RequestOverride" }, "description": "Rules that override browser network requests. The block action blocks requests matching a URL wildcard pattern and/or resource types. When both matchers are supplied, both must match. A request is blocked if any block rule matches. Omitted, null, or an empty array adds no overrides. Requires a paid plan. Accepts a JSON array in JSON requests or a JSON-encoded array string in form requests. Maximum 100 rules and 512 characters per URL pattern. Each block rule requires a nonempty URL pattern or at least one resource type; supplied matchers cannot be empty. Not supported in query strings." } } }, "ImageRequestImageRequest_Templated": { "title": "Templated Image Request", "required": [ "template_values" ], "properties": { "template_values": { "description": "Values substituted into the template for this render. Must be a non-empty JSON object. Include the values needed by the template.", "$ref": "#/components/schemas/JsonObject" }, "format": { "oneOf": [ { "type": "null" }, { "description": "Sets the file extension on the URL returned by the image creation request. It does not change the stored source image or restrict later rendering to this format. Valid values: png, jpg, jpeg, webp, or pdf. This parameter is accepted only in POST request bodies.", "$ref": "#/components/schemas/ImageFormat" } ] } } }, "ImageRequestImageRequest_Url": { "title": "URL Image Request", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Public HTTP or HTTPS URL to capture. Required for URL image requests." }, "css": { "type": [ "null", "string" ], "description": "CSS injected into the loaded URL to override styles on the page." }, "device_scale": { "maximum": 3, "minimum": 0.1, "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "description": "Adjusts the pixel ratio used for the screenshot. Minimum: 0.1. Maximum: 3. HTML and template renders default to 2; URL renders default to 1.", "format": "double" }, "full_screen": { "type": [ "null", "boolean" ], "description": "Take a screenshot of the entire screen after scrolling down and back to the top." }, "max_wait_ms": { "maximum": 10000, "minimum": 500, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Sets a limit on how long to wait before taking the screenshot when the page continues loading irrelevant content. Minimum: 500. Maximum: 10000 and subject to the account plan limit.", "format": "int32" }, "metadata": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "Custom key-value metadata stored with the image." }, "ms_delay": { "maximum": 10000, "minimum": 0, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Adds extra time in milliseconds before taking the screenshot so JavaScript can execute. Minimum: 0. Maximum: 10000.", "format": "int32", "default": 0 }, "render_when_ready": { "type": [ "null", "boolean" ], "description": "Waits until the page signals that the screenshot is ready. The image fails if the readiness signal is never sent." }, "selector": { "type": [ "null", "string" ], "description": "A CSS selector for an element in the HTML. We’ll crop the image to this specific element." }, "viewport_height": { "maximum": 6000, "minimum": 1, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Sets the height of Chrome's viewport and disables automatic cropping. Minimum: 1. Maximum: 6000. Both viewport dimensions must be supplied together.", "format": "int32" }, "viewport_width": { "maximum": 6000, "minimum": 1, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Sets the width of Chrome's viewport and disables automatic cropping. Minimum: 1. Maximum: 6000. Both viewport dimensions must be supplied together.", "format": "int32" }, "pdf_options": { "oneOf": [ { "type": "null" }, { "description": "Options used when generating a PDF instead of an image. Page dimensions and margins must include supported PDF units; margins must contain either zero or four values; scale must be between 0.1 and 2.", "$ref": "#/components/schemas/PDFOptions" } ] }, "disable_twemoji": { "type": [ "null", "boolean" ], "description": "Set explicitly to false to inject Twemoji into the loaded page. Omitted, null, or true leaves the page's emoji handling unchanged and does not disable the website's own emoji scripts." }, "dedupe_duration_s": { "maximum": 31536000, "minimum": 0, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Reuse an existing image with identical content if it was created within this many seconds. Minimum: 0. Maximum: 31536000. Availability and maximum effective duration depend on the account plan.", "format": "int32" }, "max_render_once": { "type": [ "null", "boolean" ], "description": "Ensure the image is only ever rendered and saved one time. This is an advanced option not applicable to most requests." }, "color_scheme": { "oneOf": [ { "type": "null" }, { "description": "Sets Chrome's preferred color scheme. Valid values: light or dark.", "$ref": "#/components/schemas/ColorSchemeType" } ] }, "timezone": { "type": [ "null", "string" ], "description": "Sets the IANA timezone used by Chrome while rendering. Must be a recognized IANA timezone identifier." }, "block_consent_banners": { "type": [ "null", "boolean" ], "description": "Attempt to block cookie/consent banners from displaying." }, "identify_as_hcti": { "type": [ "null", "boolean" ], "description": "Identify the top-level page navigation as an HCTI screenshot request using the X-HCTI-SCREENSHOT header." }, "headers": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "HTTP headers to include on top-level page navigations to the requested URL's origin and any additional_header_origins. Supports up to 20 headers with names up to 512 ASCII characters and values up to 8192 UTF-8 bytes. For GET and form-encoded requests, repeat this parameter using the format `headers=name:value`." }, "additional_header_origins": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Additional exact HTTP or HTTPS origins allowed to receive custom headers. Supports up to 20 unique origins of up to 512 UTF-8 bytes each. Origins must use the format scheme://host[:port] without a path; duplicates are ignored. For GET and form-encoded requests, repeat this parameter for each origin." }, "include_headers_on_subrequests": { "type": [ "null", "boolean" ], "description": "Include custom headers on subrequests to the requested URL's origin and any additional_header_origins. Defaults to false. Requires at least one header." }, "viewport_mobile": { "type": [ "null", "boolean" ], "description": "Specifies whether the page uses mobile viewport behavior, including its viewport meta tag." }, "viewport_landscape": { "type": [ "null", "boolean" ], "description": "Specifies whether the emulated viewport is in landscape orientation." }, "viewport_touch": { "type": [ "null", "boolean" ], "description": "Specifies whether the emulated viewport supports touch events." }, "media_type": { "oneOf": [ { "type": "null" }, { "description": "Sets the CSS media type used while rendering the page. Valid values: print or screen.", "$ref": "#/components/schemas/MediaType" } ] }, "proxy_id": { "type": [ "null", "string" ], "description": "Specifies which configured organization proxy to use when rendering." }, "storage_destination_id": { "type": [ "null", "string" ], "description": "Specifies which configured organization storage destination receives the rendered image." }, "jumbo_max_height": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Maximum height of the rendered image in jumbo mode. Jumbo rendering consumes additional renders and requires jumbo_max_width. Supply both jumbo dimensions. Each must be greater than 0 and no more than 80000; at least one must exceed 8000; total area cannot exceed 400000000 pixels.", "format": "int32" }, "jumbo_max_width": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Maximum width of the rendered image in jumbo mode. Jumbo rendering consumes additional renders and requires jumbo_max_height. Supply both jumbo dimensions. Each must be greater than 0 and no more than 80000; at least one must exceed 8000; total area cannot exceed 400000000 pixels.", "format": "int32" }, "transparent_background": { "type": [ "null", "boolean" ], "description": "Specifies whether the image is rendered with a transparent background." }, "format": { "oneOf": [ { "type": "null" }, { "description": "Sets the file extension on the URL returned by the image creation request. It does not change the stored source image or restrict later rendering to this format. Valid values: png, jpg, jpeg, webp, or pdf. This parameter is accepted only in POST request bodies.", "$ref": "#/components/schemas/ImageFormat" } ] }, "request_overrides": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/RequestOverride" }, "description": "Rules that override browser network requests. The block action blocks requests matching a URL wildcard pattern and/or resource types. When both matchers are supplied, both must match. A request is blocked if any block rule matches. Omitted, null, or an empty array adds no overrides. Requires a paid plan. Accepts a JSON array in JSON requests or a JSON-encoded array string in form requests. Maximum 100 rules and 512 characters per URL pattern. Each block rule requires a nonempty URL pattern or at least one resource type; supplied matchers cannot be empty. Not supported in query strings." } } }, "ImageResultWithId": { "type": "object", "properties": { "url": { "type": "string" }, "id": { "type": "string" } } }, "ImageTemplateBase": { "title": "Base Image Template", "required": [ "template_type" ], "type": "object", "anyOf": [ { "$ref": "#/components/schemas/ImageTemplateBaseImageTemplate_HtmlCss" }, { "$ref": "#/components/schemas/ImageTemplateBaseImageTemplate_Blocks" } ], "description": "A saved image template version. template_type identifies the html_css or blocks variant. Use id as the template identifier and version to render a specific saved version. Nullable rendering settings are stored overrides; null means the setting is unset.", "discriminator": { "propertyName": "template_type", "mapping": { "html_css": "#/components/schemas/ImageTemplateBaseImageTemplate_HtmlCss", "blocks": "#/components/schemas/ImageTemplateBaseImageTemplate_Blocks" } } }, "ImageTemplateBaseImageTemplate_Blocks": { "title": "Blocks Image Template", "properties": { "template_type": { "enum": [ "blocks" ], "type": "string" }, "block_counts": { "type": "object", "additionalProperties": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "uint16" }, "description": "The number of each block type used in this template." }, "variables": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateVariable" }, "description": "Discovered template variables and their value requirements. Use these entries to prepare template_values for a rendering request." }, "id": { "type": "string", "description": "Unique template identifier used when rendering or updating this template." }, "version": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Saved template version identifier. Specify it when rendering to select this exact version.", "format": "int64" }, "name": { "type": [ "null", "string" ], "description": "The name of the template, used to identify it in your account." }, "description": { "type": [ "null", "string" ], "description": "A description of the template." }, "created_at": { "type": "string", "description": "UTC timestamp when this template version was created.", "format": "date-time" }, "updated_at": { "type": "string", "description": "UTC timestamp when this template version was last updated.", "format": "date-time" }, "device_scale": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "description": "Stored screenshot pixel ratio. For example, 2 produces two output pixels per CSS pixel in each dimension. Null uses the rendering default.", "format": "double" }, "viewport_height": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Stored browser viewport height in CSS pixels. Used with viewport_width; setting both disables automatic cropping.", "format": "int32" }, "viewport_width": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Stored browser viewport width in CSS pixels. Used with viewport_height; output pixel dimensions also depend on device_scale.", "format": "int32" }, "disable_twemoji": { "type": [ "null", "boolean" ], "description": "Whether native emoji rendering is used instead of Twemoji. Null leaves the rendering default in effect." }, "max_wait_ms": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Stored loading-wait limit in milliseconds before capture.", "format": "int32" }, "ms_delay": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Stored additional delay in milliseconds before capture, used to allow client-side content to finish updating.", "format": "int32" }, "selector": { "type": [ "null", "string" ], "description": "CSS selector used to crop rendered images to an element. Preserve this setting when updating the template unless the intended crop changes." }, "render_when_ready": { "type": [ "null", "boolean" ], "description": "Whether capture waits for the template's JavaScript to call ScreenshotReady(). When enabled, rendering fails if the readiness signal is never sent." }, "request_overrides": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/RequestOverride" }, "description": "Stored browser request overrides. Block rules match URL wildcard patterns and/or resource types; supplied matchers must all match. Null or an empty array adds no overrides." }, "render_count": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Number of image creations recorded for this template version. Organization-wide image-credit usage is reported separately.", "format": "int64" }, "color_scheme": { "oneOf": [ { "type": "null" }, { "description": "Stored light or dark color-scheme preference exposed to the rendered page's CSS.", "$ref": "#/components/schemas/ColorSchemeType" } ] }, "timezone": { "type": [ "null", "string" ], "description": "Stored IANA timezone identifier exposed to the rendered page, such as America/New_York or UTC." }, "viewport_mobile": { "type": [ "null", "boolean" ], "description": "Whether mobile viewport emulation is enabled, including support for the page's meta viewport tag." }, "viewport_landscape": { "type": [ "null", "boolean" ], "description": "Whether the emulated viewport uses landscape orientation." }, "viewport_touch": { "type": [ "null", "boolean" ], "description": "Whether touch support is exposed to the rendered page." }, "media_type": { "oneOf": [ { "type": "null" }, { "description": "Stored CSS media mode: print or screen.", "$ref": "#/components/schemas/MediaType" } ] }, "proxy_id": { "type": [ "null", "string" ], "description": "Identifier of the configured organization proxy used for rendering. Proxy connection details are available through the proxy configuration." }, "jumbo_max_height": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Stored maximum output height in pixels for jumbo rendering. Used with jumbo_max_width; jumbo rendering consumes additional image credits.", "format": "int32" }, "jumbo_max_width": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Stored maximum output width in pixels for jumbo rendering. Used with jumbo_max_height.", "format": "int32" }, "transparent_background": { "type": [ "null", "boolean" ], "description": "Whether the browser's default background is transparent. Backgrounds explicitly painted by the template's HTML or CSS still apply." }, "storage_destination_id": { "type": [ "null", "string" ], "description": "Identifier of the configured destination for rendered files. The destination configuration specifies its provider, enabled state, and storage behavior." } }, "description": "A template with template_type: blocks, authored in the visual template editor. Contains block counts and variable requirements for rendering. Edit the block design in the template editor." }, "ImageTemplateBaseImageTemplate_HtmlCss": { "title": "HTML/CSS Image Template", "properties": { "template_type": { "enum": [ "html_css" ], "type": "string" }, "css": { "title": "CSS", "type": [ "null", "string" ], "description": "CSS used to style your templated images. You cannot use handlebars inside of the CSS; if you want to define variables for your CSS, it should be inlined in your HTML." }, "html": { "title": "HTML", "type": [ "null", "string" ], "description": "HTML to render for your template. Use handlebars to place variables that will be substituted in the final rendered image." }, "google_fonts": { "type": [ "null", "string" ], "description": "Google Font families loaded for this template, separated by |. The HTML or CSS must reference the families to use them." }, "id": { "type": "string", "description": "Unique template identifier used when rendering or updating this template." }, "version": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Saved template version identifier. Specify it when rendering to select this exact version.", "format": "int64" }, "name": { "type": [ "null", "string" ], "description": "The name of the template, used to identify it in your account." }, "description": { "type": [ "null", "string" ], "description": "A description of the template." }, "created_at": { "type": "string", "description": "UTC timestamp when this template version was created.", "format": "date-time" }, "updated_at": { "type": "string", "description": "UTC timestamp when this template version was last updated.", "format": "date-time" }, "device_scale": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "description": "Stored screenshot pixel ratio. For example, 2 produces two output pixels per CSS pixel in each dimension. Null uses the rendering default.", "format": "double" }, "viewport_height": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Stored browser viewport height in CSS pixels. Used with viewport_width; setting both disables automatic cropping.", "format": "int32" }, "viewport_width": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Stored browser viewport width in CSS pixels. Used with viewport_height; output pixel dimensions also depend on device_scale.", "format": "int32" }, "disable_twemoji": { "type": [ "null", "boolean" ], "description": "Whether native emoji rendering is used instead of Twemoji. Null leaves the rendering default in effect." }, "max_wait_ms": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Stored loading-wait limit in milliseconds before capture.", "format": "int32" }, "ms_delay": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Stored additional delay in milliseconds before capture, used to allow client-side content to finish updating.", "format": "int32" }, "selector": { "type": [ "null", "string" ], "description": "CSS selector used to crop rendered images to an element. Preserve this setting when updating the template unless the intended crop changes." }, "render_when_ready": { "type": [ "null", "boolean" ], "description": "Whether capture waits for the template's JavaScript to call ScreenshotReady(). When enabled, rendering fails if the readiness signal is never sent." }, "request_overrides": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/RequestOverride" }, "description": "Stored browser request overrides. Block rules match URL wildcard patterns and/or resource types; supplied matchers must all match. Null or an empty array adds no overrides." }, "render_count": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Number of image creations recorded for this template version. Organization-wide image-credit usage is reported separately.", "format": "int64" }, "color_scheme": { "oneOf": [ { "type": "null" }, { "description": "Stored light or dark color-scheme preference exposed to the rendered page's CSS.", "$ref": "#/components/schemas/ColorSchemeType" } ] }, "timezone": { "type": [ "null", "string" ], "description": "Stored IANA timezone identifier exposed to the rendered page, such as America/New_York or UTC." }, "viewport_mobile": { "type": [ "null", "boolean" ], "description": "Whether mobile viewport emulation is enabled, including support for the page's meta viewport tag." }, "viewport_landscape": { "type": [ "null", "boolean" ], "description": "Whether the emulated viewport uses landscape orientation." }, "viewport_touch": { "type": [ "null", "boolean" ], "description": "Whether touch support is exposed to the rendered page." }, "media_type": { "oneOf": [ { "type": "null" }, { "description": "Stored CSS media mode: print or screen.", "$ref": "#/components/schemas/MediaType" } ] }, "proxy_id": { "type": [ "null", "string" ], "description": "Identifier of the configured organization proxy used for rendering. Proxy connection details are available through the proxy configuration." }, "jumbo_max_height": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Stored maximum output height in pixels for jumbo rendering. Used with jumbo_max_width; jumbo rendering consumes additional image credits.", "format": "int32" }, "jumbo_max_width": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Stored maximum output width in pixels for jumbo rendering. Used with jumbo_max_height.", "format": "int32" }, "transparent_background": { "type": [ "null", "boolean" ], "description": "Whether the browser's default background is transparent. Backgrounds explicitly painted by the template's HTML or CSS still apply." }, "storage_destination_id": { "type": [ "null", "string" ], "description": "Identifier of the configured destination for rendered files. The destination configuration specifies its provider, enabled state, and storage behavior." } }, "description": "A template with template_type: html_css. Contains the saved HTML, CSS, and rendering settings. Supply template_values when rendering to substitute placeholder values; update the template to change the saved design." }, "JsonNode": { }, "JsonObject": { "type": "object" }, "ListOfTemplates": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ImageTemplateBase" } }, "pagination": { "$ref": "#/components/schemas/PaginationInfoOflong" } } }, "MediaType": { "enum": [ "print", "screen", null ] }, "OgConfig": { "title": "OG Config", "required": [ "config_type" ], "type": "object", "anyOf": [ { "$ref": "#/components/schemas/OgConfigOgConfig_HtmlCss" }, { "$ref": "#/components/schemas/OgConfigOgConfig_Templated" } ], "description": "An Open Graph image configuration.", "discriminator": { "propertyName": "config_type", "mapping": { "html_css": "#/components/schemas/OgConfigOgConfig_HtmlCss", "templated": "#/components/schemas/OgConfigOgConfig_Templated" } } }, "OgConfigOgConfig_HtmlCss": { "title": "HTML/CSS OG Config", "required": [ "id", "domain_id", "base_url" ], "properties": { "config_type": { "enum": [ "html_css" ], "type": "string" }, "default_options": { "oneOf": [ { "type": "null" }, { "description": "Default image rendering options for pages served by this configuration. Extracted image options override these defaults.", "$ref": "#/components/schemas/OgDefaultImageOptions" } ] }, "extract_values": { "type": "boolean", "description": "Whether image options are extracted from page metadata. When disabled, only the configured defaults are used." }, "id": { "type": "string" }, "domain_id": { "type": "string", "description": "Domain identifier used in this configuration's Open Graph image URLs." }, "name": { "type": [ "null", "string" ] }, "description": { "type": [ "null", "string" ] }, "base_url": { "type": "string" }, "optimization_mode": { "$ref": "#/components/schemas/OgSocialSizeOptimizationMode" }, "enabled": { "type": "boolean", "description": "Whether the configuration is enabled to serve Open Graph images." }, "refresh_interval_s": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "uint32" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "description": "An Open Graph configuration that renders page HTML/CSS." }, "OgConfigOgConfig_Templated": { "title": "Templated OG Config", "required": [ "template_id", "id", "domain_id", "base_url" ], "properties": { "config_type": { "enum": [ "templated" ], "type": "string" }, "template_id": { "type": "string", "description": "ID of the template used to render images." }, "template_version": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Template version used to render images. Null means the latest version is used.", "format": "int64" }, "template_values_mapping": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/OgTemplateValueMapping" }, "description": "Mappings from page metadata to template fields. Each mapping uses either a meta_key or a fallback." }, "headers": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "Custom HTTP headers sent on top-level page navigations to the source website's origin and any additional_header_origins." }, "additional_header_origins": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Additional exact HTTP or HTTPS origins allowed to receive custom headers, in the format scheme://host[:port] without a path." }, "id": { "type": "string" }, "domain_id": { "type": "string", "description": "Domain identifier used in this configuration's Open Graph image URLs." }, "name": { "type": [ "null", "string" ] }, "description": { "type": [ "null", "string" ] }, "base_url": { "type": "string" }, "optimization_mode": { "$ref": "#/components/schemas/OgSocialSizeOptimizationMode" }, "enabled": { "type": "boolean", "description": "Whether the configuration is enabled to serve Open Graph images." }, "refresh_interval_s": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "uint32" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "description": "An Open Graph configuration that renders a template using extracted page metadata." }, "OgDefaultImageOptions": { "type": "object", "properties": { "css": { "type": [ "null", "string" ], "description": "CSS injected into the loaded page to override its styles." }, "device_scale": { "maximum": 3, "minimum": 0.1, "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "description": "Adjusts the pixel ratio used for the screenshot. Minimum: 0.1. Maximum: 3. HTML and template renders default to 2; URL renders default to 1.", "format": "double" }, "max_wait_ms": { "maximum": 10000, "minimum": 500, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Sets a limit on how long to wait before taking the screenshot when the page continues loading irrelevant content. Minimum: 500. Maximum: 10000 and subject to the account plan limit.", "format": "int32" }, "ms_delay": { "maximum": 10000, "minimum": 0, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Adds extra time in milliseconds before taking the screenshot so JavaScript can execute. Minimum: 0. Maximum: 10000.", "format": "int32", "default": 0 }, "render_when_ready": { "type": [ "null", "boolean" ], "description": "Waits until the page signals that the screenshot is ready. The image fails if the readiness signal is never sent." }, "selector": { "type": [ "null", "string" ], "description": "A CSS selector for an element in the HTML. We’ll crop the image to this specific element." }, "viewport_height": { "maximum": 6000, "minimum": 1, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Sets the height of Chrome's viewport and disables automatic cropping. Minimum: 1. Maximum: 6000. Both viewport dimensions must be supplied together.", "format": "int32" }, "viewport_width": { "maximum": 6000, "minimum": 1, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Sets the width of Chrome's viewport and disables automatic cropping. Minimum: 1. Maximum: 6000. Both viewport dimensions must be supplied together.", "format": "int32" }, "disable_twemoji": { "type": [ "null", "boolean" ], "description": "Set explicitly to false to inject Twemoji into the captured URL page. Omitted, null, or true leaves the page's emoji handling unchanged and does not disable the website's own emoji scripts." }, "color_scheme": { "oneOf": [ { "type": "null" }, { "description": "Sets Chrome's preferred color scheme. Valid values: light or dark.", "$ref": "#/components/schemas/ColorSchemeType" } ] }, "timezone": { "type": [ "null", "string" ], "description": "Sets the IANA timezone used by Chrome while rendering. Must be a recognized IANA timezone identifier." }, "block_consent_banners": { "type": [ "null", "boolean" ], "description": "Attempt to block cookie/consent banners from displaying." }, "identify_as_hcti": { "type": [ "null", "boolean" ], "description": "Identify the top-level page navigation as an HCTI screenshot request using the X-HCTI-SCREENSHOT header." }, "headers": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "HTTP headers to include on top-level page navigations to the requested URL's origin and any additional_header_origins. Supports up to 20 headers with names up to 512 ASCII characters and values up to 8192 UTF-8 bytes. For GET and form-encoded requests, repeat this parameter using the format `headers=name:value`." }, "additional_header_origins": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Additional exact HTTP or HTTPS origins allowed to receive custom headers. Supports up to 20 unique origins of up to 512 UTF-8 bytes each. Origins must use the format scheme://host[:port] without a path; duplicates are ignored. For GET and form-encoded requests, repeat this parameter for each origin." }, "include_headers_on_subrequests": { "type": [ "null", "boolean" ], "description": "Include custom headers on subrequests to the requested URL's origin and any additional_header_origins. Defaults to false. Requires at least one header." }, "viewport_mobile": { "type": [ "null", "boolean" ], "description": "Specifies whether the page uses mobile viewport behavior, including its viewport meta tag." }, "viewport_landscape": { "type": [ "null", "boolean" ], "description": "Specifies whether the emulated viewport is in landscape orientation." }, "viewport_touch": { "type": [ "null", "boolean" ], "description": "Specifies whether the emulated viewport supports touch events." }, "media_type": { "oneOf": [ { "type": "null" }, { "description": "Sets the CSS media type used while rendering the page. Valid values: print or screen.", "$ref": "#/components/schemas/MediaType" } ] }, "proxy_id": { "type": [ "null", "string" ] }, "storage_destination_id": { "type": [ "null", "string" ] }, "transparent_background": { "type": [ "null", "boolean" ], "description": "Specifies whether the image is rendered with a transparent background." }, "request_overrides": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/RequestOverride" }, "description": "Rules that override browser network requests. The block action blocks requests matching a URL wildcard pattern and/or resource types. When both matchers are supplied, both must match. A request is blocked if any block rule matches. Omitted, null, or an empty array adds no overrides. Requires a paid plan. Set default_options.request_overrides to a JSON array. Maximum 100 rules and 512 characters per URL pattern. Each block rule requires a nonempty URL pattern or at least one resource type; supplied matchers cannot be empty. Not supported in hcti: meta tags." } } }, "OgSocialSizeOptimizationMode": { "enum": [ "no_optimization", "post_process", "set_viewport" ], "description": "How images are sized for different social platforms." }, "OgTemplateValueFallback": { "enum": [ "titles", "descriptions", null ] }, "OgTemplateValueMapping": { "required": [ "template_key" ], "type": "object", "properties": { "template_key": { "maxLength": 128, "type": "string", "description": "Template field path to populate, up to 128 characters." }, "meta_key": { "maxLength": 136, "type": [ "null", "string" ], "description": "Meta tag name or property, such as og:title or twitter:description. Supply this or fallback, not both." }, "fallback": { "oneOf": [ { "type": "null" }, { "description": "Use the page's available title or description metadata. Supply this or meta_key, not both.", "$ref": "#/components/schemas/OgTemplateValueFallback" } ] } }, "description": "Maps page metadata to a template field. Supply exactly one of meta_key or fallback." }, "PaginatedListBaseOfApiKeyAndstring": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } }, "pagination": { "$ref": "#/components/schemas/PaginationInfoOfstring" } } }, "PaginatedListBaseOfOgConfigAndstring": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OgConfig" } }, "pagination": { "$ref": "#/components/schemas/PaginationInfoOfstring" } } }, "PaginatedListBaseOfProxyAndstring": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Proxy" } }, "pagination": { "$ref": "#/components/schemas/PaginationInfoOfstring" } } }, "PaginatedListBaseOfStorageDestinationAndstring": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StorageDestination" } }, "pagination": { "$ref": "#/components/schemas/PaginationInfoOfstring" } } }, "PaginationInfoOflong": { "required": [ "next_page_start" ], "type": "object", "properties": { "next_page_start": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int64" } } }, "PaginationInfoOfstring": { "required": [ "next_page_start" ], "type": "object", "properties": { "next_page_start": { "type": [ "null", "string" ] } } }, "PDFOptions": { "type": "object", "properties": { "page_height": { "type": [ "null", "string" ], "description": "Height of the page, with unit (px, in, cm, mm, pt)" }, "page_width": { "type": [ "null", "string" ], "description": "Width of the page, with unit (px, in, cm, mm, pt)" }, "scale": { "maximum": 2, "minimum": 0.1, "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "description": "Scale of the webpage rendering. Defaults to 1.", "format": "double" }, "margins": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Margins of the webpage rendering. Defaults to 0. 4 values must be supplied: top, right, bottom, left. Units are px, cm, in, mm, or pt." }, "print_background": { "type": "boolean", "description": "Print background graphics." } } }, "PerBillingPeriodCounter": { "type": "object", "properties": { "total_images": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Number of images counted in this billing period. For a period still in progress, this is the usage recorded so far.", "format": "int32" }, "start": { "type": "string", "description": "Start of the billing period, as an ISO 8601 UTC timestamp.", "format": "date-time" }, "end": { "type": [ "null", "string" ], "description": "End of the billing period, as an ISO 8601 UTC timestamp, when available. A future timestamp indicates a period that has not yet ended.", "format": "date-time" } }, "description": "Image usage within a single billing period." }, "Proxy": { "required": [ "id", "name", "url", "bypass_hosts" ], "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "port": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "uint16" }, "bypass_hosts": { "type": "array", "items": { "type": "string" } }, "username": { "type": [ "null", "string" ], "description": "Configured proxy username, or null when authentication is not configured. An empty string is a valid username. Passwords are never returned." }, "enabled": { "type": "boolean", "description": "Whether the proxy is enabled." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ProxyAuthentication": { "required": [ "username" ], "type": "object", "properties": { "username": { "maxLength": 512, "type": "string", "description": "Proxy username, up to 512 characters. May be empty. Whitespace is preserved." }, "password": { "maxLength": 484, "type": [ "null", "string" ], "description": "Proxy password, up to 484 UTF-8 bytes. Required on create. On update, omitted or null is allowed only with retain_password: true. An empty string is a replacement password. Whitespace is preserved." }, "retain_password": { "type": [ "null", "boolean" ], "description": "Retain the existing password. Only true retains the password. Omitted, null, or false requires a supplied password, including on updates. Explicit true requires an existing password and unchanged username, and cannot be combined with a supplied password. False requires a password; use an empty string for an empty password, or authentication: null to remove authentication." } }, "description": "Proxy credentials. Username is required. Supply a password or retain the existing password on update. Empty strings and whitespace are preserved exactly." }, "RequestOverride": { "required": [ "action" ], "type": "object", "anyOf": [ { "$ref": "#/components/schemas/RequestOverrideRequestOverrideBlock" } ], "description": "A browser request override. The action discriminator selects the rule type; currently only block is supported.", "discriminator": { "propertyName": "action", "mapping": { "block": "#/components/schemas/RequestOverrideRequestOverrideBlock" } } }, "RequestOverrideRequestOverrideBlock": { "properties": { "action": { "enum": [ "block" ], "type": "string" }, "url": { "type": [ "null", "string" ], "description": "URL wildcard pattern to match, using * for any sequence of characters. When resource_types is also supplied, both matchers must match." }, "resource_types": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/RequestOverrideResourceType" }, "description": "Resource types to match, supplied as an array of names, such as image, script, xhr, or fetch. Any listed type may match. When url is also supplied, it must match too." } } }, "RequestOverrideResourceType": { "enum": [ "beacon", "document", "stylesheet", "image", "image_set", "media", "font", "script", "text_track", "xhr", "fetch", "event_source", "manifest", "ping", "img", "other" ] }, "SimpleImage": { "required": [ "created_at", "id", "url" ], "type": "object", "properties": { "created_at": { "type": "string", "description": "Date and time the image was created, in UTC.", "format": "date-time" }, "id": { "type": "string", "description": "Unique image ID. Use this value to retrieve the image's full metadata." }, "url": { "type": "string", "description": "HCTI render URL for this image, or the authenticated store endpoint URL when HCTI storage is disabled." } }, "description": "Summary of a created image returned by the image listing endpoint. Retrieve the image by ID for full metadata." }, "StorageDestination": { "required": [ "id", "name", "connection_info" ], "type": "object", "properties": { "id": { "type": "string", "description": "Storage destination ID." }, "name": { "maxLength": 255, "type": "string", "description": "Display name for the destination." }, "enabled": { "type": "boolean", "description": "Whether the destination is enabled." }, "hcti_storage_disabled": { "type": "boolean", "description": "Whether rendered files saved here are excluded from HCTI storage and the HCTI CDN, with no public HCTI image URL." }, "provider": { "type": "string", "description": "Display name of the storage provider, retained for compatibility. Use connection_info.provider for the provider's machine-readable identifier." }, "connection_info": { "description": "Provider-specific connection details, without the secret access key.", "$ref": "#/components/schemas/StorageDestinationConnectionInfo" }, "last_tested_at": { "type": [ "null", "string" ], "description": "UTC timestamp of the most recent connection test, or null if it has not been tested.", "format": "date-time" }, "last_test_succeeded": { "type": [ "null", "boolean" ], "description": "Whether the most recent write test succeeded, or null if it has not been tested. This does not verify read access or guarantee future availability." }, "last_test_error": { "maxLength": 1024, "type": [ "null", "string" ], "description": "Sanitized error from the most recent failed connection test, or null when no failure is recorded." }, "created_at": { "type": "string", "description": "UTC timestamp when the destination was created.", "format": "date-time" }, "updated_at": { "type": "string", "description": "UTC timestamp when the destination was last updated.", "format": "date-time" } }, "description": "A storage destination and the result of its most recent connection test. Secret access keys are never returned." }, "StorageDestinationConnectionInfo": { "title": "Storage Connection Info", "required": [ "provider" ], "type": "object", "anyOf": [ { "$ref": "#/components/schemas/StorageDestinationConnectionInfoStorageDestinationConnectionInfo_AwsS3" }, { "$ref": "#/components/schemas/StorageDestinationConnectionInfoStorageDestinationConnectionInfo_CloudflareR2" }, { "$ref": "#/components/schemas/StorageDestinationConnectionInfoStorageDestinationConnectionInfo_BackblazeB2" }, { "$ref": "#/components/schemas/StorageDestinationConnectionInfoStorageDestinationConnectionInfo_DigitalOceanSpaces" }, { "$ref": "#/components/schemas/StorageDestinationConnectionInfoStorageDestinationConnectionInfo_Wasabi" }, { "$ref": "#/components/schemas/StorageDestinationConnectionInfoStorageDestinationConnectionInfo_GoogleCloudStorage" }, { "$ref": "#/components/schemas/StorageDestinationConnectionInfoStorageDestinationConnectionInfo_OtherS3Compatible" } ], "description": "Provider-specific storage connection details. Secret access keys are never returned.", "discriminator": { "propertyName": "provider", "mapping": { "aws_s3": "#/components/schemas/StorageDestinationConnectionInfoStorageDestinationConnectionInfo_AwsS3", "cloudflare_r2": "#/components/schemas/StorageDestinationConnectionInfoStorageDestinationConnectionInfo_CloudflareR2", "backblaze_b2": "#/components/schemas/StorageDestinationConnectionInfoStorageDestinationConnectionInfo_BackblazeB2", "digitalocean_spaces": "#/components/schemas/StorageDestinationConnectionInfoStorageDestinationConnectionInfo_DigitalOceanSpaces", "wasabi": "#/components/schemas/StorageDestinationConnectionInfoStorageDestinationConnectionInfo_Wasabi", "google_cloud_storage": "#/components/schemas/StorageDestinationConnectionInfoStorageDestinationConnectionInfo_GoogleCloudStorage", "other_s3_compatible": "#/components/schemas/StorageDestinationConnectionInfoStorageDestinationConnectionInfo_OtherS3Compatible" } } }, "StorageDestinationConnectionInfoStorageDestinationConnectionInfo_AwsS3": { "title": "AWS S3 Connection Info", "required": [ "region", "role_arn", "bucket" ], "properties": { "provider": { "enum": [ "aws_s3" ], "type": "string" }, "region": { "description": "AWS region containing the bucket, for example us-east-1.", "$ref": "#/components/schemas/AwsStorageRegion" }, "role_arn": { "maxLength": 2048, "type": "string", "description": "ARN of the IAM role HCTI assumes to access the bucket. Configure its trust policy for this organization before saving." }, "bucket": { "maxLength": 255, "type": "string", "description": "Name of the existing bucket or Space. HCTI does not create it." }, "key_prefix": { "maxLength": 1024, "type": [ "null", "string" ], "description": "Optional prefix for object keys within the bucket. Omitted or null uses the bucket root." } }, "description": "Connection details for Amazon S3." }, "StorageDestinationConnectionInfoStorageDestinationConnectionInfo_BackblazeB2": { "title": "Backblaze B2 Connection Info", "required": [ "region", "access_key_id", "bucket" ], "properties": { "provider": { "enum": [ "backblaze_b2" ], "type": "string" }, "region": { "description": "Region code from the bucket's S3 endpoint, for example us-west-004.", "$ref": "#/components/schemas/BackblazeStorageRegion" }, "access_key_id": { "maxLength": 512, "type": "string", "description": "S3-compatible access key ID. For Google Cloud Storage, use an HMAC access ID beginning with GOOG." }, "bucket": { "maxLength": 255, "type": "string", "description": "Name of the existing bucket or Space. HCTI does not create it." }, "key_prefix": { "maxLength": 1024, "type": [ "null", "string" ], "description": "Optional prefix for object keys within the bucket. Omitted or null uses the bucket root." } }, "description": "Connection details for Backblaze B2." }, "StorageDestinationConnectionInfoStorageDestinationConnectionInfo_CloudflareR2": { "title": "Cloudflare R2 Connection Info", "required": [ "cloudflare_account_id", "access_key_id", "bucket" ], "properties": { "provider": { "enum": [ "cloudflare_r2" ], "type": "string" }, "cloudflare_account_id": { "maxLength": 32, "type": "string", "description": "The 32-character hexadecimal Cloudflare account ID that owns the bucket." }, "cloudflare_jurisdiction": { "oneOf": [ { "type": "null" }, { "description": "Bucket jurisdiction: eu or fedramp. Omit or set to null for the default jurisdiction.", "$ref": "#/components/schemas/CloudflareStorageJurisdiction" } ] }, "access_key_id": { "maxLength": 512, "type": "string", "description": "S3-compatible access key ID. For Google Cloud Storage, use an HMAC access ID beginning with GOOG." }, "bucket": { "maxLength": 255, "type": "string", "description": "Name of the existing bucket or Space. HCTI does not create it." }, "key_prefix": { "maxLength": 1024, "type": [ "null", "string" ], "description": "Optional prefix for object keys within the bucket. Omitted or null uses the bucket root." } }, "description": "Connection details for Cloudflare R2." }, "StorageDestinationConnectionInfoStorageDestinationConnectionInfo_DigitalOceanSpaces": { "title": "DigitalOcean Spaces Connection Info", "required": [ "region", "access_key_id", "bucket" ], "properties": { "provider": { "enum": [ "digitalocean_spaces" ], "type": "string" }, "region": { "description": "Region containing the Space, for example nyc3.", "$ref": "#/components/schemas/DigitalOceanStorageRegion" }, "access_key_id": { "maxLength": 512, "type": "string", "description": "S3-compatible access key ID. For Google Cloud Storage, use an HMAC access ID beginning with GOOG." }, "bucket": { "maxLength": 255, "type": "string", "description": "Name of the existing bucket or Space. HCTI does not create it." }, "key_prefix": { "maxLength": 1024, "type": [ "null", "string" ], "description": "Optional prefix for object keys within the bucket. Omitted or null uses the bucket root." } }, "description": "Connection details for DigitalOcean Spaces." }, "StorageDestinationConnectionInfoStorageDestinationConnectionInfo_GoogleCloudStorage": { "title": "Google Cloud Storage Connection Info", "required": [ "access_key_id", "bucket" ], "properties": { "provider": { "enum": [ "google_cloud_storage" ], "type": "string" }, "access_key_id": { "maxLength": 512, "type": "string", "description": "S3-compatible access key ID. For Google Cloud Storage, use an HMAC access ID beginning with GOOG." }, "bucket": { "maxLength": 255, "type": "string", "description": "Name of the existing bucket or Space. HCTI does not create it." }, "key_prefix": { "maxLength": 1024, "type": [ "null", "string" ], "description": "Optional prefix for object keys within the bucket. Omitted or null uses the bucket root." } }, "description": "Connection details for Google Cloud Storage." }, "StorageDestinationConnectionInfoStorageDestinationConnectionInfo_OtherS3Compatible": { "title": "Other S3-Compatible Connection Info", "required": [ "endpoint", "access_key_id", "bucket" ], "properties": { "provider": { "enum": [ "other_s3_compatible" ], "type": "string" }, "endpoint": { "maxLength": 512, "type": "string", "description": "Public HTTPS endpoint of the S3-compatible service. Do not include a path, query string, fragment, or credentials." }, "region": { "maxLength": 64, "type": [ "null", "string" ], "description": "Signing region expected by the service. Omit or set to null to use us-east-1." }, "force_path_style": { "type": [ "null", "boolean" ], "description": "Whether to put the bucket name in the URL path instead of the hostname. Omitted or null defaults to true." }, "access_key_id": { "maxLength": 512, "type": "string", "description": "S3-compatible access key ID. For Google Cloud Storage, use an HMAC access ID beginning with GOOG." }, "bucket": { "maxLength": 255, "type": "string", "description": "Name of the existing bucket or Space. HCTI does not create it." }, "key_prefix": { "maxLength": 1024, "type": [ "null", "string" ], "description": "Optional prefix for object keys within the bucket. Omitted or null uses the bucket root." } }, "description": "Connection details for another S3-compatible provider." }, "StorageDestinationConnectionInfoStorageDestinationConnectionInfo_Wasabi": { "title": "Wasabi Connection Info", "required": [ "region", "access_key_id", "bucket" ], "properties": { "provider": { "enum": [ "wasabi" ], "type": "string" }, "region": { "description": "Region containing the bucket, for example us-east-1.", "$ref": "#/components/schemas/WasabiStorageRegion" }, "access_key_id": { "maxLength": 512, "type": "string", "description": "S3-compatible access key ID. For Google Cloud Storage, use an HMAC access ID beginning with GOOG." }, "bucket": { "maxLength": 255, "type": "string", "description": "Name of the existing bucket or Space. HCTI does not create it." }, "key_prefix": { "maxLength": 1024, "type": [ "null", "string" ], "description": "Optional prefix for object keys within the bucket. Omitted or null uses the bucket root." } }, "description": "Connection details for Wasabi." }, "StorageDestinationConnectionRequest": { "title": "Storage Connection Request", "required": [ "provider" ], "type": "object", "anyOf": [ { "$ref": "#/components/schemas/StorageDestinationConnectionRequestStorageDestinationConnectionRequest_AwsS3" }, { "$ref": "#/components/schemas/StorageDestinationConnectionRequestStorageDestinationConnectionRequest_CloudflareR2" }, { "$ref": "#/components/schemas/StorageDestinationConnectionRequestStorageDestinationConnectionRequest_BackblazeB2" }, { "$ref": "#/components/schemas/StorageDestinationConnectionRequestStorageDestinationConnectionRequest_DigitalOceanSpaces" }, { "$ref": "#/components/schemas/StorageDestinationConnectionRequestStorageDestinationConnectionRequest_Wasabi" }, { "$ref": "#/components/schemas/StorageDestinationConnectionRequestStorageDestinationConnectionRequest_GoogleCloudStorage" }, { "$ref": "#/components/schemas/StorageDestinationConnectionRequestStorageDestinationConnectionRequest_OtherS3Compatible" } ], "description": "Provider-specific storage connection settings.", "discriminator": { "propertyName": "provider", "mapping": { "aws_s3": "#/components/schemas/StorageDestinationConnectionRequestStorageDestinationConnectionRequest_AwsS3", "cloudflare_r2": "#/components/schemas/StorageDestinationConnectionRequestStorageDestinationConnectionRequest_CloudflareR2", "backblaze_b2": "#/components/schemas/StorageDestinationConnectionRequestStorageDestinationConnectionRequest_BackblazeB2", "digitalocean_spaces": "#/components/schemas/StorageDestinationConnectionRequestStorageDestinationConnectionRequest_DigitalOceanSpaces", "wasabi": "#/components/schemas/StorageDestinationConnectionRequestStorageDestinationConnectionRequest_Wasabi", "google_cloud_storage": "#/components/schemas/StorageDestinationConnectionRequestStorageDestinationConnectionRequest_GoogleCloudStorage", "other_s3_compatible": "#/components/schemas/StorageDestinationConnectionRequestStorageDestinationConnectionRequest_OtherS3Compatible" } } }, "StorageDestinationConnectionRequestStorageDestinationConnectionRequest_AwsS3": { "title": "AWS S3 Connection Request", "required": [ "region", "role_arn", "bucket" ], "properties": { "provider": { "enum": [ "aws_s3" ], "type": "string" }, "region": { "description": "AWS region containing the bucket, for example us-east-1.", "$ref": "#/components/schemas/AwsStorageRegion" }, "role_arn": { "maxLength": 2048, "type": "string", "description": "ARN of the IAM role HCTI assumes to access the bucket. Configure its trust policy for this organization before saving." }, "bucket": { "maxLength": 255, "type": "string", "description": "Name of the existing bucket or Space. HCTI does not create it." }, "key_prefix": { "maxLength": 1024, "type": [ "null", "string" ], "description": "Optional prefix for object keys within the bucket. Omitted or null uses the bucket root." } }, "description": "Connection settings for Amazon S3." }, "StorageDestinationConnectionRequestStorageDestinationConnectionRequest_BackblazeB2": { "title": "Backblaze B2 Connection Request", "required": [ "region", "access_key_id", "bucket" ], "properties": { "provider": { "enum": [ "backblaze_b2" ], "type": "string" }, "region": { "description": "Region code from the bucket's S3 endpoint, for example us-west-004.", "$ref": "#/components/schemas/BackblazeStorageRegion" }, "access_key_id": { "maxLength": 512, "type": "string", "description": "S3-compatible access key ID. For Google Cloud Storage, use an HMAC access ID beginning with GOOG." }, "secret_access_key": { "maxLength": 990, "type": [ "null", "string" ], "description": "Secret access key, required on create and when changing provider or access key ID. On update, omitted or null is allowed only with retain_secret_access_key: true and unchanged provider and access key ID. A supplied secret replaces it unless retain_secret_access_key is explicitly true. Up to 990 characters and 996 UTF-8 bytes." }, "retain_secret_access_key": { "type": [ "null", "boolean" ], "description": "Retain the existing secret access key. Only true retains the secret. Omitted, null, or false requires a supplied secret, including on updates. Explicit true requires existing credentials with unchanged provider and access key ID, and cannot be combined with a supplied secret. False requires a replacement secret, even when disabled." }, "bucket": { "maxLength": 255, "type": "string", "description": "Name of the existing bucket or Space. HCTI does not create it." }, "key_prefix": { "maxLength": 1024, "type": [ "null", "string" ], "description": "Optional prefix for object keys within the bucket. Omitted or null uses the bucket root." } }, "description": "Connection settings for Backblaze B2." }, "StorageDestinationConnectionRequestStorageDestinationConnectionRequest_CloudflareR2": { "title": "Cloudflare R2 Connection Request", "required": [ "cloudflare_account_id", "access_key_id", "bucket" ], "properties": { "provider": { "enum": [ "cloudflare_r2" ], "type": "string" }, "cloudflare_account_id": { "maxLength": 32, "type": "string", "description": "The 32-character hexadecimal Cloudflare account ID that owns the bucket." }, "cloudflare_jurisdiction": { "oneOf": [ { "type": "null" }, { "description": "Bucket jurisdiction: eu or fedramp. Omit or set to null for the default jurisdiction.", "$ref": "#/components/schemas/CloudflareStorageJurisdiction" } ] }, "access_key_id": { "maxLength": 512, "type": "string", "description": "S3-compatible access key ID. For Google Cloud Storage, use an HMAC access ID beginning with GOOG." }, "secret_access_key": { "maxLength": 990, "type": [ "null", "string" ], "description": "Secret access key, required on create and when changing provider or access key ID. On update, omitted or null is allowed only with retain_secret_access_key: true and unchanged provider and access key ID. A supplied secret replaces it unless retain_secret_access_key is explicitly true. Up to 990 characters and 996 UTF-8 bytes." }, "retain_secret_access_key": { "type": [ "null", "boolean" ], "description": "Retain the existing secret access key. Only true retains the secret. Omitted, null, or false requires a supplied secret, including on updates. Explicit true requires existing credentials with unchanged provider and access key ID, and cannot be combined with a supplied secret. False requires a replacement secret, even when disabled." }, "bucket": { "maxLength": 255, "type": "string", "description": "Name of the existing bucket or Space. HCTI does not create it." }, "key_prefix": { "maxLength": 1024, "type": [ "null", "string" ], "description": "Optional prefix for object keys within the bucket. Omitted or null uses the bucket root." } }, "description": "Connection settings for Cloudflare R2." }, "StorageDestinationConnectionRequestStorageDestinationConnectionRequest_DigitalOceanSpaces": { "title": "DigitalOcean Spaces Connection Request", "required": [ "region", "access_key_id", "bucket" ], "properties": { "provider": { "enum": [ "digitalocean_spaces" ], "type": "string" }, "region": { "description": "Region containing the Space, for example nyc3.", "$ref": "#/components/schemas/DigitalOceanStorageRegion" }, "access_key_id": { "maxLength": 512, "type": "string", "description": "S3-compatible access key ID. For Google Cloud Storage, use an HMAC access ID beginning with GOOG." }, "secret_access_key": { "maxLength": 990, "type": [ "null", "string" ], "description": "Secret access key, required on create and when changing provider or access key ID. On update, omitted or null is allowed only with retain_secret_access_key: true and unchanged provider and access key ID. A supplied secret replaces it unless retain_secret_access_key is explicitly true. Up to 990 characters and 996 UTF-8 bytes." }, "retain_secret_access_key": { "type": [ "null", "boolean" ], "description": "Retain the existing secret access key. Only true retains the secret. Omitted, null, or false requires a supplied secret, including on updates. Explicit true requires existing credentials with unchanged provider and access key ID, and cannot be combined with a supplied secret. False requires a replacement secret, even when disabled." }, "bucket": { "maxLength": 255, "type": "string", "description": "Name of the existing bucket or Space. HCTI does not create it." }, "key_prefix": { "maxLength": 1024, "type": [ "null", "string" ], "description": "Optional prefix for object keys within the bucket. Omitted or null uses the bucket root." } }, "description": "Connection settings for DigitalOcean Spaces." }, "StorageDestinationConnectionRequestStorageDestinationConnectionRequest_GoogleCloudStorage": { "title": "Google Cloud Storage Connection Request", "required": [ "access_key_id", "bucket" ], "properties": { "provider": { "enum": [ "google_cloud_storage" ], "type": "string" }, "access_key_id": { "maxLength": 512, "type": "string", "description": "S3-compatible access key ID. For Google Cloud Storage, use an HMAC access ID beginning with GOOG." }, "secret_access_key": { "maxLength": 990, "type": [ "null", "string" ], "description": "Secret access key, required on create and when changing provider or access key ID. On update, omitted or null is allowed only with retain_secret_access_key: true and unchanged provider and access key ID. A supplied secret replaces it unless retain_secret_access_key is explicitly true. Up to 990 characters and 996 UTF-8 bytes." }, "retain_secret_access_key": { "type": [ "null", "boolean" ], "description": "Retain the existing secret access key. Only true retains the secret. Omitted, null, or false requires a supplied secret, including on updates. Explicit true requires existing credentials with unchanged provider and access key ID, and cannot be combined with a supplied secret. False requires a replacement secret, even when disabled." }, "bucket": { "maxLength": 255, "type": "string", "description": "Name of the existing bucket or Space. HCTI does not create it." }, "key_prefix": { "maxLength": 1024, "type": [ "null", "string" ], "description": "Optional prefix for object keys within the bucket. Omitted or null uses the bucket root." } }, "description": "Connection settings for Google Cloud Storage." }, "StorageDestinationConnectionRequestStorageDestinationConnectionRequest_OtherS3Compatible": { "title": "Other S3-Compatible Connection Request", "required": [ "endpoint", "access_key_id", "bucket" ], "properties": { "provider": { "enum": [ "other_s3_compatible" ], "type": "string" }, "endpoint": { "maxLength": 512, "type": "string", "description": "Public HTTPS endpoint of the S3-compatible service. Do not include a path, query string, fragment, or credentials." }, "region": { "maxLength": 64, "type": [ "null", "string" ], "description": "Signing region expected by the service. Omit or set to null to use us-east-1." }, "force_path_style": { "type": [ "null", "boolean" ], "description": "Whether to put the bucket name in the URL path instead of the hostname. Omitted or null defaults to true." }, "access_key_id": { "maxLength": 512, "type": "string", "description": "S3-compatible access key ID. For Google Cloud Storage, use an HMAC access ID beginning with GOOG." }, "secret_access_key": { "maxLength": 990, "type": [ "null", "string" ], "description": "Secret access key, required on create and when changing provider or access key ID. On update, omitted or null is allowed only with retain_secret_access_key: true and unchanged provider and access key ID. A supplied secret replaces it unless retain_secret_access_key is explicitly true. Up to 990 characters and 996 UTF-8 bytes." }, "retain_secret_access_key": { "type": [ "null", "boolean" ], "description": "Retain the existing secret access key. Only true retains the secret. Omitted, null, or false requires a supplied secret, including on updates. Explicit true requires existing credentials with unchanged provider and access key ID, and cannot be combined with a supplied secret. False requires a replacement secret, even when disabled." }, "bucket": { "maxLength": 255, "type": "string", "description": "Name of the existing bucket or Space. HCTI does not create it." }, "key_prefix": { "maxLength": 1024, "type": [ "null", "string" ], "description": "Optional prefix for object keys within the bucket. Omitted or null uses the bucket root." } }, "description": "Connection settings for another S3-compatible provider." }, "StorageDestinationConnectionRequestStorageDestinationConnectionRequest_Wasabi": { "title": "Wasabi Connection Request", "required": [ "region", "access_key_id", "bucket" ], "properties": { "provider": { "enum": [ "wasabi" ], "type": "string" }, "region": { "description": "Region containing the bucket, for example us-east-1.", "$ref": "#/components/schemas/WasabiStorageRegion" }, "access_key_id": { "maxLength": 512, "type": "string", "description": "S3-compatible access key ID. For Google Cloud Storage, use an HMAC access ID beginning with GOOG." }, "secret_access_key": { "maxLength": 990, "type": [ "null", "string" ], "description": "Secret access key, required on create and when changing provider or access key ID. On update, omitted or null is allowed only with retain_secret_access_key: true and unchanged provider and access key ID. A supplied secret replaces it unless retain_secret_access_key is explicitly true. Up to 990 characters and 996 UTF-8 bytes." }, "retain_secret_access_key": { "type": [ "null", "boolean" ], "description": "Retain the existing secret access key. Only true retains the secret. Omitted, null, or false requires a supplied secret, including on updates. Explicit true requires existing credentials with unchanged provider and access key ID, and cannot be combined with a supplied secret. False requires a replacement secret, even when disabled." }, "bucket": { "maxLength": 255, "type": "string", "description": "Name of the existing bucket or Space. HCTI does not create it." }, "key_prefix": { "maxLength": 1024, "type": [ "null", "string" ], "description": "Optional prefix for object keys within the bucket. Omitted or null uses the bucket root." } }, "description": "Connection settings for Wasabi." }, "StoreImageObjectResult": { "required": [ "status", "target" ], "type": "object", "properties": { "status": { "$ref": "#/components/schemas/StoreImageStatus" }, "target": { "$ref": "#/components/schemas/StoreImageTarget" }, "bucket": { "type": [ "null", "string" ] }, "key": { "type": [ "null", "string" ] } } }, "StoreImageOutcome": { "enum": [ "complete", "partial", "failed" ] }, "StoreImageResult": { "required": [ "outcome", "baseResult", "message", "statusCode" ], "type": "object", "properties": { "outcome": { "$ref": "#/components/schemas/StoreImageOutcome" }, "baseResult": { "description": "Describes whether the base image was stored and where it was stored.", "$ref": "#/components/schemas/StoreImageObjectResult" }, "transformationResult": { "oneOf": [ { "type": "null" }, { "description": "Describes whether the transformed image was stored and where it was stored. Null when no transformation was requested.", "$ref": "#/components/schemas/StoreImageObjectResult" } ] }, "error": { "type": [ "null", "string" ] }, "referenceId": { "type": [ "null", "string" ] }, "success": { "type": "boolean" }, "message": { "type": "string" }, "statusCode": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } }, "StoreImageStatus": { "enum": [ "stored", "already_stored", "failed", "not_attempted" ] }, "StoreImageTarget": { "enum": [ "hcti_storage", "storage_destination" ] }, "TemplateCreateResponse": { "type": "object", "properties": { "template_id": { "type": "string" }, "template_version": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" } } }, "TemplateRequest": { "title": "Template Request", "required": [ "html" ], "type": "object", "properties": { "html": { "type": "string", "description": "HTML to render for the template. Use Handlebars placeholders for values that will be substituted when an image is rendered. Must be non-empty, contain at least one Handlebars placeholder, and compile as valid Handlebars." }, "name": { "maxLength": 64, "type": [ "null", "string" ], "description": "The name of the template, used to identify it in your account. Maximum: 64 characters." }, "description": { "maxLength": 1024, "type": [ "null", "string" ], "description": "An optional description of the template for your reference. Maximum: 1024 characters." }, "css": { "type": [ "null", "string" ], "description": "CSS used to style images rendered from the template. Handlebars expressions are not supported in CSS; put dynamic CSS in the HTML instead." }, "device_scale": { "maximum": 3, "minimum": 0.1, "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "description": "Adjusts the pixel ratio used for the screenshot. Minimum: 0.1. Maximum: 3. HTML and template renders default to 2; URL renders default to 1.", "format": "double" }, "google_fonts": { "type": [ "null", "string" ], "description": "Google fonts to load. Separate multiple fonts with a pipe, such as 'Roboto|OpenSans', and set font-family in the CSS to use them." }, "max_wait_ms": { "maximum": 10000, "minimum": 500, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Sets a limit on how long to wait before taking the screenshot when the page continues loading irrelevant content. Minimum: 500. Maximum: 10000 and subject to the account plan limit.", "format": "int32" }, "ms_delay": { "maximum": 10000, "minimum": 0, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Adds extra time in milliseconds before taking the screenshot so JavaScript can execute. Minimum: 0. Maximum: 10000.", "format": "int32", "default": 0 }, "render_when_ready": { "type": [ "null", "boolean" ], "description": "Waits until the page signals that the screenshot is ready. The image fails if the readiness signal is never sent." }, "selector": { "type": [ "null", "string" ], "description": "A CSS selector for an element in the HTML. We’ll crop the image to this specific element." }, "viewport_height": { "maximum": 6000, "minimum": 1, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Sets the height of Chrome's viewport and disables automatic cropping. Minimum: 1. Maximum: 6000. Both viewport dimensions must be supplied together.", "format": "int32" }, "viewport_width": { "maximum": 6000, "minimum": 1, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Sets the width of Chrome's viewport and disables automatic cropping. Minimum: 1. Maximum: 6000. Both viewport dimensions must be supplied together.", "format": "int32" }, "disable_twemoji": { "type": [ "null", "boolean" ], "description": "Twemoji is enabled by default for images rendered from the template. Set true to disable automatic emoji replacement. Omitted, null, or false keeps Twemoji enabled." }, "color_scheme": { "oneOf": [ { "type": "null" }, { "description": "Sets Chrome's preferred color scheme. Valid values: light or dark.", "$ref": "#/components/schemas/ColorSchemeType" } ] }, "timezone": { "type": [ "null", "string" ], "description": "Sets the IANA timezone used by Chrome while rendering. Must be a recognized IANA timezone identifier." }, "viewport_mobile": { "type": [ "null", "boolean" ], "description": "Specifies whether the page uses mobile viewport behavior, including its viewport meta tag." }, "viewport_landscape": { "type": [ "null", "boolean" ], "description": "Specifies whether the emulated viewport is in landscape orientation." }, "viewport_touch": { "type": [ "null", "boolean" ], "description": "Specifies whether the emulated viewport supports touch events." }, "media_type": { "oneOf": [ { "type": "null" }, { "description": "Sets the CSS media type used while rendering the page. Valid values: print or screen.", "$ref": "#/components/schemas/MediaType" } ] }, "proxy_id": { "type": [ "null", "string" ], "description": "Specifies which configured organization proxy to use when rendering." }, "storage_destination_id": { "type": [ "null", "string" ], "description": "Specifies which configured organization storage destination receives the rendered image." }, "jumbo_max_height": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Maximum height of the rendered image in jumbo mode. Jumbo rendering consumes additional renders and requires jumbo_max_width. Supply both jumbo dimensions. Each must be greater than 0 and no more than 80000; at least one must exceed 8000; total area cannot exceed 400000000 pixels.", "format": "int32" }, "jumbo_max_width": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Maximum width of the rendered image in jumbo mode. Jumbo rendering consumes additional renders and requires jumbo_max_height. Supply both jumbo dimensions. Each must be greater than 0 and no more than 80000; at least one must exceed 8000; total area cannot exceed 400000000 pixels.", "format": "int32" }, "transparent_background": { "type": [ "null", "boolean" ], "description": "Specifies whether the image is rendered with a transparent background." }, "request_overrides": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/RequestOverride" }, "description": "Rules that override browser network requests. The block action blocks requests matching a URL wildcard pattern and/or resource types. When both matchers are supplied, both must match. A request is blocked if any block rule matches. Omitted, null, or an empty array adds no overrides. Requires a paid plan. Accepts a JSON array in JSON requests or a JSON-encoded array string in form requests. Maximum 100 rules and 512 characters per URL pattern. Each block rule requires a nonempty URL pattern or at least one resource type; supplied matchers cannot be empty." } } }, "TemplateValueKind": { "enum": [ "UNKNOWN", "String", "Boolean", "Integer", "Float", "Color", "Size", "Object", "Collection" ] }, "TemplateVariable": { "type": "object", "properties": { "mode": { "description": "Whether the template variable is required, ignored, or has a fallback value.", "$ref": "#/components/schemas/TemplateVariableMode" }, "key": { "type": "string", "description": "Variable name or path used in template_values, without Handlebars braces. Preserve its casing and nesting when supplying values." }, "fallback_value": { "oneOf": [ { "type": "null" }, { "description": "Saved fallback JSON value used when the variable is missing and its mode selects fallback behavior. Preserve its JSON value type when supplying an override.", "$ref": "#/components/schemas/JsonNode" } ] }, "kind_hint": { "description": "Inferred value kind, such as string, boolean, integer, color, object, or collection. Use it to choose an appropriate JSON value; an unknown kind provides no type guidance.", "$ref": "#/components/schemas/TemplateValueKind" }, "helper_kind": { "description": "Handlebars helper context used during value validation, such as if, unless, with, or each. Interpret this together with mode and kind_hint when preparing template_values.", "$ref": "#/components/schemas/HandlebarsHelperKind" } }, "description": "A variable discovered in a block template, with its key, requirement mode, inferred value kind, and any fallback or helper context." }, "TemplateVariableMode": { "enum": [ "Required", "Ignore", "Fallback" ], "description": "How a block-template variable is handled when rendering." }, "UsageDataReturn": { "type": "object", "properties": { "data": { "description": "Recent image counts grouped by hour, day, and month. These are different views of the same usage and should not be added together.", "$ref": "#/components/schemas/UsageTimeSeries" }, "per_billing_period": { "type": "array", "items": { "$ref": "#/components/schemas/PerBillingPeriodCounter" }, "description": "Image totals for available billing periods, ordered by period start from oldest to newest. Billing periods follow the organization's billing schedule rather than calendar months." } }, "description": "Image usage for the authenticated organization, grouped by calendar intervals and billing periods." }, "UsageTimeSeries": { "type": "object", "properties": { "hour": { "type": "object", "additionalProperties": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "description": "Hourly image counts, with up to 72 recent entries. Keys are ISO 8601 timestamps identifying the start of each hour; values are image counts for that hour." }, "day": { "type": "object", "additionalProperties": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "description": "Daily image counts, with up to 60 recent entries. Keys are ISO 8601 timestamps identifying the start of each calendar day; values are image counts for that day." }, "month": { "type": "object", "additionalProperties": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "description": "Monthly image counts, with up to 12 recent entries. Keys are ISO 8601 timestamps identifying the start of each calendar month; values are image counts for that month. Calendar months are separate from billing periods." } }, "description": "Image counts grouped by hour, calendar day, and calendar month. Each object maps an interval's start timestamp to its image count. Intervals without recorded data may be omitted." }, "ValidationError": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "WasabiStorageRegion": { "enum": [ "us-east-1", "us-east-2", "us-central-1", "us-west-1", "us-west-2", "ca-central-1", "eu-central-1", "eu-central-2", "eu-west-1", "eu-west-2", "eu-west-3", "eu-south-1", "ap-northeast-1", "ap-northeast-2", "ap-southeast-1", "ap-southeast-2" ] } }, "securitySchemes": { "basic": { "type": "http", "description": "Basic auth using API ID as username and API Key as password. Example: `Authorization: Basic {base64(api-id:api-key)}`", "scheme": "basic" } } }, "security": [ { "basic": [ ] } ], "tags": [ { "name": "Images" }, { "name": "Templates" }, { "name": "Proxies" }, { "name": "OG Configs" }, { "name": "Storage Destinations" }, { "name": "API Keys" }, { "name": "Usage" } ] }