Internal API

Website preview runs

7 endpoints.

POST/api/v1/internal/website-preview/agent-callback

Post Website Preview Agent Callback

Store an edit slot's result (2 h) for the workflow's settle. Only an edit run's token posts here: a build reports through the generator callback, and a stored result is settled as a slot's. A check-only run ("Check again") settles nothing: its check is recorded here.

Parameters

Name	In	Type	Description
`x-internal-api-key`	header	`string \| null`
`X-Keystone-Run-Token`	header	`string \| null`

Request bodyrequired

application/jsonPreviewAgentCallbackRequest

Field	Type	Description
`plan_request_id`required	`string`
`website_id`required	`string \| string (uuid)`	string \| string (uuid) fields string string (uuid)
`status`required	`string`
`summary`	`string`	default ""
`agent_message`	`string`	default ""
`file_updates`	`object[]`	object[] fields
`primitives`	`object[]`	object[] fields
`error`	`string`	default ""
`cost_usd`	`number \| null`
`duration_s`	`number \| null`
`run_id`	`string`	default ""
`smoke`	`object \| null`
`confirmation`	`object \| null`
`denied_commands`	`string[]`	string[] fields
`stop_source`	`string`	default ""
`model`	`string`	default ""
`usage`	`object \| null`
`browser_check`	`object \| null`
`check_only`	`boolean`	default false
`interrupt`	`object \| null`
`notes_delivered`	`string[]`	string[] fields
`fetched_urls`	`object[]`	object[] fields
`notes_pending`	`string[]`	string[] fields
`checks`	`object \| null`
`failure_kind`	`string`	default ""

Responses

200Successful Response

application/jsonSuccessResponse_dict_str__Any__

Field Type Description

request_idrequired string

success true default true

datarequired object

metadata

ResponseMetadata | null

ResponseMetadata fields

Field Type Description

pagination

PaginationMetadata | null

PaginationMetadata fields

Field	Type	Description
`limit`required	`integer`
`next_cursor`	`string \| null`
`prev_cursor`	`string \| null`
`has_more`required	`boolean`
`has_prev`	`boolean`	default false
`total_count`	`integer \| null`

status_counts

object | null

object | null fields

Map of string to integer

lifecycle_counts

LifecycleCounts | null

LifecycleCounts fields

Field	Type	Description
`lead`	`integer`	default 0
`prospect`	`integer`	default 0
`customer`	`integer`	default 0
`former_customer`	`integer`	default 0

classification_counts

ClassificationCounts | null

ClassificationCounts fields

Field	Type	Description
`signal`	`object`	object fields Nested object (not expanded)
`touch`	`object`	object fields Nested object (not expanded)
`stage`	`object`	object fields Nested object (not expanded)

meta

ResponseMeta | null

ResponseMeta fields

Field	Type	Description
`total`	`integer \| null`
`total_count`	`integer \| null`
`page`	`integer \| null`
`per_page`	`integer \| null`

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/internal/website-preview/agent-progress

Post Website Preview Agent Progress

Append a sanitized event to the run's activity trail. A full build's ring is deeper than an edit's: it runs for most of an hour.

Parameters

Name	In	Type	Description
`x-internal-api-key`	header	`string \| null`
`X-Keystone-Run-Token`	header	`string \| null`

Request bodyrequired

application/jsonWebsiteModAgentProgressRequest

Field	Type	Description
`plan_request_id`required	`string`
`website_id`required	`string \| string (uuid)`	string \| string (uuid) fields string string (uuid)
`seq`required	`integer`
`ts`	`integer \| null`
`kind`required	`string`
`stage`	`string \| null`
`text`	`string \| null`
`tool`	`string \| null`
`label`	`string \| null`
`block`	`string \| null`
`status`	`string \| null`
`partial`	`boolean`	default false
`artifact`	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_dict_str__Any__

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`object`
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/internal/website-preview/check-artifacts

Post Website Preview Check Artifact

One browser-check screenshot from a preview edit's pod, under that run's token. The image is the raw request body.

Parameters

Name	In	Type	Description
`plan_request_id`required	query	`string`
`route`required	query	`string`
`viewport`required	query	`string`
`kind`	query	`string`	default "fold"
`x-internal-api-key`	header	`string \| null`
`X-Keystone-Run-Token`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_dict_str__Any__

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`object`
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/internal/workflow-engine/website-preview/runs/fail

Post Preview Run Fail

``{state}`` — ``failed``, or the state a settled run already had.

Parameters

Name	In	Type	Description
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonPreviewRunFailBody

Field	Type	Description
`preview_id`required	`string (uuid)`
`revision`	`integer`	default 0 · min 0
`kind`required	`enum`	one of "preview", "edit", "full"
`run_id`	`string`	default ""
`reason`	`string`	default ""

Responses

200Successful Response

application/jsonSuccessResponse_dict_str__Any__

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`object`
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/internal/workflow-engine/website-preview/runs/settle

Post Preview Run Settle

``{state, checkpoint_sha, reason, fallback_eligible}``; idempotent.

Parameters

Name	In	Type	Description
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonPreviewRunRefBody

Field	Type	Description
`preview_id`required	`string (uuid)`
`revision`	`integer`	default 0 · min 0
`kind`required	`enum`	one of "preview", "edit", "full"
`run_id`	`string`	default ""

Responses

200Successful Response

application/jsonSuccessResponse_dict_str__Any__

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`object`
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/internal/workflow-engine/website-preview/runs/start

Post Preview Run Start

``{executor, run_id, deadline_s, state}``; idempotent per attempt.

Parameters

Name	In	Type	Description
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonPreviewRunStartBody

Field	Type	Description
`preview_id`required	`string (uuid)`
`revision`	`integer`	default 0 · min 0
`kind`required	`enum`	one of "preview", "edit", "full"
`workflow_run_id`	`string`	default ""
`attempt`	`integer`	default 1 · min 1
`force_executor`	`enum \| null`

Responses

200Successful Response

application/jsonSuccessResponse_dict_str__Any__

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`object`
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/internal/workflow-engine/website-preview/runs/status

Post Preview Run Status

``{state, executor, reason, fallback_eligible, deadline_s}``. Read-only but for one case: a later attempt whose launch was lost is failed here (no one else will), hence the commit.

Parameters

Name	In	Type	Description
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonPreviewRunRefBody

PreviewRunRefBody, expanded above.

Responses

200Successful Response

application/jsonSuccessResponse_dict_str__Any__

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`object`
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.