Endpoint reference

Every HTTP endpoint the Inspecta server exposes, generated from the same specification the application itself is built against. 47 operations across 11 groups, all relative to https://getinspecta.com/api.

This is a map of the product, not a developer API. Read the access line on each group before you plan anything around it.

How to read this

Most of these are not callable by you

There are no API keys. Every group marked Dashboard or Admin is authenticated by the signed-in browser session behind the dashboard, and nothing else will get you in. The supported way to move data out of Inspecta is webhooks.

Each group carries a badge: Open needs nothing, Widget transport is what the assessment widget and the report page call from a homeowner's browser, Dashboard needs a signed-in company session, Platform staff needs an Inspecta administrator account, and Mixed means the group holds more than one of those. The badge is a summary; the line underneath it says what actually authenticates each call, which within a group is not always the same thing.

Types name the schema in the specification rather than expanding it, which keeps this page readable at 47 operations. Errors all share the shape described under errors, limits and security.

health

Open

Health operations

No authentication. Used by hosting health checks.

GET/healthz

Health check

Returns server health status

Responses

200HealthyHealthStatus

Storage

Mixed

Object storage upload and serving endpoints.

Requesting an upload URL needs a signed-in dashboard session. The two read routes are unauthenticated: the object path contains a random identifier minted at upload time, and possession of that path is the permission.

POST/storage/uploads/request-url

Request a presigned URL for an authenticated company upload

Returns a presigned GCS URL for direct upload. The client sends JSON metadata here, then uploads the file directly to the returned URL.

Request body

UploadUrlRequestapplication/jsonrequired

Responses

200Presigned upload URL generated.UploadUrlResponse
400Invalid requestErrorEnvelope
401Not authenticatedErrorEnvelope
500Unexpected server errorErrorEnvelope

GET/storage/public-objects/{filePath}

Serve a public asset from PUBLIC_OBJECT_SEARCH_PATHS

Parameters

filePathin pathstringrequired

Responses

200Object content streamed with correct Content-Type.binary
404Not foundErrorEnvelope
500Unexpected server errorErrorEnvelope

GET/storage/objects/{objectPath}

Serve an object entity from PRIVATE_OBJECT_DIR

Parameters

objectPathin pathstringrequired

Responses

200Object content streamed with correct Content-Type.binary
404Not foundErrorEnvelope
500Unexpected server errorErrorEnvelope

Account

Dashboard

Current user and company account operations.

Signed-in dashboard session, resolved from the Clerk session cookie. No API key or token can be issued for these, so they are not callable from outside the dashboard.

GET/me

Get the signed-in user and their company membership state

Responses

200Current userCurrentUser
401Not authenticatedErrorEnvelope

POST/companies

Create the company record from the onboarding wizard

Request body

CompanyOnboardingInputapplication/jsonrequired

Responses

201Company createdCompany
400Invalid requestErrorEnvelope
401Not authenticatedErrorEnvelope
409ConflictErrorEnvelope

Company

Dashboard

Company profile, branding, features, CTA and pricing settings.

Signed-in dashboard session, resolved from the Clerk session cookie. No API key or token can be issued for these, so they are not callable from outside the dashboard.

GET/company

Get the signed-in user's company with branding, features and CTA

Responses

200CompanyCompany
401Not authenticatedErrorEnvelope
404Not foundErrorEnvelope

PATCH/company

Update company profile fields

Request body

CompanyProfileUpdateapplication/jsonrequired

Responses

200Updated companyCompany
400Invalid requestErrorEnvelope
401Not authenticatedErrorEnvelope

PATCH/company/branding

Update logo and brand colors

Request body

CompanyBrandingUpdateapplication/jsonrequired

Responses

200Updated companyCompany
400Invalid requestErrorEnvelope
401Not authenticatedErrorEnvelope

PATCH/company/features

Update the company's service and credential toggles

Request body

CompanyFeaturesUpdateapplication/jsonrequired

Responses

200Updated companyCompany
400Invalid requestErrorEnvelope
401Not authenticatedErrorEnvelope

PATCH/company/cta

Update the primary and secondary call-to-action configuration

Request body

CompanyCtaUpdateapplication/jsonrequired

Responses

200Updated companyCompany
400Invalid requestErrorEnvelope
401Not authenticatedErrorEnvelope

GET/company/pricing

Get the company's remediation pricing rules

Responses

200Pricing rulesPricingRules
401Not authenticatedErrorEnvelope

PATCH/company/pricing

Update the company's remediation pricing rules

Request body

PricingRulesUpdateapplication/jsonrequired

Responses

200Updated pricing rulesPricingRules
400Invalid requestErrorEnvelope
401Not authenticatedErrorEnvelope

DELETE/company/pricing

Reset pricing rules back to the platform defaults

Responses

200Reset pricing rulesPricingRules
401Not authenticatedErrorEnvelope

Widgets

Dashboard

Assessment widget management.

Signed-in dashboard session, resolved from the Clerk session cookie. No API key or token can be issued for these, so they are not callable from outside the dashboard.

GET/widgets

List the company's assessment widgets

Responses

200WidgetsWidget[]
401Not authenticatedErrorEnvelope

POST/widgets

Create an assessment widget

Request body

WidgetInputapplication/jsonrequired

Responses

201Created widgetWidget
400Invalid requestErrorEnvelope
401Not authenticatedErrorEnvelope

GET/widgets/{widgetId}

Get a single widget

Parameters

widgetIdin pathstringrequired

Responses

200WidgetWidget
401Not authenticatedErrorEnvelope
404Not foundErrorEnvelope

PATCH/widgets/{widgetId}

Update a widget

Parameters

widgetIdin pathstringrequired

Request body

WidgetUpdateapplication/jsonrequired

Responses

200Updated widgetWidget
400Invalid requestErrorEnvelope
401Not authenticatedErrorEnvelope
404Not foundErrorEnvelope

DELETE/widgets/{widgetId}

Delete a widget

Parameters

widgetIdin pathstringrequired

Responses

200DeletedOperationResult
401Not authenticatedErrorEnvelope
404Not foundErrorEnvelope

Templates

Open

Predefined assessment templates.

No authentication. The questionnaire definitions are served from here so the widget and the dashboard read the same ones.

GET/assessment-templates

List the three predefined assessment templates

Responses

200TemplatesAssessmentTemplate[]

Leads

Dashboard

Lead pipeline for the authenticated company.

Signed-in dashboard session, resolved from the Clerk session cookie. No API key or token can be issued for these, so they are not callable from outside the dashboard.

GET/leads

List leads for the company

Parameters

statusin queryLeadStatusoptional
concernLevelin queryConcernLeveloptional
widgetIdin querystringoptional
searchin querystringoptional

Responses

200LeadsLeadSummary[]
401Not authenticatedErrorEnvelope

GET/leads/{leadId}

Get the full lead record including report and photos

Parameters

leadIdin pathstringrequired

Responses

200Lead detailLeadDetail
401Not authenticatedErrorEnvelope
404Not foundErrorEnvelope

PATCH/leads/{leadId}

Update lead status and company follow-up fields

Parameters

leadIdin pathstringrequired

Request body

LeadUpdateapplication/jsonrequired

Responses

200Updated leadLeadDetail
400Invalid requestErrorEnvelope
401Not authenticatedErrorEnvelope
404Not foundErrorEnvelope

Dashboard

Company dashboard metrics and activity.

Signed-in dashboard session, resolved from the Clerk session cookie. No API key or token can be issued for these, so they are not callable from outside the dashboard.

GET/dashboard/summary

Headline metrics, breakdowns and recent leads for the company

Responses

200Dashboard summaryDashboardSummary
401Not authenticatedErrorEnvelope

Admin

Platform staff

Platform administrator operations.

Signed-in dashboard session belonging to a platform administrator. Not reachable by a company account.

GET/admin/overview

Platform-wide totals for the SaaS administrator

Responses

200OverviewAdminOverview
401Not authenticatedErrorEnvelope
403Not allowedErrorEnvelope

GET/admin/companies

List every company on the platform with usage counts

Responses

200CompaniesAdminCompany[]
401Not authenticatedErrorEnvelope
403Not allowedErrorEnvelope

GET/admin/ai-errors

Recent AI processing failures across the platform

Responses

200AI processing errorsAiProcessingError[]
401Not authenticatedErrorEnvelope
403Not allowedErrorEnvelope

POST/admin/impersonations

Act inside a company's account to help them with setup

Request body

StartImpersonationRequestapplication/jsonrequired

Responses

201Support session startedImpersonationSession
401Not authenticatedErrorEnvelope
403Not allowedErrorEnvelope
404Not foundErrorEnvelope

DELETE/admin/impersonations/current

Stop acting inside a company's account

Responses

204Support session ended
401Not authenticatedErrorEnvelope

Public

Widget transport

Unauthenticated consumer assessment and report endpoints.

No account and no developer credential. This is what the assessment widget and the report page call from a consumer browser, and what authenticates a call varies within the group. Reads are open: widget configuration is public, and a report is read by possession of its token. Starting an assessment is open as well, and is what mints the per-assessment session token that the answer, photo and lead writes must then present in their body. Engagement events carry no session token and are attributed from the report token instead.

GET/public/widgets/{companySlug}/{widgetSlug}

Load a hosted assessment widget by company and widget slug

Parameters

companySlugin pathstringrequired
widgetSlugin pathstringrequired

Responses

200Public widget payloadPublicWidget
404Not foundErrorEnvelope

GET/public/widgets/by-id/{widgetPublicId}

Load a hosted assessment widget by its public embed id

Parameters

widgetPublicIdin pathstringrequired

Responses

200Public widget payloadPublicWidget
404Not foundErrorEnvelope

POST/public/assessments

Begin a consumer assessment session

Request body

AssessmentStartInputapplication/jsonrequired

Responses

201Assessment sessionAssessmentSession
400Invalid requestErrorEnvelope
404Not foundErrorEnvelope
429Rate limit exceededErrorEnvelope

POST/public/assessments/{assessmentId}/answers

Save questionnaire answers for an in-progress assessment

Parameters

assessmentIdin pathstringrequired

Request body

AssessmentAnswersInputapplication/jsonrequired

Responses

200SavedOperationResult
400Invalid requestErrorEnvelope
403Not allowedErrorEnvelope
404Not foundErrorEnvelope

POST/public/assessments/{assessmentId}/photo-upload-url

Request a presigned upload URL for a consumer assessment photo

Parameters

assessmentIdin pathstringrequired

Request body

AssessmentPhotoUrlInputapplication/jsonrequired

Responses

200Presigned upload URLUploadUrlResponse
400Invalid requestErrorEnvelope
403Not allowedErrorEnvelope
404Not foundErrorEnvelope
429Rate limit exceededErrorEnvelope

POST/public/assessments/{assessmentId}/photos

Parameters

assessmentIdin pathstringrequired

Request body

AssessmentPhotoInputapplication/jsonrequired

Responses

201Registered photoAssessmentPhoto
400Invalid requestErrorEnvelope
403Not allowedErrorEnvelope
404Not foundErrorEnvelope

POST/public/assessments/{assessmentId}/photos/{photoId}/remove

Remove a photo from an in-progress assessment

Parameters

assessmentIdin pathstringrequired
photoIdin pathstringrequired

Request body

AssessmentSessionRefapplication/jsonrequired

Responses

200RemovedOperationResult
403Not allowedErrorEnvelope
404Not foundErrorEnvelope

POST/public/assessments/{assessmentId}/lead

Submit consumer contact details, create the lead and start AI analysis

The lead is persisted synchronously before any AI work begins. AI analysis, pricing and report generation run in the background; poll the report endpoint with the returned token.

Parameters

assessmentIdin pathstringrequired

Request body

LeadCaptureInputapplication/jsonrequired

Responses

200Lead capturedLeadCaptureResult
400Invalid requestErrorEnvelope
403Not allowedErrorEnvelope
404Not foundErrorEnvelope
429Rate limit exceededErrorEnvelope

GET/public/reports/{reportToken}

Fetch a branded consumer report by its secure token

Parameters

reportTokenin pathstringrequired

Responses

200Report envelopeReportEnvelope
404Not foundErrorEnvelope

POST/public/events

Record a consumer-side analytics or CTA event

Request body

AnalyticsEventInputapplication/jsonrequired

Responses

200RecordedOperationResult
400Invalid requestErrorEnvelope

Webhooks

Dashboard

Outbound webhook endpoints the company registers for lead events.

Signed-in dashboard session, resolved from the Clerk session cookie. No API key or token can be issued for these, so they are not callable from outside the dashboard.

GET/company/webhooks

List the company's webhook endpoints

Responses

200Webhook endpointsWebhookEndpointList
401Not authenticatedErrorEnvelope

POST/company/webhooks

Request body

WebhookEndpointCreateapplication/jsonrequired

Responses

201The new endpoint and its signing secret, shown only onceWebhookEndpointWithSecret
400Invalid requestErrorEnvelope
401Not authenticatedErrorEnvelope

PATCH/company/webhooks/{webhookId}

Update a webhook endpoint

Parameters

webhookIdin pathstringrequired

Request body

WebhookEndpointUpdateapplication/jsonrequired

Responses

200Updated endpointWebhookEndpoint
400Invalid requestErrorEnvelope
401Not authenticatedErrorEnvelope
404Not foundErrorEnvelope

DELETE/company/webhooks/{webhookId}

Delete a webhook endpoint

Parameters

webhookIdin pathstringrequired

Responses

204Deleted
401Not authenticatedErrorEnvelope
404Not foundErrorEnvelope

POST/company/webhooks/{webhookId}/test

Send a test event to the endpoint

Parameters

webhookIdin pathstringrequired

Responses

200The test delivery and its outcomeWebhookDelivery
401Not authenticatedErrorEnvelope
404Not foundErrorEnvelope

POST/company/webhooks/{webhookId}/rotate-secret

Replace the signing secret for an endpoint

Parameters

webhookIdin pathstringrequired

Responses

200The endpoint and its new signing secret, shown only onceWebhookEndpointWithSecret
401Not authenticatedErrorEnvelope
404Not foundErrorEnvelope

GET/company/webhooks/{webhookId}/deliveries

Recent delivery attempts for an endpoint

Parameters

webhookIdin pathstringrequired

Responses

200Delivery historyWebhookDeliveryList
401Not authenticatedErrorEnvelope
404Not foundErrorEnvelope

POST/company/webhooks/{webhookId}/deliveries/{deliveryId}/resend

Send a past event to the endpoint again

Parameters

webhookIdin pathstringrequired
deliveryIdin pathstringrequired

Responses

200The delivery after the new attemptWebhookDelivery
400Invalid requestErrorEnvelope
401Not authenticatedErrorEnvelope
404Not foundErrorEnvelope

Version

Generated from specification version 0.1.0 at build time. This page is rebuilt whenever the site is, so it cannot drift from what the server is built against.

Webhooks

Events, exact payloads, signature verification, retries, delivery history and testing.

Errors, limits and security

The error shape, which routes are rate limited, and the rules applied to webhook targets.