HTML/CSS to Image API

List OG Configurations

list_og_configs

Read-onlyIdempotent

Lists the organization's Open Graph configurations in descending creation order, including disabled configurations. Results are in item.data. Pass item.pagination.next_page_start as page_start to continue; a null cursor marks the last page.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`count`	No	Maximum number of configurations to return, from 1 to 100. Defaults to 10.
`page_start`	No	Opaque cursor from item.pagination.next_page_start in the previous response. Pass it unchanged; omit for the first page.

Output Schema

TableJSON Schema

Name	Required	Description
`item`	No	Operation result. Check success before using this value.
`error`	No	Error details when the operation failed; null on success.
`success`	No	Whether the operation succeeded. If false, inspect error before retrying.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 22, 2026

changedOutput schema / properties / item / properties / data / items / anyOf

Previous value: -[
-  {
-    "description": "An Open Graph configuration that renders page HTML/CSS.",
-    "properties": {
-      "base_url": {
-        "type": "string"
-      },
-      "config_type": {
-        "const": "html_css"
-      },
-      "created_at": {
-        "format": "date-time",
-        "type": "string"
-      },
-      "default_options": {
-        "description": "Default image rendering options for pages served by this configuration. Extracted image options override these defaults.",
-        "properties": {
-          "additional_header_origins": {
-            "description": "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.",
-            "items": {
-              "type": "string"
-            },
-            "type": [
-              "array",
-              "null"
-            ]
-          },
-          "block_consent_banners": {
-            "description": "Attempt to block cookie/consent banners from displaying.",
-            "type": [
-              "boolean",
-              "null"
-            ]
-          },
-          "color_scheme": {
-            "description": "Sets Chrome's preferred color scheme. Valid values: light or dark.",
-            "enum": [
-              "light",
-              "dark",
-              null
-            ],
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "css": {
-            "description": "CSS injected into the loaded page to override its styles.",
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "device_scale": {
-            "description": "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.",
-            "maximum": 3,
-            "minimum": 0.1,
-            "type": [
-              "number",
-              "null"
-            ]
-          },
-          "disable_twemoji": {
-            "description": "Disables the Twemoji fallback and renders emoji using native fonts instead.",
-            "type": [
-              "boolean",
-              "null"
-            ]
-          },
-          "headers": {
-            "additionalProperties": {
-              "type": "string"
-            },
-            "description": "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`.",
-            "type": [
-              "object",
-              "null"
-            ]
-          },
-          "identify_as_hcti": {
-            "description": "Identify the top-level page navigation as an HCTI screenshot request using the X-HCTI-SCREENSHOT header.",
-            "type": [
-              "boolean",
-              "null"
-            ]
-          },
-          "include_headers_on_subrequests": {
-            "description": "Include custom headers on subrequests to the requested URL's origin and any additional_header_origins. Defaults to false. Requires at least one header.",
-            "type": [
-              "boolean",
-              "null"
-            ]
-          },
-          "max_wait_ms": {
-            "description": "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.",
-            "maximum": 10000,
-            "minimum": 500,
-            "type": [
-              "integer",
-              "null"
-            ]
-          },
-          "media_type": {
-            "description": "Sets the CSS media type used while rendering the page. Valid values: print or screen.",
-            "enum": [
-              "print",
-              "screen",
-              null
-            ],
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "ms_delay": {
-            "description": "Adds extra time in milliseconds before taking the screenshot so JavaScript can execute. Minimum: 0. Maximum: 10000.",
-            "maximum": 10000,
-            "minimum": 0,
-            "type": [
-              "integer",
-              "null"
-            ]
-          },
-          "proxy_id": {
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "render_when_ready": {
-            "description": "Waits until the page signals that the screenshot is ready. The image fails if the readiness signal is never sent.",
-            "type": [
-              "boolean",
-              "null"
-            ]
-          },
-          "selector": {
-            "description": "A CSS selector for an element in the HTML. We’ll crop the image to this specific element.",
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "storage_destination_id": {
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "timezone": {
-            "description": "Sets the IANA timezone used by Chrome while rendering. Must be a recognized IANA timezone identifier.",
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "transparent_background": {
-            "description": "Specifies whether the image is rendered with a transparent background.",
-            "type": [
-              "boolean",
-              "null"
-            ]
-          },
-          "viewport_height": {
-            "description": "Sets the height of Chrome's viewport and disables automatic cropping. Minimum: 1. Maximum: 6000. Both viewport dimensions must be supplied together.",
-            "maximum": 6000,
-            "minimum": 1,
-            "type": [
-              "integer",
-              "null"
-            ]
-          },
-          "viewport_landscape": {
-            "description": "Specifies whether the emulated viewport is in landscape orientation.",
-            "type": [
-              "boolean",
-              "null"
-            ]
-          },
-          "viewport_mobile": {
-            "description": "Specifies whether the page uses mobile viewport behavior, including its viewport meta tag.",
-            "type": [
-              "boolean",
-              "null"
-            ]
-          },
-          "viewport_touch": {
-            "description": "Specifies whether the emulated viewport supports touch events.",
-            "type": [
-              "boolean",
-              "null"
-            ]
-          },
-          "viewport_width": {
-            "description": "Sets the width of Chrome's viewport and disables automatic cropping. Minimum: 1. Maximum: 6000. Both viewport dimensions must be supplied together.",
-            "maximum": 6000,
-            "minimum": 1,
-            "type": [
-              "integer",
-              "null"
-            ]
-          }
-        },
-        "type": [
-          "object",
-          "null"
-        ]
-      },
-      "description": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "domain_id": {
-        "description": "Domain identifier used in this configuration's Open Graph image URLs.",
-        "type": "string"
-      },
-      "enabled": {
-        "description": "Whether the configuration is enabled to serve Open Graph images.",
-        "type": "boolean"
-      },
-      "extract_values": {
-        "description": "Whether image options are extracted from page metadata. When disabled, only the configured defaults are used.",
-        "type": "boolean"
-      },
-      "id": {
-        "type": "string"
-      },
-      "name": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "optimization_mode": {
-        "description": "How images are sized for different social platforms.",
-        "enum": [
-          "no_optimization",
-          "post_process",
-          "set_viewport"
-        ],
-        "type": "string"
-      },
-      "refresh_interval_s": {
-        "type": "integer"
-      },
-      "updated_at": {
-        "format": "date-time",
-        "type": "string"
-      }
-    },
-    "required": [
-      "id",
-      "domain_id",
-      "base_url"
-    ]
-  },
-  {
-    "description": "An Open Graph configuration that renders a template using extracted page metadata.",
-    "properties": {
-      "additional_header_origins": {
-        "description": "Additional exact HTTP or HTTPS origins allowed to receive custom headers, in the format scheme://host[:port] without a path.",
-        "items": {
-          "type": "string"
-        },
-        "type": [
-          "array",
-          "null"
-        ]
-      },
-      "base_url": {
-        "type": "string"
-      },
-      "config_type": {
-        "const": "templated"
-      },
-      "created_at": {
-        "format": "date-time",
-        "type": "string"
-      },
-      "description": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "domain_id": {
-        "description": "Domain identifier used in this configuration's Open Graph image URLs.",
-        "type": "string"
-      },
-      "enabled": {
-        "description": "Whether the configuration is enabled to serve Open Graph images.",
-        "type": "boolean"
-      },
-      "headers": {
-        "additionalProperties": {
-          "type": "string"
-        },
-        "description": "Custom HTTP headers sent on top-level page navigations to the source website's origin and any additional_header_origins.",
-        "type": [
-          "object",
-          "null"
-        ]
-      },
-      "id": {
-        "type": "string"
-      },
-      "name": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "optimization_mode": {
-        "description": "How images are sized for different social platforms.",
-        "enum": [
-          "no_optimization",
-          "post_process",
-          "set_viewport"
-        ],
-        "type": "string"
-      },
-      "refresh_interval_s": {
-        "type": "integer"
-      },
-      "template_id": {
-        "description": "ID of the template used to render images.",
-        "type": "string"
-      },
-      "template_values_mapping": {
-        "description": "Mappings from page metadata to template fields. Each mapping uses either a meta_key or a fallback.",
-        "items": {
-          "description": "Maps page metadata to a template field. Supply exactly one of meta_key or fallback.",
-          "properties": {
-            "fallback": {
-              "description": "Use the page's available title or description metadata. Supply this or meta_key, not both.",
-              "enum": [
-                "titles",
-                "descriptions",
-                null
-              ],
-              "type": [
-                "string",
-                "null"
-              ]
-            },
-            "meta_key": {
-              "description": "Meta tag name or property, such as og:title or twitter:description. Supply this or fallback, not both.",
-              "maxLength": 136,
-              "type": [
-                "string",
-                "null"
-              ]
-            },
-            "template_key": {
-              "description": "Template field path to populate, up to 128 characters.",
-              "maxLength": 128,
-              "type": "string"
-            }
-          },
-          "required": [
-            "template_key"
-          ],
-          "type": "object"
-        },
-        "type": [
-          "array",
-          "null"
-        ]
-      },
-      "template_version": {
-        "description": "Template version used to render images. Null means the latest version is used.",
-        "type": [
-          "integer",
-          "null"
-        ]
-      },
-      "updated_at": {
-        "format": "date-time",
-        "type": "string"
-      }
-    },
-    "required": [
-      "template_id",
-      "id",
-      "domain_id",
-      "base_url"
-    ]
-  }
-]New value: +[
+  {
+    "description": "An Open Graph configuration that renders page HTML/CSS.",
+    "properties": {
+      "base_url": {
+        "type": "string"
+      },
+      "config_type": {
+        "const": "html_css"
+      },
+      "created_at": {
+        "format": "date-time",
+        "type": "string"
+      },
+      "default_options": {
+        "description": "Default image rendering options for pages served by this configuration. Extracted image options override these defaults.",
+        "properties": {
+          "additional_header_origins": {
+            "description": "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.",
+            "items": {
+              "type": "string"
+            },
+            "type": [
+              "array",
+              "null"
+            ]
+          },
+          "block_consent_banners": {
+            "description": "Attempt to block cookie/consent banners from displaying.",
+            "type": [
+              "boolean",
+              "null"
+            ]
+          },
+          "color_scheme": {
+            "description": "Sets Chrome's preferred color scheme. Valid values: light or dark.",
+            "enum": [
+              "light",
+              "dark",
+              null
+            ],
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "css": {
+            "description": "CSS injected into the loaded page to override its styles.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "device_scale": {
+            "description": "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.",
+            "maximum": 3,
+            "minimum": 0.1,
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "disable_twemoji": {
+            "description": "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.",
+            "type": [
+              "boolean",
+              "null"
+            ]
+          },
+          "headers": {
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "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`.",
+            "type": [
+              "object",
+              "null"
+            ]
+          },
+          "identify_as_hcti": {
+            "description": "Identify the top-level page navigation as an HCTI screenshot request using the X-HCTI-SCREENSHOT header.",
+            "type": [
+              "boolean",
+              "null"
+            ]
+          },
+          "include_headers_on_subrequests": {
+            "description": "Include custom headers on subrequests to the requested URL's origin and any additional_header_origins. Defaults to false. Requires at least one header.",
+            "type": [
+              "boolean",
+              "null"
+            ]
+          },
+          "max_wait_ms": {
+            "description": "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.",
+            "maximum": 10000,
+            "minimum": 500,
+            "type": [
+              "integer",
+              "null"
+            ]
+          },
+          "media_type": {
+            "description": "Sets the CSS media type used while rendering the page. Valid values: print or screen.",
+            "enum": [
+              "print",
+              "screen",
+              null
+            ],
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "ms_delay": {
+            "description": "Adds extra time in milliseconds before taking the screenshot so JavaScript can execute. Minimum: 0. Maximum: 10000.",
+            "maximum": 10000,
+            "minimum": 0,
+            "type": [
+              "integer",
+              "null"
+            ]
+          },
+          "proxy_id": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "render_when_ready": {
+            "description": "Waits until the page signals that the screenshot is ready. The image fails if the readiness signal is never sent.",
+            "type": [
+              "boolean",
+              "null"
+            ]
+          },
+          "selector": {
+            "description": "A CSS selector for an element in the HTML. We’ll crop the image to this specific element.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "storage_destination_id": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "timezone": {
+            "description": "Sets the IANA timezone used by Chrome while rendering. Must be a recognized IANA timezone identifier.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "transparent_background": {
+            "description": "Specifies whether the image is rendered with a transparent background.",
+            "type": [
+              "boolean",
+              "null"
+            ]
+          },
+          "viewport_height": {
+            "description": "Sets the height of Chrome's viewport and disables automatic cropping. Minimum: 1. Maximum: 6000. Both viewport dimensions must be supplied together.",
+            "maximum": 6000,
+            "minimum": 1,
+            "type": [
+              "integer",
+              "null"
+            ]
+          },
+          "viewport_landscape": {
+            "description": "Specifies whether the emulated viewport is in landscape orientation.",
+            "type": [
+              "boolean",
+              "null"
+            ]
+          },
+          "viewport_mobile": {
+            "description": "Specifies whether the page uses mobile viewport behavior, including its viewport meta tag.",
+            "type": [
+              "boolean",
+              "null"
+            ]
+          },
+          "viewport_touch": {
+            "description": "Specifies whether the emulated viewport supports touch events.",
+            "type": [
+              "boolean",
+              "null"
+            ]
+          },
+          "viewport_width": {
+            "description": "Sets the width of Chrome's viewport and disables automatic cropping. Minimum: 1. Maximum: 6000. Both viewport dimensions must be supplied together.",
+            "maximum": 6000,
+            "minimum": 1,
+            "type": [
+              "integer",
+              "null"
+            ]
+          }
+        },
+        "type": [
+          "object",
+          "null"
+        ]
+      },
+      "description": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "domain_id": {
+        "description": "Domain identifier used in this configuration's Open Graph image URLs.",
+        "type": "string"
+      },
+      "enabled": {
+        "description": "Whether the configuration is enabled to serve Open Graph images.",
+        "type": "boolean"
+      },
+      "extract_values": {
+        "description": "Whether image options are extracted from page metadata. When disabled, only the configured defaults are used.",
+        "type": "boolean"
+      },
+      "id": {
+        "type": "string"
+      },
+      "name": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "optimization_mode": {
+        "description": "How images are sized for different social platforms.",
+        "enum": [
+          "no_optimization",
+          "post_process",
+          "set_viewport"
+        ],
+        "type": "string"
+      },
+      "refresh_interval_s": {
+        "type": "integer"
+      },
+      "updated_at": {
+        "format": "date-time",
+        "type": "string"
+      }
+    },
+    "required": [
+      "id",
+      "domain_id",
+      "base_url"
+    ]
+  },
+  {
+    "description": "An Open Graph configuration that renders a template using extracted page metadata.",
+    "properties": {
+      "additional_header_origins": {
+        "description": "Additional exact HTTP or HTTPS origins allowed to receive custom headers, in the format scheme://host[:port] without a path.",
+        "items": {
+          "type": "string"
+        },
+        "type": [
+          "array",
+          "null"
+        ]
+      },
+      "base_url": {
+        "type": "string"
+      },
+      "config_type": {
+        "const": "templated"
+      },
+      "created_at": {
+        "format": "date-time",
+        "type": "string"
+      },
+      "description": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "domain_id": {
+        "description": "Domain identifier used in this configuration's Open Graph image URLs.",
+        "type": "string"
+      },
+      "enabled": {
+        "description": "Whether the configuration is enabled to serve Open Graph images.",
+        "type": "boolean"
+      },
+      "headers": {
+        "additionalProperties": {
+          "type": "string"
+        },
+        "description": "Custom HTTP headers sent on top-level page navigations to the source website's origin and any additional_header_origins.",
+        "type": [
+          "object",
+          "null"
+        ]
+      },
+      "id": {
+        "type": "string"
+      },
+      "name": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "optimization_mode": {
+        "description": "How images are sized for different social platforms.",
+        "enum": [
+          "no_optimization",
+          "post_process",
+          "set_viewport"
+        ],
+        "type": "string"
+      },
+      "refresh_interval_s": {
+        "type": "integer"
+      },
+      "template_id": {
+        "description": "ID of the template used to render images.",
+        "type": "string"
+      },
+      "template_values_mapping": {
+        "description": "Mappings from page metadata to template fields. Each mapping uses either a meta_key or a fallback.",
+        "items": {
+          "description": "Maps page metadata to a template field. Supply exactly one of meta_key or fallback.",
+          "properties": {
+            "fallback": {
+              "description": "Use the page's available title or description metadata. Supply this or meta_key, not both.",
+              "enum": [
+                "titles",
+                "descriptions",
+                null
+              ],
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "meta_key": {
+              "description": "Meta tag name or property, such as og:title or twitter:description. Supply this or fallback, not both.",
+              "maxLength": 136,
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "template_key": {
+              "description": "Template field path to populate, up to 128 characters.",
+              "maxLength": 128,
+              "type": "string"
+            }
+          },
+          "required": [
+            "template_key"
+          ],
+          "type": "object"
+        },
+        "type": [
+          "array",
+          "null"
+        ]
+      },
+      "template_version": {
+        "description": "Template version used to render images. Null means the latest version is used.",
+        "type": [
+          "integer",
+          "null"
+        ]
+      },
+      "updated_at": {
+        "format": "date-time",
+        "type": "string"
+      }
+    },
+    "required": [
+      "template_id",
+      "id",
+      "domain_id",
+      "base_url"
+    ]
+  }
+]

Changed5 schema fields changedSep 15, 2026

changedInput schema / properties / count / description

Previous value: -"Maximum number of configurations to return, from 1 to 100."New value: +"Maximum number of configurations to return, from 1 to 100. Defaults to 10."

changedInput schema / properties / page_start / description

Previous value: -"pagination.next_page_start from the previous response. Omit for the first page."New value: +"Opaque cursor from item.pagination.next_page_start in the previous response. Pass it unchanged; omit for the first page."

addedOutput schema / properties / error / description

Added value: +"Error details when the operation failed; null on success."

addedOutput schema / properties / item / description

Added value: +"Operation result. Check success before using this value."

addedOutput schema / properties / success / description

Added value: +"Whether the operation succeeded. If false, inspect error before retrying."

First observedSep 15, 2026

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark this as read-only, idempotent, and non-destructive, so the description wisely adds non-redundant behavior: ordering, inclusion of disabled entries, result location in item.data, and pagination semantics. No contradiction exists between the description and annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with no filler: the first states what the tool does, the second tells where results live, and the third explains pagination. The most decision-relevant information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only, paginated listing tool with a rich output schema and annotations covering safety, the description covers the key operational facets: ordering, inclusion, result location, continuation, and terminal condition. Nothing an agent needs to invoke or paginate correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already documents count and page_start at 100% coverage, so the baseline is 3. The description adds operational value by clarifying how to chain pagination ('Pass item.pagination.next_page_start as page_start') and when to stop ('a null cursor marks the last page'), which goes slightly beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Lists the organization's Open Graph configurations') plus two scoping details that help distinguish it from other config tools: descending creation order and inclusion of disabled configurations. The sibling set includes create/get/update/delete_og_config, and this description makes the list operation unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly implies use when an agent needs a paginated, organization-wide list of OG configurations. However, it does not explicitly mention alternatives such as get_og_config for a single configuration or state when not to use this tool, so the decision is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All HTML/CSS to Image API tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?