OG configurations API

Manage configurations that generate automatic Open Graph 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, rate limits, and the interactive API reference.

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.

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

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.

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.

{
  "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 to design the card and define the template keys, or create a template through the API. 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 supplies custom HTTP headers for the source origin.
• 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:

Use domain_id to add the OG image URL 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.
• 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.

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.

Need help?

Talk to a human. Please email us support@htmlcsstoimage.com with any questions and we’ll gladly help you get started.