Keystone Developers
Open Keystone
API reference

Console API

Website

19 endpoints.

GET/api/v1/admin/businesses/{business_id}/website

Get website for business

Always 200. Returns optional website payload (null if not created).

Parameters

NameInTypeDescription
business_idrequiredpathstring (uuid)
authorizationheaderstring | null

Responses

200Successful Response
application/jsonSuccessResponse_WebsiteGetResponse_
FieldTypeDescription
request_idrequiredstring
successtruedefault true
datarequiredWebsiteGetResponse
WebsiteGetResponse fields
FieldTypeDescription
websiteWebsiteResponse | null
WebsiteResponse fields
FieldTypeDescription
idrequiredstring (uuid)
business_idrequiredstring (uuid)
namerequiredstring
slugrequiredstring
domainrequiredstring
preview_urlstring | null
worker_urlstring | null
custom_domainstring | null
source_domainstring | null
statusrequiredstring
custom_promptstring | null
provisioning_errorstring | null
provisioning_logsProvisioningLogEntry[] | null
ProvisioningLogEntry[] | null fields

Nested object (not expanded)

github_repo_idinteger | null
website_photosWebsitePhotos | null
WebsitePhotos fields

WebsitePhotos (not expanded)

metadataResponseMetadata | null
ResponseMetadata fields
FieldTypeDescription
paginationPaginationMetadata | null
PaginationMetadata fields
FieldTypeDescription
limitrequiredinteger
next_cursorstring | null
prev_cursorstring | null
has_morerequiredboolean
has_prevbooleandefault false
total_countinteger | null
status_countsobject | null
object | null fields

Map of string to integer

lifecycle_countsLifecycleCounts | null
LifecycleCounts fields
FieldTypeDescription
leadintegerdefault 0
prospectintegerdefault 0
customerintegerdefault 0
former_customerintegerdefault 0
classification_countsClassificationCounts | null
ClassificationCounts fields
FieldTypeDescription
signalobject
object fields

Nested object (not expanded)

touchobject
object fields

Nested object (not expanded)

stageobject
object fields

Nested object (not expanded)

metaResponseMeta | null
ResponseMeta fields
FieldTypeDescription
totalinteger | null
total_countinteger | null
pageinteger | null
per_pageinteger | null
  • 400Bad request
  • 401Unauthorized
  • 403Forbidden
  • 404Not found
  • 422Validation error
  • 500Internal server error
  • 503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/businesses/{business_id}/website

Create website for business

Create website + API key for the business, trigger provisioning, and return website only.

Takes no input beyond ``business_id``: the generator builds from the business's own backend content, so there is no design prompt to supply.

Parameters

NameInTypeDescription
business_idrequiredpathstring (uuid)
authorizationheaderstring | null

Request body

application/jsonWebsiteCreateBody | null
FieldTypeDescription

Responses

201Successful Response
application/jsonSuccessResponse_WebsiteCreateResponse_
FieldTypeDescription
request_idrequiredstring
successtruedefault true
datarequiredWebsiteCreateResponse
WebsiteCreateResponse fields
FieldTypeDescription
websiterequiredWebsiteResponse
WebsiteResponse fields

WebsiteResponse, expanded above.

metadataResponseMetadata | null
ResponseMetadata fields

ResponseMetadata, expanded above.

metaResponseMeta | null
ResponseMeta fields

ResponseMeta, expanded above.

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

Error bodies: ErrorResponse. See Errors.

GET/api/v1/admin/businesses/{business_id}/website-check/artifacts/{artifact_id}

A screenshot the site agent's browser check took

The image bytes; 404 for a screenshot of another business, or none.

Parameters

NameInTypeDescription
business_idrequiredpathstring (uuid)
artifact_idrequiredpathstring
authorizationheaderstring | null

Responses

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

Error bodies: ErrorResponse. See Errors.

GET/api/v1/admin/businesses/{business_id}/website-mod/requirements/{file_id}

Download a document attached for the site agent

The document as the owner attached it; 404 for another business's.

Parameters

NameInTypeDescription
business_idrequiredpathstring (uuid)
file_idrequiredpathstring
authorizationheaderstring | null

Responses

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

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/businesses/{business_id}/website-mod/requirements/upload

Upload a document for the site agent (website editor chats)

Store a document the owner attached for the site agent. With the private bucket: a PDF, Word, Excel, PowerPoint or text file, validated and converted at once (the answer lists the derived files and any ``warnings``); without it, text files only, as before.

Parameters

NameInTypeDescription
business_idrequiredpathstring (uuid)
authorizationheaderstring | null

Request bodyrequired

multipart/form-dataBody_upload_website_mod_requirements_api_v1_admin_businesses__business_id__website_mod_requirements_upload_post
FieldTypeDescription
filerequiredstring

Responses

200Successful Response
application/jsonSuccessResponse_WebsiteAgentDocumentUpload_
FieldTypeDescription
request_idrequiredstring
successtruedefault true
datarequiredWebsiteAgentDocumentUpload
WebsiteAgentDocumentUpload fields
FieldTypeDescription
file_idrequiredstring
filenamerequiredstring
content_typestring | null
kindstring | null
sizeinteger | null
derivedstring[]
string[] fields
warningsstring[]
string[] fields
pagesinteger | null
sheetsinteger | null
slidesinteger | null
metadataResponseMetadata | null
ResponseMetadata fields

ResponseMetadata, expanded above.

metaResponseMeta | null
ResponseMeta fields

ResponseMeta, expanded above.

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

Error bodies: ErrorResponse. See Errors.

GET/api/v1/admin/businesses/{business_id}/website/api-key

Reveal the website's public API key (live credential)

Return the site's live public API key, in the clear.

404 while the feature flag is off; 404 for an unknown business or a business with no website; 409 when the site has no readable key yet. The key returned is the one the running site uses — revealing never rotates.

Parameters

NameInTypeDescription
business_idrequiredpathstring (uuid)
authorizationheaderstring | null

Responses

200Successful Response
application/jsonSuccessResponse_WebsiteApiKeyRevealData_
FieldTypeDescription
request_idrequiredstring
successtruedefault true
datarequiredWebsiteApiKeyRevealData
WebsiteApiKeyRevealData fields
FieldTypeDescription
api_keyrequiredstring
metadataResponseMetadata | null
ResponseMetadata fields

ResponseMetadata, expanded above.

metaResponseMeta | null
ResponseMeta fields

ResponseMeta, expanded above.

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

Error bodies: ErrorResponse. See Errors.

GET/api/v1/admin/businesses/{business_id}/website/collaborators

List who has access to the business's site repo

Direct collaborators (``status="active"``) merged with pending invitations (``status="invited"``). Direct affiliation only: org-inherited members (Keystone staff, the App) are asked out of the list at GitHub.

404 while the flag is off, for an unknown business, and for a business with no site repo yet.

Parameters

NameInTypeDescription
business_idrequiredpathstring (uuid)
authorizationheaderstring | null

Responses

200Successful Response
application/jsonSuccessResponse_WebsiteCollaboratorsData_
FieldTypeDescription
request_idrequiredstring
successtruedefault true
datarequiredWebsiteCollaboratorsData
WebsiteCollaboratorsData fields
FieldTypeDescription
repo_full_namerequiredstring
collaboratorsrequiredWebsiteCollaboratorRow[]
WebsiteCollaboratorRow[] fields

WebsiteCollaboratorRow (not expanded)

metadataResponseMetadata | null
ResponseMetadata fields

ResponseMetadata, expanded above.

metaResponseMeta | 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/admin/businesses/{business_id}/website/collaborators

Invite a GitHub username to the business's site repo (push)

Invite at push. Idempotent-friendly: an already-invited or already-active username answers 200 with ``already=true`` and a sentence saying so — repeats are clean answers, not errors.

422 for a blank or unknown username; 503 ``GITHUB_APP_PERMISSION_MISSING`` when the App lacks the Administration permission.

Parameters

NameInTypeDescription
business_idrequiredpathstring (uuid)
authorizationheaderstring | null

Request bodyrequired

application/jsonWebsiteCollaboratorInviteBody
FieldTypeDescription
usernamerequiredstring

Responses

200Successful Response
application/jsonSuccessResponse_WebsiteCollaboratorInviteData_
FieldTypeDescription
request_idrequiredstring
successtruedefault true
datarequiredWebsiteCollaboratorInviteData
WebsiteCollaboratorInviteData fields
FieldTypeDescription
usernamerequiredstring
statusrequiredenumone of "active", "invited"
alreadyrequiredboolean
permissionenum | null
invitation_idinteger | null
messagerequiredstring
metadataResponseMetadata | null
ResponseMetadata fields

ResponseMetadata, expanded above.

metaResponseMeta | null
ResponseMeta fields

ResponseMeta, expanded above.

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

Error bodies: ErrorResponse. See Errors.

DELETE/api/v1/admin/businesses/{business_id}/website/collaborators/{username}

Remove a collaborator or cancel their pending invitation

One endpoint for both shapes of "take their access away": sor cancels the pending invitation if that is what exists, removes the active direct collaborator otherwise. 404 when the username has neither.

Parameters

NameInTypeDescription
business_idrequiredpathstring (uuid)
usernamerequiredpathstring
authorizationheaderstring | null

Responses

200Successful Response
application/jsonSuccessResponse_WebsiteCollaboratorRemoveData_
FieldTypeDescription
request_idrequiredstring
successtruedefault true
datarequiredWebsiteCollaboratorRemoveData
WebsiteCollaboratorRemoveData fields
FieldTypeDescription
usernamerequiredstring
removedrequiredenumone of "invitation", "collaborator"
messagerequiredstring
metadataResponseMetadata | null
ResponseMetadata fields

ResponseMetadata, expanded above.

metaResponseMeta | null
ResponseMeta fields

ResponseMeta, expanded above.

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

Error bodies: ErrorResponse. See Errors.

GET/api/v1/admin/businesses/{business_id}/website/commits

List the website's change history (History tab)

The conversation's changes as a git log, newest first.

404 while the preview flag is off, and for a business with no website row. A website with no repository yet answers 200 with the honest-empty shape.

Parameters

NameInTypeDescription
business_idrequiredpathstring (uuid)
authorizationheaderstring | null

Responses

200Successful Response
application/jsonSuccessResponse_WebsiteCommitsResponse_
FieldTypeDescription
request_idrequiredstring
successtruedefault true
datarequiredWebsiteCommitsResponse
WebsiteCommitsResponse fields
FieldTypeDescription
repo_full_namestring | null
default_branchstring | null
launched_atstring | null
confirm_textstring | null
commitsWebsiteCommitItem[]default []
WebsiteCommitItem[] fields

WebsiteCommitItem (not expanded)

metadataResponseMetadata | null
ResponseMetadata fields

ResponseMetadata, expanded above.

metaResponseMeta | null
ResponseMeta fields

ResponseMeta, expanded above.

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

Error bodies: ErrorResponse. See Errors.

PUT/api/v1/admin/businesses/{business_id}/website/photos

Update website photo mappings

Update website photo selections (partial). Only slot IDs present in the active config are applied.

Parameters

NameInTypeDescription
business_idrequiredpathstring (uuid)
authorizationheaderstring | null

Request bodyrequired

application/jsonWebsitePhotosUpdate

Map of string to string | null

Responses

200Successful Response
application/jsonSuccessResponse_WebsiteResponse_
FieldTypeDescription
request_idrequiredstring
successtruedefault true
datarequiredWebsiteResponse
WebsiteResponse fields

WebsiteResponse, expanded above.

metadataResponseMetadata | null
ResponseMetadata fields

ResponseMetadata, expanded above.

metaResponseMeta | null
ResponseMeta fields

ResponseMeta, expanded above.

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

Error bodies: ErrorResponse. See Errors.

GET/api/v1/admin/websites/{website_id}/custom-domain

Get custom domain state

Return current custom_domain, worker_name (repo_name), and preview_url when set; otherwise success with custom_domain: null.

Parameters

NameInTypeDescription
website_idrequiredpathstring (uuid)
authorizationheaderstring | null

Responses

200Successful Response
application/jsonSuccessResponse_CustomDomainGetResponse_
FieldTypeDescription
request_idrequiredstring
successtruedefault true
datarequiredCustomDomainGetResponse
CustomDomainGetResponse fields
FieldTypeDescription
successbooleandefault true
custom_domainstring | null
source_domainstring | null
worker_namestring | null
preview_urlstring | null
entri_enabledbooleandefault false
metadataResponseMetadata | null
ResponseMetadata fields

ResponseMetadata, expanded above.

metaResponseMeta | 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/admin/websites/{website_id}/custom-domain

Create or attach custom domain

Set custom domain for a website. Normalizes apex to www, creates Cloudflare custom hostname if needed, returns DNS instructions.

Parameters

NameInTypeDescription
website_idrequiredpathstring (uuid)
authorizationheaderstring | null

Request bodyrequired

application/jsonCustomDomainCreateRequest
FieldTypeDescription
domainrequiredstring

Responses

200Successful Response
application/jsonSuccessResponse_CustomDomainCreateResponse_
FieldTypeDescription
request_idrequiredstring
successtruedefault true
datarequiredCustomDomainCreateResponse
CustomDomainCreateResponse fields
FieldTypeDescription
successbooleandefault true
custom_domainrequiredstring
dns_instructionsrequiredDnsInstructions
DnsInstructions fields
FieldTypeDescription
cnamerequiredDnsInstructionsCname
DnsInstructionsCname fields

DnsInstructionsCname (not expanded)

txtrequiredDnsInstructionsTxtRecord[]
DnsInstructionsTxtRecord[] fields

Nested object (not expanded)

apex_forwardingrequiredDnsInstructionsApexForwarding
DnsInstructionsApexForwarding fields

DnsInstructionsApexForwarding (not expanded)

dcv_cnameDnsInstructionsCname | null
DnsInstructionsCname fields

DnsInstructionsCname (not expanded)

domainstring | null
recordsDnsInstructionsRecord[]default []
DnsInstructionsRecord[] fields

Nested object (not expanded)

redirectDnsInstructionsRedirect | null
DnsInstructionsRedirect fields

DnsInstructionsRedirect (not expanded)

converted_fromstring | null
messagestring | null
metadataResponseMetadata | null
ResponseMetadata fields

ResponseMetadata, expanded above.

metaResponseMeta | null
ResponseMeta fields

ResponseMeta, expanded above.

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

Error bodies: ErrorResponse. See Errors.

DELETE/api/v1/admin/websites/{website_id}/custom-domain

Remove custom domain

Remove custom domain: delete in Cloudflare and clear website.custom_domain. 404 if none configured.

Parameters

NameInTypeDescription
website_idrequiredpathstring (uuid)
authorizationheaderstring | null

Responses

200Successful Response
application/jsonSuccessResponse_CustomDomainDeleteResponse_
FieldTypeDescription
request_idrequiredstring
successtruedefault true
datarequiredCustomDomainDeleteResponse
CustomDomainDeleteResponse fields
FieldTypeDescription
messagerequiredstring
metadataResponseMetadata | null
ResponseMetadata fields

ResponseMetadata, expanded above.

metaResponseMeta | null
ResponseMeta fields

ResponseMeta, expanded above.

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

Error bodies: ErrorResponse. See Errors.

GET/api/v1/admin/websites/{website_id}/custom-domain-status

Get custom domain status

Return Cloudflare status, ssl_status, validation_records, and dns_instructions when custom_domain is set; else { status: 'none' }.

Parameters

NameInTypeDescription
website_idrequiredpathstring (uuid)
authorizationheaderstring | null

Responses

200Successful Response
application/jsonSuccessResponse_CustomDomainStatusResponse_
FieldTypeDescription
request_idrequiredstring
successtruedefault true
datarequiredCustomDomainStatusResponse
CustomDomainStatusResponse fields
FieldTypeDescription
successbooleandefault true
statusrequiredstring
domainstring | null
ssl_statusstring | null
validation_errorsany[] | null
any[] | null fields
validation_recordsobject[] | null
object[] | null fields

Nested object (not expanded)

dns_instructionsDnsInstructions | null
DnsInstructions fields

DnsInstructions, expanded above.

metadataResponseMetadata | null
ResponseMetadata fields

ResponseMetadata, expanded above.

metaResponseMeta | null
ResponseMeta fields

ResponseMeta, expanded above.

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

Error bodies: ErrorResponse. See Errors.

GET/api/v1/admin/websites/{website_id}/entri-setup

Get Entri setup (token + dnsRecords) for automated DNS

Mint a fresh Entri token and build the dnsRecords for entri.showEntri().

Dedicated endpoint (not folded into create/status) so a fresh short-lived token is minted each time the user opens the modal. 409 if no custom domain is configured yet.

Parameters

NameInTypeDescription
website_idrequiredpathstring (uuid)
authorizationheaderstring | null

Responses

200Successful Response
application/jsonSuccessResponse_EntriSetupResponse_
FieldTypeDescription
request_idrequiredstring
successtruedefault true
datarequiredEntriSetupResponse
EntriSetupResponse fields
FieldTypeDescription
successbooleandefault true
application_idrequiredstring
tokenrequiredstring
prefilled_domainrequiredstring
dns_recordsrequiredEntriDnsRecord[]
EntriDnsRecord[] fields

EntriDnsRecord (not expanded)

metadataResponseMetadata | null
ResponseMetadata fields

ResponseMetadata, expanded above.

metaResponseMeta | null
ResponseMeta fields

ResponseMeta, expanded above.

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

Error bodies: ErrorResponse. See Errors.

GET/api/v1/admin/websites/{website_id}/provisioning-stream

Stream provisioning logs and status for a website (SSE)

Server-Sent Events stream of provisioning logs/status for a website.

Parameters

NameInTypeDescription
website_idrequiredpathstring (uuid)
after_seqqueryinteger | null
authorizationheaderstring | null

Responses

200Successful Response
text/event-streamstring
  • 400Bad request
  • 401Unauthorized
  • 403Forbidden
  • 404Not found
  • 422Validation error
  • 500Internal server error
  • 503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/websites/{website_id}/reconcile-custom-domain

Reconcile orphaned custom domain

Link an orphaned domain (in Cloudflare but not in DB) to this website. 404 if not in CF; 409 if linked to another website.

Parameters

NameInTypeDescription
website_idrequiredpathstring (uuid)
authorizationheaderstring | null

Request bodyrequired

application/jsonCustomDomainCreateRequest

CustomDomainCreateRequest, expanded above.

Responses

200Successful Response
application/jsonSuccessResponse_CustomDomainReconcileResponse_
FieldTypeDescription
request_idrequiredstring
successtruedefault true
datarequiredCustomDomainReconcileResponse
CustomDomainReconcileResponse fields
FieldTypeDescription
successbooleandefault true
messagerequiredstring
custom_domainrequiredstring
cloudflare_statusrequiredCloudflareStatusInfo
CloudflareStatusInfo fields
FieldTypeDescription
statusrequiredstring
ssl_statusrequiredstring
validation_errorsany[]default []
any[] fields

Nested object (not expanded)

metadataResponseMetadata | null
ResponseMetadata fields

ResponseMetadata, expanded above.

metaResponseMeta | 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/admin/websites/{website_id}/reprovision

Re-provision a failed website

Reset a failed website and re-run its build in the background.

404 if the website does not exist, 409 if it is already active or currently provisioning. On success the error is cleared and a fresh build is kicked off. Without a website preview that is the classic path the create endpoint uses (status reset to ``provisioning``); a website preview's failed full build is retried as that build, seeded from the confirmed draft — 409 for a draft not confirmed yet (see ``website_svc.reprovision_website``) — and the answer waits (bounded) for the workflow start it makes, as the preview routes do.

A plain retry: it re-runs the same fixed brief against the business's current backend content. The body is accepted but ignored (see ``WebsiteReprovisionBody``).

Parameters

NameInTypeDescription
website_idrequiredpathstring (uuid)
authorizationheaderstring | null

Request body

application/jsonWebsiteReprovisionBody | null
FieldTypeDescription

Responses

200Successful Response
application/jsonSuccessResponse_WebsiteReprovisionResponse_
FieldTypeDescription
request_idrequiredstring
successtruedefault true
datarequiredWebsiteReprovisionResponse
WebsiteReprovisionResponse fields
FieldTypeDescription
websiterequiredWebsiteResponse
WebsiteResponse fields

WebsiteResponse, expanded above.

metadataResponseMetadata | null
ResponseMetadata fields

ResponseMetadata, expanded above.

metaResponseMeta | null
ResponseMeta fields

ResponseMeta, expanded above.

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

Error bodies: ErrorResponse. See Errors.