--- title: "Create an OG configuration" method: POST path: "/v1/og-configs" tags: ["OG Configs"] --- # Create an OG configuration `POST /v1/og-configs` ## Request - Base URL: `https://hcti.io` - URL: `https://hcti.io/v1/og-configs` - Auth: HTTP basic **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. ## Request body - union: Settings for creating or updating an Open Graph image configuration. - object: Settings for an Open Graph configuration that renders page HTML/CSS. - `config_type` 'html_css', required - `default_options` OgDefaultImageOptions - `css` string, nullable: CSS injected into the loaded page to override its styles. - `device_scale` union: 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. - number, double - string, double - `max_wait_ms` union: 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. - integer - string, int32 - `ms_delay` union: Adds extra time in milliseconds before taking the screenshot so JavaScript can execute. Minimum: 0. Maximum: 10000. - integer - string, int32 - `render_when_ready` boolean, nullable: Waits until the page signals that the screenshot is ready. The image fails if the readiness signal is never sent. - `selector` string, nullable: A CSS selector for an element in the HTML. We’ll crop the image to this specific element. - `viewport_height` union: Sets the height of Chrome's viewport and disables automatic cropping. Minimum: 1. Maximum: 6000. Both viewport dimensions must be supplied together. - integer - string, int32 - `viewport_width` union: Sets the width of Chrome's viewport and disables automatic cropping. Minimum: 1. Maximum: 6000. Both viewport dimensions must be supplied together. - integer - string, int32 - `disable_twemoji` boolean, nullable: 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` unknown - `timezone` string, nullable: Sets the IANA timezone used by Chrome while rendering. Must be a recognized IANA timezone identifier. - `block_consent_banners` boolean, nullable: Attempt to block cookie/consent banners from displaying. - `identify_as_hcti` boolean, nullable: Identify the top-level page navigation as an HCTI screenshot request using the X-HCTI-SCREENSHOT header. - `headers` object, nullable: 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` string[], nullable: 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` boolean, nullable: 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` boolean, nullable: Specifies whether the page uses mobile viewport behavior, including its viewport meta tag. - `viewport_landscape` boolean, nullable: Specifies whether the emulated viewport is in landscape orientation. - `viewport_touch` boolean, nullable: Specifies whether the emulated viewport supports touch events. - `media_type` unknown - `proxy_id` string, nullable - `storage_destination_id` string, nullable - `transparent_background` boolean, nullable: Specifies whether the image is rendered with a transparent background. - `request_overrides` RequestOverride[], nullable: 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. - `action` 'block', required - `url` string, nullable: URL wildcard pattern to match, using * for any sequence of characters. When resource_types is also supplied, both matchers must match. - `resource_types` RequestOverrideResourceType[], nullable: 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. - `extract_values` boolean: Whether to extract image options from page metadata. When disabled, only the configured defaults are used. - `name` string, required: Display name for the configuration, up to 255 characters. - `description` string, nullable: Optional description of the configuration, up to 1023 characters. - `base_url` string, required: HTTPS origin of the source website, such as https://example.com. Do not include a path, query string, fragment, or credentials. - `optimization_mode` 'no_optimization' | 'post_process' | 'set_viewport': How images are sized for different social platforms. - `disabled` boolean: Whether this configuration is disabled from serving Open Graph images. Defaults to false. - `refresh_interval_s` union: Interval in seconds before cached images are eligible for refresh. The minimum depends on your plan; the maximum is one year. - integer - string, uint32 - object: Settings for an Open Graph configuration that renders a template using values extracted from page metadata. - `config_type` 'templated', required - `template_id` string, required: ID of the template used to render images. - `template_version` union: Template version to use. Omit or set to null to use the latest version. - integer - string, int64 - `template_values_mapping` OgTemplateValueMapping[], nullable: Up to 32 mappings from page metadata to template fields. Each mapping supplies either a meta_key or a fallback. - `template_key` string, required: Template field path to populate, up to 128 characters. - `meta_key` string, nullable: Meta tag name or property, such as og:title or twitter:description. Supply this or fallback, not both. - `fallback` unknown - `headers` object, nullable: 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` string[], nullable: 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` string, required: Display name for the configuration, up to 255 characters. - `description` string, nullable: Optional description of the configuration, up to 1023 characters. - `base_url` string, required: HTTPS origin of the source website, such as https://example.com. Do not include a path, query string, fragment, or credentials. - `optimization_mode` 'no_optimization' | 'post_process' | 'set_viewport': How images are sized for different social platforms. - `disabled` boolean: Whether this configuration is disabled from serving Open Graph images. Defaults to false. - `refresh_interval_s` union: Interval in seconds before cached images are eligible for refresh. The minimum depends on your plan; the maximum is one year. - integer - string, uint32 ## Response `200` OK - union: An Open Graph image configuration. - object: An Open Graph configuration that renders page HTML/CSS. - `config_type` 'html_css', required - `default_options` OgDefaultImageOptions - `css` string, nullable: CSS injected into the loaded page to override its styles. - `device_scale` union: 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. - number, double - string, double - `max_wait_ms` union: 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. - integer - string, int32 - `ms_delay` union: Adds extra time in milliseconds before taking the screenshot so JavaScript can execute. Minimum: 0. Maximum: 10000. - integer - string, int32 - `render_when_ready` boolean, nullable: Waits until the page signals that the screenshot is ready. The image fails if the readiness signal is never sent. - `selector` string, nullable: A CSS selector for an element in the HTML. We’ll crop the image to this specific element. - `viewport_height` union: Sets the height of Chrome's viewport and disables automatic cropping. Minimum: 1. Maximum: 6000. Both viewport dimensions must be supplied together. - integer - string, int32 - `viewport_width` union: Sets the width of Chrome's viewport and disables automatic cropping. Minimum: 1. Maximum: 6000. Both viewport dimensions must be supplied together. - integer - string, int32 - `disable_twemoji` boolean, nullable: 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` unknown - `timezone` string, nullable: Sets the IANA timezone used by Chrome while rendering. Must be a recognized IANA timezone identifier. - `block_consent_banners` boolean, nullable: Attempt to block cookie/consent banners from displaying. - `identify_as_hcti` boolean, nullable: Identify the top-level page navigation as an HCTI screenshot request using the X-HCTI-SCREENSHOT header. - `headers` object, nullable: 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` string[], nullable: 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` boolean, nullable: 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` boolean, nullable: Specifies whether the page uses mobile viewport behavior, including its viewport meta tag. - `viewport_landscape` boolean, nullable: Specifies whether the emulated viewport is in landscape orientation. - `viewport_touch` boolean, nullable: Specifies whether the emulated viewport supports touch events. - `media_type` unknown - `proxy_id` string, nullable - `storage_destination_id` string, nullable - `transparent_background` boolean, nullable: Specifies whether the image is rendered with a transparent background. - `request_overrides` RequestOverride[], nullable: 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. - `action` 'block', required - `url` string, nullable: URL wildcard pattern to match, using * for any sequence of characters. When resource_types is also supplied, both matchers must match. - `resource_types` RequestOverrideResourceType[], nullable: 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. - `extract_values` boolean: Whether image options are extracted from page metadata. When disabled, only the configured defaults are used. - `id` string, required - `domain_id` string, required: Domain identifier used in this configuration's Open Graph image URLs. - `name` string, nullable - `description` string, nullable - `base_url` string, required - `optimization_mode` 'no_optimization' | 'post_process' | 'set_viewport': How images are sized for different social platforms. - `enabled` boolean: Whether the configuration is enabled to serve Open Graph images. - `refresh_interval_s` union - integer - string, uint32 - `created_at` string, date-time - `updated_at` string, date-time - object: An Open Graph configuration that renders a template using extracted page metadata. - `config_type` 'templated', required - `template_id` string, required: ID of the template used to render images. - `template_version` union: Template version used to render images. Null means the latest version is used. - integer - string, int64 - `template_values_mapping` OgTemplateValueMapping[], nullable: Mappings from page metadata to template fields. Each mapping uses either a meta_key or a fallback. - `template_key` string, required: Template field path to populate, up to 128 characters. - `meta_key` string, nullable: Meta tag name or property, such as og:title or twitter:description. Supply this or fallback, not both. - `fallback` unknown - `headers` object, nullable: Custom HTTP headers sent on top-level page navigations to the source website's origin and any additional_header_origins. - `additional_header_origins` string[], nullable: Additional exact HTTP or HTTPS origins allowed to receive custom headers, in the format scheme://host[:port] without a path. - `id` string, required - `domain_id` string, required: Domain identifier used in this configuration's Open Graph image URLs. - `name` string, nullable - `description` string, nullable - `base_url` string, required - `optimization_mode` 'no_optimization' | 'post_process' | 'set_viewport': How images are sized for different social platforms. - `enabled` boolean: Whether the configuration is enabled to serve Open Graph images. - `refresh_interval_s` union - integer - string, uint32 - `created_at` string, date-time - `updated_at` string, date-time ## Other responses - `400`: Bad Request - `401`: Unauthorized - `403`: Forbidden - `404`: Not Found - `409`: Conflict - `429`: Too Many Requests ## Changes - **2026-09-30** `398cec19904b`: 2 info - added the new optional request property `anyOf[subschema #1: HTML/CSS OG Config Request]/default_options/oneOf[#/components/schemas/OgDefaultImageOptions]/request_overrides` - added the optional property `anyOf[subschema #1: HTML/CSS OG Config]/default_options/oneOf[#/components/schemas/OgDefaultImageOptions]/request_overrides` to the response with the `200` status - **2026-09-14** `d5730c2a58f6`: 1 info - endpoint added [Operation history](https://skmtc.dev/htmlcsstoimage/apis/html-css-to-image-api/changes/v1/og-configs/post.md) --- [API](https://skmtc.dev/htmlcsstoimage/apis/html-css-to-image-api.md) - [All operations](https://skmtc.dev/htmlcsstoimage/apis/html-css-to-image-api/llms.txt) - [OpenAPI document](https://skmtc.dev/htmlcsstoimage/apis/html-css-to-image-api/revisions/100550373ae1?raw)