- Docs
- Management API
- Recordings API
Recordings API
Manage the recordings your organization has created. To create one, see Using the API.
Operations
Section titled “Operations”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
/v1/recordingPermission required: images:create
MCP tool: create_url_recording
Get recording status
/v1/recordings/{id}/statusPermission required: images:read
MCP tool: get_recording_status
List recordings
/v1/recordingsPermission required: images:read
MCP tool: list_recordings
Retrieve a recording
/v1/recordings/{id}Permission required: images:read
MCP tool: get_recording
Store a recording
/v1/recording/{id}/storePermission required: images:store
MCP tool: store_recording
Delete a recording
/v1/recordings/{id}Permission required: images:delete
MCP tool: delete_recording
Delete a batch of recordings
/v1/recordings/batchPermission required: images:delete
MCP tool: Not available
Get recording status
Section titled “Get recording status”https://hcti.io/v1/recordings/{id}/statusYou 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}Statuses
Section titled “Statuses”| 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.
Errors
Section titled “Errors”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. |
List recordings
Section titled “List recordings”https://hcti.io/v1/recordingsReturns 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.
Retrieve a recording
Section titled “Retrieve a recording”https://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.
Store a recording
Section titled “Store a recording”https://hcti.io/v1/recording/{id}/storeSaves 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.
Storage destinations
Section titled “Storage destinations”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.
Delete recordings
Section titled “Delete recordings”https://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.
https://hcti.io/v1/recordings/batchDeletes several recordings at once:
{ "ids": ["01a1b2c3-d4e5-7f60-8a9b-0c1d2e3f4a5b", "01a1b2c4-0000-7f60-8a9b-0c1d2e3f4a5c"] }Each delete request sends one recording_deleted webhook.
Webhooks
Section titled “Webhooks”| 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.