Skip to main content
GET
List / search themes

Authorizations

X-API-Key
string
header
required

Team-scoped API key created in the app (Settings → API Keys). Sent as X-API-Key: <key> on every request. The header name apikey is also accepted as an alias.

Query Parameters

show_all
boolean
default:false

Has no effect; kept for compatibility.

q
string

Search text. Required when search_mode is semantic.

Maximum string length: 500
search_mode
enum<string>
default:lexical

lexical matches text (default); semantic matches by meaning.

Available options:
lexical,
semantic
min_similarity
number<float>
default:0.5

How close a semantic match must be, from 0.3 to 1. Semantic search only.

Required range: 0.3 <= x <= 1
allow_fallback
boolean
default:false

Fall back to text search when semantic search is unavailable. Semantic search only.

include_retired
boolean
default:false

Has no effect; kept for compatibility.

status
enum<string>

Return themes with this status. Omit it for open themes.

Available options:
active,
new,
reviewing,
planned,
in_progress,
parked,
shipped,
declined
sort
enum<string>
default:ric_score
Available options:
ric_score,
insight_count,
unique_customer_count,
created_at
product_id
string<uuid>[]

Themes with an open need in any of these products from /products. Up to 50 IDs, comma-separated or repeated.

Maximum array length: 50
product_feature_id
string<uuid>

The theme that holds this feature from /features.

product_area_id
string<uuid>[]

Themes with an open need in any of these product areas from /areas. Up to 50 IDs, comma-separated or repeated.

Maximum array length: 50
feature_area_id
string<uuid>[]

Themes with an open need in any of these feature areas from /areas. Up to 50 IDs, comma-separated or repeated.

Maximum array length: 50
date_from
string<date>

Themes created on or after this date, YYYY-MM-DD. Other formats return 400.

Pattern: ^\d{4}-\d{2}-\d{2}$
date_to
string<date>

Themes created on or before this date (inclusive), YYYY-MM-DD. Other formats return 400.

Pattern: ^\d{4}-\d{2}-\d{2}$
limit
integer
default:50

Page size (max 200).

Required range: 1 <= x <= 200
offset
integer
default:0

Number of records to skip.

Required range: x >= 0

Response

A page of themes

data
object[]
required
pagination
object
required
search_mode
enum<string>
required

The search that ran.

Available options:
lexical,
semantic
min_similarity
number<float> | null
required

The similarity cutoff used, or null for a text search.