API reference
Internal API
Service-to-service operations: onboarding, workflows, media, previews, callbacks.
Endpoints other Keystone services call: onboarding and import pipelines, the workflow engine, media processing, website preview runs, agent callbacks, and consumer auth. Not for external callers; listed so that the whole contract is in one place.
157 endpoints in 25 groups.
Account invites
Account user invites
Ads workflow engine
- POST
/api/v1/internal/workflow-engine/ads/archive-campaignArchive Campaign - POST
/api/v1/internal/workflow-engine/ads/create-ad-unitCreate Ad Unit - POST
/api/v1/internal/workflow-engine/ads/create-refresh-draftCreate Refresh Draft - POST
/api/v1/internal/workflow-engine/ads/disable-all-unitsDisable All Units - POST
/api/v1/internal/workflow-engine/ads/draft-proposalDraft Campaign Proposal - POST
/api/v1/internal/workflow-engine/ads/generate-refresh-planGenerate Refresh Plan - POST
/api/v1/internal/workflow-engine/ads/get-campaignGet Campaign - POST
/api/v1/internal/workflow-engine/ads/get-insight-tileGet Insight Tile - POST
/api/v1/internal/workflow-engine/ads/get-refresh-contextGet Refresh Context - POST
/api/v1/internal/workflow-engine/ads/list-ad-setsList Ad Sets - POST
/api/v1/internal/workflow-engine/ads/list-campaignsList Campaigns - POST
/api/v1/internal/workflow-engine/ads/propose-campaignPropose Campaign - POST
/api/v1/internal/workflow-engine/ads/review-refresh-mediaReview Refresh Media - POST
/api/v1/internal/workflow-engine/ads/toggle-unitToggle Unit - POST
/api/v1/internal/workflow-engine/ads/update-ad-setUpdate Ad Set - POST
/api/v1/internal/workflow-engine/ads/update-ad-unitUpdate Ad Unit - POST
/api/v1/internal/workflow-engine/ads/update-campaignUpdate Campaign - POST
/api/v1/internal/workflow-engine/ads/update-refresh-statusUpdate Refresh Status
Blog posts
- GET
/api/v1/internal/businesses/{business_id}/blog_postsList blog posts for a business (internal) - POST
/api/v1/internal/businesses/{business_id}/blog_postsCreate a blog post (internal) - GET
/api/v1/internal/businesses/{business_id}/blog_posts/{blog_post_id}Get a single blog post (internal) - PUT
/api/v1/internal/businesses/{business_id}/blog_posts/{blog_post_id}Update a blog post (internal) - POST
/api/v1/internal/businesses/{business_id}/blog_posts/generateGenerate a blog post using AI (internal) - GET
/api/v1/internal/businesses/{business_id}/blog/learningsWriter learnings ledger for a business (internal, debugging only)
Blog workflow engine
Consumer auth
- POST
/api/v1/internal/consumer-auth/completeComplete - POST
/api/v1/internal/consumer-auth/phone-entryPhone Entry - GET
/api/v1/internal/consumer-auth/prefillPrefill - POST
/api/v1/internal/consumer-auth/resolve-api-keyResolve Api Key - GET
/api/v1/internal/consumers/{consumer_id}/portal-profileConsumer Portal Profile
Contacts
- GET
/api/v1/internal/businesses/{business_id}/contactsList contacts - POST
/api/v1/internal/businesses/{business_id}/contactsCreate contact - GET
/api/v1/internal/businesses/{business_id}/contacts/{contact_id}Get contact detail - PATCH
/api/v1/internal/businesses/{business_id}/contacts/{contact_id}Update contact - DELETE
/api/v1/internal/businesses/{business_id}/contacts/{contact_id}Delete contact - PATCH
/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/classificationOverride contact classification - GET
/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/classification-historyGet classification history - POST
/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/classifyManually classify a contact (legacy POST alias) - GET
/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/conversationGet this contact's conversation - GET
/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/emailsList contact emails - POST
/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/emailsAdd email to contact - PATCH
/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/emails/{email_id}Update contact email - DELETE
/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/emails/{email_id}Remove email from contact - POST
/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/emails/{email_id}/set-primarySet primary email - GET
/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/insightsList contact insights - GET
/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/insights/{insight_id}Get a contact insight - POST
/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/insights/{insight_id}/dismissDismiss a contact insight - DELETE
/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/needs-attentionResolve contact needs-attention overlay - POST
/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/opt-inRecord opt-in - POST
/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/opt-outRecord opt-out - GET
/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/phonesList contact phones - POST
/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/phonesAdd phone to contact - PATCH
/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/phones/{phone_id}Update contact phone - DELETE
/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/phones/{phone_id}Remove phone from contact - POST
/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/phones/{phone_id}/set-primarySet primary phone - GET
/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/preferencesGet preferences - POST
/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/reassessTrigger a fresh AI classification pass - GET
/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/score-historyGet engagement score history - GET
/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/sourcesList sources - POST
/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/sourcesAdd source - GET
/api/v1/internal/businesses/{business_id}/contacts/exportExport contacts as CSV - POST
/api/v1/internal/businesses/{business_id}/contacts/lookupLookup contact by email/phone - POST
/api/v1/internal/businesses/{business_id}/contacts/mergeMerge contacts - GET
/api/v1/internal/businesses/{business_id}/contacts/needs-attentionList contacts needing attention - GET
/api/v1/internal/businesses/{business_id}/contacts/pipeline-summaryGet pipeline summary - GET
/api/v1/internal/businesses/{business_id}/contacts/searchSearch contacts - GET
/api/v1/internal/businesses/{business_id}/contacts/statsGet classification stats - PUT
/api/v1/internal/businesses/{business_id}/contacts/upsertUpsert contact - GET
/api/v1/internal/businesses/{business_id}/duplicate-reviewsList duplicate reviews - GET
/api/v1/internal/businesses/{business_id}/duplicate-reviews/{review_id}Get duplicate review - POST
/api/v1/internal/businesses/{business_id}/duplicate-reviews/{review_id}/dismissDismiss duplicate pair - POST
/api/v1/internal/businesses/{business_id}/duplicate-reviews/{review_id}/mergeMerge duplicate pair - GET
/api/v1/internal/businesses/{business_id}/identity-reviewsList identity reviews - GET
/api/v1/internal/businesses/{business_id}/identity-reviews/{review_id}Get identity review - POST
/api/v1/internal/businesses/{business_id}/identity-reviews/{review_id}/resolveResolve identity review
Data models
Follow ups
Import data
Media
- GET
/api/v1/internal/media/businessesBusinesses with >=1 live photo — media-service bulk-backfill enumeration (internal) - GET
/api/v1/internal/media/businesses/{business_id}/members/{user_id}Is this heimdal user a member of this business? — media-service tenant check (internal) - GET
/api/v1/internal/media/galleryPaged industry-gallery list for the media-service industry sweep (internal) - GET
/api/v1/internal/media/gallery/{photo_id}/bytesStream one industry-gallery photo's blob (internal) - GET
/api/v1/internal/media/photosPaged photo list for media-service ingest/backfill/sweep (internal) - GET
/api/v1/internal/media/photos/{photo_id}/bytesStream one photo's blob (internal); 410 when an external URL expired - GET
/api/v1/internal/media/photos/{photo_id}/usagesDelete-guard cross-check: modules referencing this photo (internal) - POST
/api/v1/internal/media/photos/import-derivativeWrite an edited image back as a first-class derived photo (internal)
Notifications
Onboarding
- POST
/api/v1/internal/workflow-engine/onboarding/crawl-attempts/{attempt_id}/assetsIngest Assets - POST
/api/v1/internal/workflow-engine/onboarding/crawl-attempts/{attempt_id}/classifyClassify Crawl Pages - POST
/api/v1/internal/workflow-engine/onboarding/crawl-attempts/{attempt_id}/completeComplete Crawl - POST
/api/v1/internal/workflow-engine/onboarding/crawl-attempts/{attempt_id}/extract-blog-postExtract Blog Post Fragment - POST
/api/v1/internal/workflow-engine/onboarding/crawl-attempts/{attempt_id}/extract-domainExtract Domain Fragment - POST
/api/v1/internal/workflow-engine/onboarding/crawl-attempts/{attempt_id}/extract-findingsExtract Findings - GET
/api/v1/internal/workflow-engine/onboarding/crawl-attempts/{attempt_id}/fetched-urlsFetched Urls - POST
/api/v1/internal/workflow-engine/onboarding/crawl-attempts/{attempt_id}/heartbeatHeartbeat Crawl Attempt - GET
/api/v1/internal/workflow-engine/onboarding/crawl-attempts/{attempt_id}/pagesList Pages - POST
/api/v1/internal/workflow-engine/onboarding/crawl-attempts/{attempt_id}/pagesIngest Pages - PATCH
/api/v1/internal/workflow-engine/onboarding/photos/tagsUpdate Photo Tags - POST
/api/v1/internal/workflow-engine/onboarding/runs/{run_id}/assembleAssemble Run Payload - POST
/api/v1/internal/workflow-engine/onboarding/runs/{run_id}/categorise-imagesCategorise Run Images - POST
/api/v1/internal/workflow-engine/onboarding/runs/{run_id}/crawl-attemptsCreate Crawl Attempt - POST
/api/v1/internal/workflow-engine/onboarding/runs/{run_id}/enrichEnrich Run - POST
/api/v1/internal/workflow-engine/onboarding/runs/{run_id}/mergeMerge Run - GET
/api/v1/internal/workflow-engine/onboarding/runs/{run_id}/photosList Run Photos - GET
/api/v1/internal/workflow-engine/onboarding/runs/{run_id}/sor-stateGet Sor State - POST
/api/v1/internal/workflow-engine/onboarding/runs/{run_id}/stage-statusRecord Stage Status - POST
/api/v1/internal/workflow-engine/onboarding/runs/{run_id}/stages/{stage}Run Stage - POST
/api/v1/internal/workflow-engine/onboarding/runs/{run_id}/website-photos/auto-assignAuto Assign Website Photos
Platform admin invites
Portal
Scheduler tick
Social posts
- POST
/api/v1/internal/businesses/{business_id}/social_postsCreate a social post draft (internal) - GET
/api/v1/internal/businesses/{business_id}/social_posts/{social_post_id}Get a social post (internal) - PATCH
/api/v1/internal/businesses/{business_id}/social_posts/{social_post_id}Update a social post draft (internal) - POST
/api/v1/internal/businesses/{business_id}/social_posts/{social_post_id}/publishPublish a social post immediately (internal) - POST
/api/v1/internal/businesses/{business_id}/social_posts/generateGenerate social post caption (internal)
Social posts
Social workflow engine
Website agent attachments
Website generation
Website modification agent data
Website modifications
- GET
/api/v1/internal/businesses/{business_id}/website-mod/check-gateGet Website Mod Check Gate - GET
/api/v1/internal/businesses/{business_id}/website-mod/contextGet Website Mod Context - GET
/api/v1/internal/businesses/{business_id}/website-mod/pending-changesGet Pending Website Mod Changes - POST
/api/v1/internal/businesses/{business_id}/website-mod/requirements/textsPost Website Mod Requirement Texts - POST
/api/v1/internal/website-mod/agent-callbackPost Website Mod Agent Callback - POST
/api/v1/internal/website-mod/agent-progressPost Website Mod Agent Progress - POST
/api/v1/internal/website-mod/check-artifactsPost Website Mod Check Artifact - POST
/api/v1/internal/website-mod/deploy-reconcilePost Website Mod Deploy Reconcile - POST
/api/v1/internal/workflow-engine/website-mod/cancel-pendingPost Cancel Pending Website Mod - POST
/api/v1/internal/workflow-engine/website-mod/deploy-statusPost Deploy Status - POST
/api/v1/internal/workflow-engine/website-mod/gate-statusPost Website Mod Gate Status - POST
/api/v1/internal/workflow-engine/website-mod/merge-deployPost Merge Deploy - POST
/api/v1/internal/workflow-engine/website-mod/plan-and-open-prPost Plan And Open Pr - POST
/api/v1/internal/workflow-engine/website-mod/preview-statusPost Preview Status - POST
/api/v1/internal/workflow-engine/website-mod/reconcile-pendingPost Website Mod Reconcile Pending - POST
/api/v1/internal/workflow-engine/website-mod/repo-lock/acquirePost Acquire Repo Lock - POST
/api/v1/internal/workflow-engine/website-mod/repo-lock/releasePost Release Repo Lock
Website preview
Website preview runs
- POST
/api/v1/internal/website-preview/agent-callbackPost Website Preview Agent Callback - POST
/api/v1/internal/website-preview/agent-progressPost Website Preview Agent Progress - POST
/api/v1/internal/website-preview/check-artifactsPost Website Preview Check Artifact - POST
/api/v1/internal/workflow-engine/website-preview/runs/failPost Preview Run Fail - POST
/api/v1/internal/workflow-engine/website-preview/runs/settlePost Preview Run Settle - POST
/api/v1/internal/workflow-engine/website-preview/runs/startPost Preview Run Start - POST
/api/v1/internal/workflow-engine/website-preview/runs/statusPost Preview Run Status