Skip to content
Retidal Docs

Create/update the growth definition (ADMIN)

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
projectId
required
string

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Validated by growthDefinitionPayloadSchema (@/lib/growth-definition). Includes status, templateType, defaultAnalysisSubject, analysisSubjectKey, northStarMetric, aarrrStages, defaultFunnel, defaultRetention. status “PUBLISHED” stamps publishedAt.

object
key
additional properties
any
Examplegenerated
json
{}

Responses

Section titled “Responses”

200

Section titled “200”

{ definition }. Some keys are dynamic — 200 body is exactly {definition: }. definition is typed DashboardGrowthDefinitionRecord | null because the repository re-reads after upsert (dashboard-growth-definitions.ts:128), so null is reachable in principle; in practice a successful upsert returns the row. Same JSON-column caveats and timestamp formats as growthGetDefinition. publishedAt is set to new Date().toISOString() when status == “PUBLISHED”, otherwise explicitly null. Error bodies: 400 {error: “增长定义配置无效”, issues: }; 500 {error: “保存增长定义失败”} (no detail field on this route).

Media typeapplication/json
object
definition
required

Same shape as growthGetDefinition.definition.

object
id
required
string
projectId
required
string
status
required
string
Allowed values: DRAFT PUBLISHED
templateType
required
string
Allowed values: CUSTOM B2B_SAAS CONTENT ECOMMERCE
defaultAnalysisSubject
required
string
Allowed values: EVENT SESSION VISITOR IDENTIFIED_USER ACCOUNT
analysisSubjectKey
required

Must match /^properties(.[a-zA-Z0-9_]+)+$/ when set.

string
nullable
northStarMetric
required

Free-form JSON column; not validated on write beyond “object or null”. Shape written by this app: {label: string, aggregation: “count”|“sum”, scope: GrowthAnalysisSubject, eventName: string|null, propertyPath: string|null}.

object
key
additional properties
any
aarrrStages
required

Exactly 5 stages when written through PUT (stageSchema.length(5)).

Array<object>
object
key
string
Allowed values: acquisition activation retention revenue referral
label
string
<= 40 characters
description
string
<= 200 characters
successEvents
Array<string>
<= 10 items
conversionWindowDays
integer
nullable >= 1 <= 365
defaultBreakdowns
Array<string>
<= 5 items
key
additional properties
any
defaultFunnel
required

Free-form JSON column. Shape written by this app: {scope: GrowthAnalysisSubject, windowHours: number, steps: string[]}.

object
key
additional properties
any
defaultRetention
required

Free-form JSON column. Shape written by this app: {scope: GrowthAnalysisSubject, startEvent: string|null, returnEvent: string|null, granularity: “day”|“week”|“month”}.

object
key
additional properties
any
publishedAt
required

ISO-8601 with milliseconds and Z, or null.

string
nullable
createdAt
required

SQLite CURRENT_TIMESTAMP text: ‘YYYY-MM-DD HH:MM:SS’ (UTC).

string
updatedAt
required

SQLite CURRENT_TIMESTAMP text: ‘YYYY-MM-DD HH:MM:SS’ (UTC).

string

400

Section titled “400”

Invalid definition.

Media typeapplication/json

Validation error envelope (Zod). issues/details present on schema failures.

object
error
required
string
issues
Array<object>
object
key
additional properties
any
details
Array<object>
object
key
additional properties
any
Examplegenerated
json
{
  "error": "example",
  "issues": [
    {}
  ],
  "details": [
    {}
  ]
}

500

Section titled “500”

Save failed.

Media typeapplication/json
object
error
required

Human-readable error message.

string
message
string
Examplegenerated
json
{
  "error": "example",
  "message": "example"
}