---
layout: page
title: OG configurations API
permalink: /management-api/og-configs/
parent: Management API
nav_order: 5
description: >-
  Create and manage Open Graph image configurations with the HTML/CSS to Image API or MCP. Configure screenshots, templates, metadata extraction, and refreshes.
---
# OG configurations API
{: .no_toc }

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).

{% include operation-cards.html resource="og-configs" %}

## 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/).

{% include additional_parameters.md context="og_config_management" include_primary=true %}

## 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/).

{% include code_footer.md version=1 %}