Beliefs API

Manage growth beliefs and update their confidence levels with Bayesian evidence. All endpoints require authentication.

List Beliefs

GET/api/beliefs

Retrieve all beliefs for the current project

curl https://your-instance.com/api/beliefs \ -H "x-api-key: apex_key_abc123"

Returns an array of belief objects:

[
  {
    "id": "bel_001",
    "statement": "Social proof on pricing increases conversion by 15%",
    "confidence": 0.72,
    "evidence": [
      { "type": "experiment", "experimentId": "exp_abc", "delta": 0.22, "timestamp": "2025-01-20T12:00:00Z" }
    ],
    "createdAt": "2025-01-01T10:00:00Z",
    "updatedAt": "2025-01-20T12:00:00Z"
  }
]

Create Belief

POST/api/beliefs

Create a new growth belief

Parameter	Type	Description
`statement`required	`string`	The belief hypothesis (e.g. 'Video testimonials increase demo requests')
`confidence`	`number`	Initial confidence level between 0 and 1. Defaults to 0.5 (maximum uncertainty).
`tags`	`array`	Optional tags for categorization (e.g. ['pricing', 'social-proof'])

curl -X POST https://your-instance.com/api/beliefs \ -H "Content-Type: application/json" \ -H "x-api-key: apex_key_abc123" \ -d '{ "statement": "Adding customer logos to the homepage increases signups", "confidence": 0.5, "tags": ["homepage", "social-proof"] }'

Tip

Start beliefs at 0.5 confidence (the default) unless you have strong prior evidence. This represents maximum uncertainty and lets experiment data drive the confidence in either direction.

Update Confidence

POST/api/beliefs/:id/update-confidence

Apply a Bayesian confidence update based on new evidence

Submit evidence from an experiment or observation to shift a belief's confidence level. The update uses Bayesian inference — supporting evidence pushes confidence toward 1, contradicting evidence pushes it toward 0.

Parameter	Type	Description
`id`required	`string`	Belief ID (path parameter)
`type`required	`string`	Evidence type: experiment, observation, or external
`experimentId`	`string`	Linked experiment ID (when type is experiment)
`delta`required	`number`	Observed effect size. Positive values support the belief; negative values weaken it.
`sampleSize`	`number`	Number of observations. Larger samples produce stronger updates.

curl -X POST https://your-instance.com/api/beliefs/bel_001/update-confidence \ -H "Content-Type: application/json" \ -H "x-api-key: apex_key_abc123" \ -d '{ "type": "experiment", "experimentId": "exp_abc", "delta": 0.18, "sampleSize": 4200 }'

Returns the updated belief with the new confidence value and appended evidence entry.