OG configurations API

Manage configurations that generate automatic Open Graph images for your site’s pages.

Manage this resource alongside your application with Terraform or Pulumi. See infrastructure as code for application setups, credentials, and lifecycle behavior.

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.

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
    }
  }'

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.

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.

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

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.