Skip to content
HTML/CSS to ImageDocs

Manage the recordings your organization has created. To create one, see Using the API.

Use the https://hcti.io/v1 base URL and HTTP Basic authentication. Recordings use the same images:* permissions as images. Resource IDs must belong to the authenticated organization.

Create a recording

POST/v1/recording

Permission required: images:create

MCP tool: create_url_recording

Get recording status

GET/v1/recordings/{id}/status

Permission required: images:read

MCP tool: get_recording_status

List recordings

GET/v1/recordings

Permission required: images:read

MCP tool: list_recordings

Retrieve a recording

GET/v1/recordings/{id}

Permission required: images:read

MCP tool: get_recording

Store a recording

PUT/v1/recording/{id}/store

Permission required: images:store

MCP tool: store_recording

Delete a recording

DELETE/v1/recordings/{id}

Permission required: images:delete

MCP tool: delete_recording

Delete a batch of recordings

DELETE/v1/recordings/batch

Permission required: images:delete

MCP tool: Not available

GEThttps://hcti.io/v1/recordings/{id}/status

You don’t need this to use a recording, because requesting its recording_url waits until it’s finished. Status checks are for workflows that would rather not hold a request open.

Returns 202 Accepted until the recording is finished, then 200 OK. Responses are never cached.

{
"id": "01a1b2c3-d4e5-7f60-8a9b-0c1d2e3f4a5b",
"status": "ready",
"status_entered_at": "2026-11-16T15:04:12Z",
"attempt_count": 1,
"error": null,
"stored_duration_ms": 9840,
"recording_url": "https://hcti.io/v1/recording/01a1b2c3-d4e5-7f60-8a9b-0c1d2e3f4a5b.mp4",
"storage_destination_hcti_storage_disabled": null
}
Status Finished Meaning
processing No The recording is being made.
pending_retry No An attempt hit a temporary problem and will be retried. error describes it.
awaiting_render No Created with defer_render and not requested yet.
ready Yes The recording is saved and recording_url serves it, unless HCTI storage is disabled.
failed Yes The recording couldn’t be made. See errors.
cancelled Yes The recording was stopped before it finished.

When checking in a loop, wait a few seconds between requests.

error describes the most recent failure. It can describe an attempt that will be retried, so check status first.

{
"code": "action_error",
"message": "The action requested that the recording fail.",
"occurred_at": "2026-11-16T15:04:12Z",
"retryable": false,
"action_path": "actions[1].if_not_found[0]"
}
Code Retried Cause
trigger_timeout No The trigger didn’t fire before its timeout_ms.
action_error No An error action ran. action_path shows which one.
javascript_error No An execute_javascript script threw an error and had no if_error branch.
javascript_timeout No A script ran past its timeout_ms and had no if_error branch.
resource_limit No The recording went over a size or processing limit. Lower the resolution, frame rate, or duration.
invalid_request No The page or settings couldn’t be recorded as requested.
recording_error Yes A temporary problem interrupted the attempt.
GEThttps://hcti.io/v1/recordings

Returns your organization’s recordings, newest first. Deleted recordings aren’t included. count sets the page size, from 1 to 50 (default 50). Pass next_page_token as page_token to get the next page while has_next_page is true.

{
"recordings": [
{
"id": "01a1b2c3-d4e5-7f60-8a9b-0c1d2e3f4a5b",
"created_at": "2026-11-16T15:03:58Z",
"status": "ready",
"status_entered_at": "2026-11-16T15:04:12Z",
"attempt_count": 1,
"recording_url": "https://hcti.io/v1/recording/01a1b2c3-d4e5-7f60-8a9b-0c1d2e3f4a5b.mp4",
"status_url": "https://hcti.io/v1/recordings/01a1b2c3-d4e5-7f60-8a9b-0c1d2e3f4a5b/status"
}
],
"next_page_token": "eyJ...",
"has_next_page": true
}

A listed status was correct when the entry was written. Use status_url for the current status.

GEThttps://hcti.io/v1/recordings/{id}

Returns the recording’s status, credits, and the source and settings it was created with. recording_type is html_css or url. Settings you didn’t send are null.

{
"recording_type": "url",
"id": "01a1b2c3-d4e5-7f60-8a9b-0c1d2e3f4a5b",
"recording_url": "https://hcti.io/v1/recording/01a1b2c3-d4e5-7f60-8a9b-0c1d2e3f4a5b.mp4",
"created_at": "2026-11-16T15:03:58Z",
"updated_at": "2026-11-16T15:04:12Z",
"status": "ready",
"status_entered_at": "2026-11-16T15:04:12Z",
"attempt_count": 1,
"error": null,
"credit_count": 3,
"stored_duration_ms": 9840,
"last_render_stored_at": "2026-11-16T15:04:12Z",
"saved_to_storage_destination_at": null,
"storage_destination_hcti_storage_disabled": null,
"url": "https://example.com/",
"duration_ms": 10000,
"duration_mode": null,
"actions": [{ "type": "simple_scroll" }],
"output": { "format": "mp4" }
}

credit_count is the number of credits the recording used. stored_duration_ms is the finished video’s length, which can differ from duration_ms depending on duration_mode.

PUThttps://hcti.io/v1/recording/{id}/store

Saves the recording to HCTI storage, or to its storage destination, without downloading it. If it was created with defer_render, this starts it. A recording that’s already stored isn’t recorded again. Requires images:store.

With a storage_destination_id, finished recordings are also uploaded to your bucket. If the destination has Disable HCTI Storage turned on, the recording goes only to your bucket and recording_url doesn’t serve it. Read it from your bucket once its status is ready, or when you get a recording_stored webhook.

DELETEhttps://hcti.io/v1/recordings/{id}

Deletes one recording and returns 202 Accepted. Copies already saved to your storage destination aren’t deleted. Deleting doesn’t refund credits.

DELETEhttps://hcti.io/v1/recordings/batch

Deletes several recordings at once:

{ "ids": ["01a1b2c3-d4e5-7f60-8a9b-0c1d2e3f4a5b", "01a1b2c4-0000-7f60-8a9b-0c1d2e3f4a5c"] }

Each delete request sends one recording_deleted webhook.

Event When
recording_stored A recording was saved. If it’s saved to both HCTI storage and a storage destination, you get one event for each.
recording_failed A recording failed and won’t be retried.
recording_deleted A delete request removed one or more recordings.

Need help?

Talk to a human. Email support@htmlcsstoimage.com and we’ll help you get started.