FLfloqer
ackDB

Replace a score definition's config

Full replace of the mutable fields (name, description, groups, criteria, normalization, labels, isPrimary, enabled). scoreKey and grain are immutable. Disabling a previously-enabled definition removes its columns and transactionally scrubs referencing saved segments (the response's scrubbedSegments reports how many). Any successful edit clears degraded.

put/api/v1/ackdb/scores/{scoreKey}

Request

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

Path parameters

scoreKeystring required

The score definition's slug (immutable after create).

Query parameters

grain'company' | 'person'

Disambiguates a scoreKey that exists on both grains (400 without it in that case).

Request body

scoreKeystring required

Immutable slug → the sc__<scoreKey> column. Single underscores only.

namestring required
descriptionstring nullable
grain'company' | 'person' required

Immutable after create.

normalization'absolute' | 'percentile'

absolute (default): 100 × points / max possible, clamped. percentile: rank within THIS grain's population (strictly-below semantics — a no-data row is the 0th percentile).

percentilePopulation'all' | 'active'

Percentile definitions only (#432) — 400 with absolute normalization. all (default): rank against the whole grain population (today's behavior). active: rank only against rows where at least one non-trait criterion fired (an event:/convergence/contacts/company: criterion contributed nonzero points) — on sparse books the empty rows stop being the yardstick. Excluded rows still serve a score of 0 (never NULL) and take whatever lt label band covers 0.

scopeSegmentIdstring nullable

SCOPE (#443): score ONLY the members of this saved segment. Absent/null = the whole grain (every definition before this feature). Rows outside the segment read NULL in sc__<key> and sc__<key>__label — not 0 — and are excluded from the percentile population, the preview histogram and the history sweep. ANY segment grain is legal for either score grain: a contact/person segment scoping a company score means 'the companies of those people', a company segment scoping a person score means 'the people with an active edge at those companies'. Derived segments are legal. 400s when the segment does not exist, or when its filter (or its base's) references a SCOPED score — a scored population may only be defined by whole-grain scores, which is what makes a scoring cycle impossible.

isPrimaryboolean

One primary per grain (server-enforced hand-off).

enabledboolean

Example request

{
  "scoreKey": "pql",
  "name": "PQL score",
  "groups": [
    {
      "key": "fit",
      "weight": 0.4
    }
  ],
  "criteria": [
    {
      "field": "event:slack.message",
      "valueField": "employee_count"
    }
  ],
  "labels": [
    {
      "label": "Excellent"
    }
  ]
}

Response

The updated definition (+ scrubbedSegments).

scoreKeystring required

Immutable slug → the sc__<scoreKey> column. Single underscores only.

namestring required
descriptionstring nullable
grain'company' | 'person' required

Immutable after create.

normalization'absolute' | 'percentile'

absolute (default): 100 × points / max possible, clamped. percentile: rank within THIS grain's population (strictly-below semantics — a no-data row is the 0th percentile).

percentilePopulation'all' | 'active'

Percentile definitions only (#432) — 400 with absolute normalization. all (default): rank against the whole grain population (today's behavior). active: rank only against rows where at least one non-trait criterion fired (an event:/convergence/contacts/company: criterion contributed nonzero points) — on sparse books the empty rows stop being the yardstick. Excluded rows still serve a score of 0 (never NULL) and take whatever lt label band covers 0.

scopeSegmentIdstring nullable

SCOPE (#443): score ONLY the members of this saved segment. Absent/null = the whole grain (every definition before this feature). Rows outside the segment read NULL in sc__<key> and sc__<key>__label — not 0 — and are excluded from the percentile population, the preview histogram and the history sweep. ANY segment grain is legal for either score grain: a contact/person segment scoping a company score means 'the companies of those people', a company segment scoping a person score means 'the people with an active edge at those companies'. Derived segments are legal. 400s when the segment does not exist, or when its filter (or its base's) references a SCOPED score — a scored population may only be defined by whole-grain scores, which is what makes a scoring cycle impossible.

isPrimaryboolean

One primary per grain (server-enforced hand-off).

enabledboolean
degradedboolean

True when a source deletion scrubbed criteria out of this definition, or (#443) when its scope segment was deleted (the definition is also disabled) or widened by a scrub. Any successful edit clears it.

scopeSegmentNamestring nullable

Scope segment display name, hydrated on reads (#443). Null when the definition is unscoped OR its scope segment has been deleted — a non-null scopeSegmentId with a null name is the dangling-scope state (the definition is disabled + degraded).

scopeSegmentKind'company' | 'contact' | 'person' nullable

Scope segment home grain, hydrated on reads (#443). Null when unscoped/dangling.

createdAtstring date-time
updatedAtstring date-time

Example response

{
  "scoreKey": "pql",
  "name": "PQL score",
  "groups": [
    {
      "key": "fit",
      "weight": 0.4
    }
  ],
  "criteria": [
    {
      "field": "event:slack.message",
      "valueField": "employee_count"
    }
  ],
  "labels": [
    {
      "label": "Excellent"
    }
  ]
}

Changes

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