Learn which Public API endpoints are available, what they return, and how pagination works.

Resource Reference

This page documents the human-readable shape of the v1 Deck Public API. The machine-readable contract is available from the OpenAPI endpoint.

Endpoint summary

Method	Path	Description	Pagination
`GET`	`/openapi`	OpenAPI 3.1 specification	none
`GET`	`/me`	Verify the key and inspect resolved identity	none
`GET`	`/themes`	List themes	cursor
`GET`	`/themes/{themeId}`	Get a theme by ID	none
`GET`	`/insights`	List insights	cursor
`GET`	`/insights/{insightId}`	Get an insight by ID	none
`GET`	`/initiatives`	List initiatives	cursor
`GET`	`/initiatives/{initiativeId}`	Get an initiative by ID	none
`POST`	`/build/initiatives`	Execute one initiative build mutation	none
`POST`	`/build/opportunities`	Execute one opportunity build mutation	none
`GET`	`/subthemes`	List subthemes	offset
`GET`	`/subthemes/{subthemeId}`	Get a subtheme by ID	none

`/me`

Use this endpoint to confirm that your key works and see the identity Deck resolved from it.

Response fields

Field	Meaning
`org_id`	The authenticated organization
`user_id`	The key owner
`role`	The key owner’s current role
`scope`	The authorized scope for this endpoint (`read` for `/me`)

`/themes`

Lists themes for the authenticated organization.

Query parameters

Parameter	Type	Notes
`limit`	integer	default `50`, max `100`
`cursor`	string	opaque pagination cursor

Theme fields

Field	Meaning
`id`	Theme ID
`name`	Theme name
`color`	Theme color
`notes`	Optional notes
`insight_count`	Number of linked insights
`created_at`	Creation timestamp
`updated_at`	Last update timestamp

`/insights`

Lists insights for the authenticated organization.

Query parameters

Parameter	Type	Notes
`limit`	integer	default `50`, max `100`
`cursor`	string	opaque pagination cursor
`theme_id`	string	filter to a specific theme
`sentiment`	string	`POSITIVE`, `NEGATIVE`, `NEUTRAL`
`category`	string	category filter

Supported categories

PAIN_POINTS
DELIGHTS
GENERAL_FEEDBACK
FEATURE_REQUESTS
USABILITY_ISSUES
BUGS_AND_ERRORS

Insight list fields

Field	Meaning
`id`	Insight ID
`name`	Insight title
`sentiment`	Sentiment classification
`category`	Insight category
`quote`	Representative customer quote
`themes`	Linked theme references
`created_at`	Creation timestamp
`updated_at`	Last update timestamp

`/insights/{insightId}`

Returns a single insight with richer source metadata.

Additional fields include:

feedback_id
contact_id
user_email
user_name
interview_date

`/initiatives`

Lists initiatives for the authenticated organization.

Query parameters

Parameter	Type	Notes
`limit`	integer	default `50`, max `100`
`cursor`	string	opaque pagination cursor
`status`	string	initiative lifecycle status

Supported statuses

draft
exploring
building
ready_to_act
completed
archived

Initiative fields

Field	Meaning
`id`	Initiative ID
`title`	Initiative title
`slug`	URL slug
`description`	Optional short summary
`goal`	Optional goal statement
`status`	Initiative status
`leveraged_insights_count`	Number of linked insights
`created_at`	Creation timestamp
`updated_at`	Last update timestamp

`/initiatives/{initiativeId}`

Returns a single initiative plus structured content sections.

Additional fields:

sections
last_generated_at

Each section includes:

key
content
updated_at

Build write surfaces

Build writes are action-based and strictly bounded.

Required on every mutation:

Idempotency-Key header (1-128 chars)
one action payload per request
org policy that allows write scope for the key owner

Explicit non-goals:

backlog generation endpoints
story generation endpoints
arbitrary delete endpoints

`/build/initiatives`

Executes one initiative mutation action.

Supported actions

Action	Required fields	Optional fields
`create`	`title`	`goal`, `owner_id`
`update_title`	`initiative_id`, `title`	none
`update_goal`	`initiative_id`, `goal`	none
`update_status`	`initiative_id`, `status`	none
`upsert_section`	`initiative_id`, `section_type`, `content`	`metadata`
`set_segments`	`initiative_id`, `segment_ids`	none

`/build/opportunities`

Executes one opportunity mutation action.

Supported actions

Action	Required fields	Optional fields
`archive`	`opportunity_id`	none
`set_segments`	`opportunity_id`, `segment_ids`	none
`link_initiative`	`opportunity_id`, `initiative_id`	none
`create_initiative_from_opportunity`	`opportunity_id`, `title`	`goal`, `owner_id`

Idempotency behavior

Same key + same normalized payload returns the original response with idempotency.replayed=true
Same key + different payload returns 409 IDEMPOTENCY_CONFLICT
Reusing the same key while the original matching request is still running also returns 409 IDEMPOTENCY_CONFLICT

`/subthemes`

Lists subthemes synthesized from theme-level or segment-level analysis.

Subthemes are only available to organizations eligible for the subthemes feature.

Query parameters

Parameter	Type	Notes
`limit`	integer	default `50`, max `100`
`offset`	integer	zero-based offset
`theme_id`	string	filter to a specific theme
`segment_id`	string	filter to a specific segment when segments are enabled
`q`	string	case-insensitive search against pattern name or description

Subtheme fields

Field	Meaning
`id`	Subtheme ID
`name`	Subtheme name
`description`	Subtheme description
`insight_count`	Number of contributing insights
`sentiment_breakdown`	Positive, negative, and neutral counts
`theme_id`	Parent theme ID
`theme_name`	Parent theme name
`theme_color`	Parent theme color
`segment_id`	Segment context when present
`synthesized_at`	Timestamp of the synthesis used

`/subthemes/{subthemeId}`

Returns full synthesized subtheme detail.

Additional fields:

insight_ids
blocks
theme
related_subthemes

Use this endpoint when you need more than the summary list and want the full subtheme context.

Pagination

Cursor pagination

Used by:

themes
insights
initiatives

Response shape:

{
  "pagination": {
    "next_cursor": "opaque-string-or-null",
    "has_more": true
  }
}

Offset pagination

Used by:

subthemes

Response shape:

{
  "pagination": {
    "total": 120,
    "has_more": true,
    "offset": 0,
    "limit": 50
  }
}

OpenAPI spec

The latest API contract is available at:

/api/v1/openapi

Use it when you want the exact field types or need to generate a client.

Resource Reference

On this page