# OG configurations API

Manage configurations that generate [automatic Open Graph images](/getting-started/og-images/) for your site’s pages.

## Operations

Reads share **100 requests/minute**, and writes share **20 requests/minute**, per organization across REST and MCP. See [authentication](/getting-started/using-the-api/api-keys/), [rate limits](/getting-started/using-the-api/rate-limits/), and the [interactive API reference](https://htmlcsstoimage.com/api-docs).

### Create a new OG configuration

`POST https://hcti.io/v1/og-configs`

Permission required: [`og_configs:create_update`](/getting-started/using-the-api/permissions/#permission-og-configs-create-update)

MCP tool: [`create_og_config`](/integrations/mcp/tools/#og-configurations)

### List OG configurations

`GET https://hcti.io/v1/og-configs`

Permission required: [`og_configs:read`](/getting-started/using-the-api/permissions/#permission-og-configs-read)

MCP tool: [`list_og_configs`](/integrations/mcp/tools/#og-configurations)

### Retrieve an OG configuration

`GET https://hcti.io/v1/og-configs/{id}`

Permission required: [`og_configs:read`](/getting-started/using-the-api/permissions/#permission-og-configs-read)

MCP tool: [`get_og_config`](/integrations/mcp/tools/#og-configurations)

### Update an OG configuration

`POST https://hcti.io/v1/og-configs/{id}`

Permission required: [`og_configs:create_update`](/getting-started/using-the-api/permissions/#permission-og-configs-create-update)

MCP tool: [`update_og_config`](/integrations/mcp/tools/#og-configurations)

### Delete an OG configuration

`DELETE https://hcti.io/v1/og-configs/{id}`

Permission required: [`og_configs:delete`](/getting-started/using-the-api/permissions/#permission-og-configs-delete)

MCP tool: [`delete_og_config`](/integrations/mcp/tools/#og-configurations)

## Create a screenshot configuration

Set `config_type` to `html_css` to render page HTML/CSS using default image options and, optionally, options extracted from page metadata.

```bash
curl 'https://hcti.io/v1/og-configs' \
  --user "$HCTI_API_ID:$HCTI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "config_type": "html_css",
    "name": "Website screenshots",
    "base_url": "https://example.com",
    "disabled": false,
    "optimization_mode": "post_process",
    "extract_values": false,
    "default_options": {
      "viewport_width": 1200,
      "viewport_height": 630,
      "device_scale": 1
    }
  }'
```

### Shared fields

| Field | Description |
| --- | --- |
| `config_type` | Required: `html_css` or `templated`. Determines the request’s remaining fields. |
| `name` | Required, up to 255 characters. |
| `base_url` | Required HTTPS origin, such as `https://example.com`. No path, query, fragment, or credentials. |
| `description` | Optional, up to 1,023 characters. |
| `disabled` | Defaults to `false`; response uses `enabled`. |
| `refresh_interval_s` | Seconds before cached images become eligible for refresh. Minimum depends on the plan; maximum one year. Defaults to 86,400 seconds (24 hours). See [refresh behavior](/guides/debugging/og-image-caching/) and [plan options](https://htmlcsstoimage.com/pricing). |
| `optimization_mode` | `no_optimization` retains dimensions; `post_process` (default) adapts one render to social sizes; `set_viewport` renders for crawler-specific viewport sizes and consumes multiple renders. |

### HTML/CSS fields

Set image rendering defaults in `default_options` using the supported parameters below.

`extract_values` defaults to `false`. When true, extracted page metadata overrides configured default image options. See [OG parameter support](/getting-started/og-images/supported-parameters/).

| Name | Type | Description |
| --- | --- | --- |
| [`css`](/parameters/) | `String` | CSS used to style the rendered image or modify a captured page. |
| [`additional_header_origins`](/parameters/headers/#additional-header-origins) | `Array` | Allow custom `headers` on requests to specific additional HTTP or HTTPS origins. |
| [`block_consent_banners`](/guides/advanced/blocking-cookie-banners/) | `Boolean` | When set to `true`, automatically blocks cookie consent banners and popups on websites. Most useful for URL screenshots. |
| [`color_scheme`](/parameters/color_scheme/) | `String` | Set Chrome to render in `light` or `dark` mode. Affects websites using `prefers-color-scheme`. |
| [`device_scale`](/parameters/device_scale/) | `Double` | Control resolution by adjusting the pixel ratio from `0.1` to `3`. Higher values increase image quality and file size. |
| [`disable_twemoji`](/guides/debugging/emoji/#disabling-twemoji) | `Boolean` | Set to `true` to use native emoji fonts instead of Twemoji. |
| [`headers`](/parameters/headers/) | `Object` | Add custom HTTP headers when screenshotting a URL. Headers are restricted to the requested URL's origin and any `additional_header_origins`. |
| [`identify_as_hcti`](/parameters/identify_as_hcti/) | `Boolean` | Add `X-HCTI-SCREENSHOT: 1` to the top-level request when screenshotting a URL. |
| [`include_headers_on_subrequests`](/parameters/headers/#include-headers-on-subrequests) | `Boolean` | Also add custom `headers` to same-origin subrequests and subrequests matching `additional_header_origins`. |
| [`max_wait_ms`](/parameters/max_wait_ms/) | `Integer` | Set a maximum time limit from `500` to `10000` milliseconds for waiting before taking the screenshot. |
| [`media_type`](/parameters/media_type/) | `String` | Set Chrome to render using `screen` or `print` CSS media styles. |
| [`ms_delay`](/parameters/ms_delay/) | `Integer` | Delay before generating the image. Useful when waiting for JavaScript; start with `500` milliseconds. |
| [`proxy_id`](/parameters/proxy_id/) | `String` | Route outbound traffic through one of your organization's configured HTTP proxies. Available on the 10,000 images/month plan or higher. |
| [`render_when_ready`](/parameters/render_when_ready/) | `Boolean` | Wait to generate the image until JavaScript calls `ScreenshotReady()`. |
| [`selector`](/parameters/selector/) | `String` | Crop the image to an element matching this CSS selector, such as `section#complete-toolkit.container-lg`. |
| [`storage_destination_id`](/parameters/storage_destination_id/) | `String` | Save rendered files to one of your organization's configured storage destinations. Available on the 10,000 images/month plan or higher. |
| [`timezone`](/parameters/timezone/) | `String` | Set Chrome's timezone with an IANA identifier such as `America/New_York`. |
| [`transparent_background`](/parameters/transparent_background/) | `Boolean` | Set to `true` to render with a transparent background. |
| [`viewport_height`](/parameters/viewport/#viewport-width-and-height) | `Integer` | Set the height of Chrome's viewport. Both dimensions must be set when using either. |
| [`viewport_landscape`](/parameters/viewport/#viewport-landscape) | `Boolean` | Set Chrome's viewport to landscape mode. |
| [`viewport_mobile`](/parameters/viewport/#viewport-mobile) | `Boolean` | Set Chrome's viewport to emulate a mobile device. |
| [`viewport_touch`](/parameters/viewport/#viewport-touch) | `Boolean` | Set Chrome's viewport to support touch events. |
| [`viewport_width`](/parameters/viewport/#viewport-width-and-height) | `Integer` | Set the width of Chrome's viewport. Both dimensions must be set when using either. |

## Create a templated configuration

For `config_type: "templated"`, supply `template_id`. The referenced template must belong to your organization. To submit this example, save it as `og-config.json`, replace the template ID, and send it using `--data @og-config.json` with the same endpoint and authentication above.

This example includes optional headers for fetching the source page. Omit `headers` and `additional_header_origins` if you don’t need them.

```json
{
  "config_type": "templated",
  "name": "Blog social cards",
  "base_url": "https://example.com",
  "template_id": "your-template-id",
  "headers": {
    "X-Site-Token": "your-site-token"
  },
  "additional_header_origins": ["https://www.example.com"],
  "template_values_mapping": [
    { "template_key": "headline", "fallback": "titles" },
    { "template_key": "summary", "fallback": "descriptions" }
  ]
}
```

Use the [Template Editor](/template-editor/) to design the card and define the template keys, or [create a template through the API](/getting-started/templates/#creating-a-template). Use those keys in `template_values_mapping`. `template_version` is optional; omitted/null uses the latest version. Each of up to 32 mappings supplies a `template_key` and exactly one of:

*   `meta_key`: a page metadata key to extract.
*   `fallback`: `titles` or `descriptions`, using HCTI’s title or description fallbacks.

The optional fetching settings shown above apply when extracting template values from the source page:

*   [`headers`](/parameters/headers/) supplies custom HTTP headers for the source origin.
*   [`additional_header_origins`](/parameters/headers/#additional-header-origins) allows those headers to be sent to other specified origins, such as `https://www.example.com` after a redirect.

## Read the response and use the configuration

Create, get, and update return `200 OK` with the configuration fields, timestamps, and:

| Field | Use |
| --- | --- |
| `id` | Management API/MCP identifier for reading, updating, or deleting the configuration. |
| `domain_id` | Identifier used in the public OG image URL. |
| `enabled` | Whether the configuration can serve OG images. |

Use `domain_id` to [add the OG image URL to your pages](/getting-started/og-images/#5-add-the-generated-domain-id-to-your-pages). Creating a configuration does not itself render every page. The public OG image URL needs no API key or HMAC signature.

## List, update, and delete

*   **List configurations:** `GET /v1/og-configs` returns configurations newest first, including disabled configurations.
*   **Paginate:** Use `count` (1–100, default 10) and pass `pagination.next_page_start` as the next request’s `page_start`. Stop when the cursor is `null`. See [pagination](/management-api/#resource-ids-and-pagination).
*   **Retrieve one configuration:** Use `GET /v1/og-configs/{id}`.

`POST /v1/og-configs/{id}` replaces the configuration. Send `config_type`, required fields, and every optional setting you want to keep; omitted settings clear or reset. To disable it temporarily, send the complete configuration with `disabled: true`.

`DELETE /v1/og-configs/{id}` returns `204 No Content` on success. Removing or disabling a configuration affects its ability to serve OG images; remove or replace the corresponding metadata on your site as appropriate.

Invalid settings return `400`; inaccessible references can return `404`; conflicting configurations can return `409`. Plan and permission errors return `403`. Check the response message before retrying.

## MCP

Create accepts the same request under `content`; update takes `id` and `content`. Get/delete take `id`, and list accepts `count` and `page_start`. See [MCP tools](/integrations/mcp/tools/#og-configurations).

For example: **“Use HCTI to list my OG configurations, inspect the blog configuration, and explain its refresh interval and template mappings.”** This needs `og_configs:read`. Creating or changing a configuration also needs `og_configs:create_update` approved through [OAuth](/integrations/mcp/permissions/).

## Need help?

Talk to a human. Email [support@htmlcsstoimage.com](mailto:support@htmlcsstoimage.com) and we’ll help you get started.