FLfloqer
ackDB

Declare a custom source

Declares a new custom source definition at runtime. A source declared here is INDISTINGUISHABLE from a shipped pack: it flows through the same DB tables, so ingest, discovery, agent guidance, contact extraction, and embedding all treat it identically.

eventTypeField is REQUIRED (no static single-event sources) and identityLinkTypes MUST include domain so the source can resolve to or create entities. Default trait keys MUST be namespaced as <sourceType>_*. Use ?dryRun=true to validate the payload without persisting anything.

post/api/v1/ackdb/schemas/sources

Request

  • Base URL
    http://localhost:3009
  • Auth
    HTTP bearer

Query parameters

dryRunboolean

Validate without persisting. Returns 200 with { valid: true, dryRun: true, ... }.

Request body

sourceTypestring required

Lowercase source identifier (e.g. app_usage).

displayNamestring required

Human-readable name.

descriptionstring required

What data this source carries.

versionstring

Optional source version string.

queryingGuidestring

Optional agent-facing guidance on how to query this source's events.

identityLinkTypesstring[] required

May be empty when every declared event is person_only and allowCustomEventTypes is false. Otherwise must include domain. Add domain before adding company event types or allowing custom types.

eventTypeFieldstring required

REQUIRED. Which content.metadata field determines the event type.

eventTypePrefixstring required

Namespace prefix for event types.

defaultContentNature'conversational' | 'structured' | 'activity-signal'

Optional default content nature applied to events that don't specify one.

allowCustomEventTypesboolean

Optional HubSpot-custom-objects escape hatch: accept unknown event types and skip per-event validation.

contextOnlyboolean

This source's events describe a PERSON but anchor to a company (job → the employer, education → the school), so the entities it mints are context rather than accounts (#493). A company whose only ingested evidence comes from such sources is hidden from the Companies grain and excluded from every score population. NULLABLE: null means never-decided and lets the pack loader seed it; true/false is a decision the loader will not overwrite.

Example request

{
  "sourceType": "app_usage",
  "displayName": "App Usage",
  "identityLinkTypes": [
    "domain",
    "app_account_id"
  ],
  "eventTypeField": "event_type",
  "eventTypePrefix": "app_usage_",
  "defaultTraits": [
    {
      "traitKey": "app_usage_dau",
      "valueType": "number"
    }
  ]
}

Response

Dry-run validation succeeded (nothing persisted)

Changes

No recorded changes to this operation across all 1 revision of this API.