Learnings#

Keep what a team decided, assumed, worried about and learned on each campaign, so the next campaign can start from it.

Authentication required

All endpoints require a Bearer token in the Authorization header. See the Authentication guide for setup instructions.

GET /v1/learnings#

List one campaign's learnings: its decisions, rationale, assumptions, risks, lessons and recommendations for next time.

bash

GET /v1/learnings?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&campaign_id=3a8d1f56-9e42-4b7c-a1d8-6f0e2b9c4a03
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
campaignId	`string (UUID)`	Required	Unique identifier (UUID v4).

Response#

Returns { items, totalCount, facets, _meta } with paginated results.

GET /v1/learnings/search#

Search learnings across every campaign in the workspace by text and type, so a past lesson or decision turns up without knowing which campaign it came from.

bash

GET /v1/learnings/search?page_index=0&page_size=25&workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
pageIndex	`integer`	Required	Zero-based page index for pagination.
pageSize	`integer`	Required	Number of items per page (1-100).
workspaceId	`string (UUID)`	Required	Workspace identifier.
searchTerm	`string`	—	Free-text term matched against learning titles and wording.
learningTypes	`Array<'decision' \| 'rationale' \| 'hypothesis' \| 'assumption' \| 'creative_strategy' \| 'agency_recommendation' \| 'impact_mechanism' \| 'risk' \| 'constraint' \| 'lesson' \| 'future_recommendation'>`	—	Restrict results to these learning types. Defaults to every type.
campaignId	`string (UUID)`	—	Restrict results to one campaign, for example to re-read its own history.
excludeCampaignId	`string (UUID)`	—	Omit one campaign, so the current campaign does not crowd out past learnings.

Response#

Returns { items, totalCount, facets, _meta } with paginated results.

GET /v1/learnings/:id#

Get one learning with who recorded it, the original author and date, its current revision number, and the other learnings or source files it references.

bash

GET /v1/learnings/:id
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	Unique identifier (UUID v4).

Response#

Returns { data, _meta } with the result.

GET /v1/learnings/:id/revisions#

List every revision of one learning, including changes to its type, title, wording, attribution and references, so a correction can be told apart from the original wording.

bash

GET /v1/learnings/:id/revisions
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	Unique identifier (UUID v4).

Response#

Returns { items, totalCount, facets, _meta } with paginated results.

POST /v1/learnings#

Record a learning on a campaign: its type (decision, rationale, assumption, risk, lesson and others), a title and the wording. It can also carry the original author and date, and the past learnings or source files it was based on.

bash

POST /v1/learnings
Authorization: Bearer {token}
Content-Type: application/json

{
  "workspace_id": "1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01",
  "campaign_id": "3a8d1f56-9e42-4b7c-a1d8-6f0e2b9c4a03",
  "learning_type": "...",
  "title": "...",
  "content": "Note content here."
}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
campaignId	`string (UUID)`	Required	Unique identifier (UUID v4).
learningType	`'decision' \| 'rationale' \| 'hypothesis' \| 'assumption' \| 'creative_strategy' \| 'agency_recommendation' \| 'impact_mechanism' \| 'risk' \| 'constraint' \| 'lesson' \| 'future_recommendation'`	Required	The type of learning: decision, rationale, hypothesis, assumption, creative_strategy, agency_recommendation, impact_mechanism, risk, constraint, lesson, or future_recommendation.
title	`string`	Required	One-line summary of the learning.
content	`string`	Required	Full wording of the decision, reasoning, risk or lesson.
authorName	`string \| null`	—	Who originally wrote it, when that differs from the user recording it.
authoredAt	`string \| null`	—	Date (YYYY-MM-DD) it was originally written, when known.
references	`Array<unknown>`	—	Past learnings or attached source files this learning was based on. A reference to a learning may pin the exact revision that was read.

Response#

Returns { data, _meta } with the result.

PATCH /v1/learnings/:id#

Update the title, wording, type, author, authored date or references of one learning, recorded as a new revision. Pass expectedRevisionNumber to get a conflict back instead of overwriting a change someone else saved first.

bash

PATCH /v1/learnings/:id
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
learningType	`'decision' \| 'rationale' \| 'hypothesis' \| 'assumption' \| 'creative_strategy' \| 'agency_recommendation' \| 'impact_mechanism' \| 'risk' \| 'constraint' \| 'lesson' \| 'future_recommendation'`	—	The type of learning: decision, rationale, hypothesis, assumption, creative_strategy, agency_recommendation, impact_mechanism, risk, constraint, lesson, or future_recommendation.
title	`string`	—	One-line summary of the learning.
content	`string`	—	Full wording of the decision, reasoning, risk or lesson.
authorName	`string \| null`	—	Who originally wrote it, when that differs from the user recording it.
authoredAt	`string \| null`	—	Date (YYYY-MM-DD) it was originally written, when known.
references	`Array<unknown>`	—	Past learnings or attached source files this learning was based on. A reference to a learning may pin the exact revision that was read.
id	`string (UUID)`	Required	Unique identifier (UUID v4).
expectedRevisionNumber	`integer`	—

Response#

Returns { data, _meta } with the result.

DELETE /v1/learnings/:id#

Delete one learning. It is soft deleted and keeps its revision history.

bash

DELETE /v1/learnings/:id
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	Unique identifier (UUID v4).

Response#

Returns { data, _meta } with the result.