List topics

List topics (issues) with filters, message counts, and authors. When embeddingSearch is provided, performs semantic search using vector similarity instead of keyword search. Semantic search finds topics by meaning, useful for queries like “users having trouble with authentication”.

GET/topics

Authorization

AuthorizationBearer token · headerrequired

Organization API key (modem_…).

Query parameters

viewstring

Deprecated and ignored. Topics are always served from the current pipeline, whichever value is sent. Accepted so existing requests keep working; omit it in new integrations.

Allowed:v1v2

searchstring

Keyword search on title (max 100 chars). Wrap in double-quotes for exact token matching (e.g. "persona" matches the whole word and excludes "personal"). Ignored if embeddingSearch is provided.

max length 100

embeddingSearchstring

Semantic search query using vector similarity. When provided, finds topics by meaning instead of keywords. Overrides the search parameter.

min length 1 · max length 1000

minSimilaritynumber

Minimum cosine similarity threshold for embeddingSearch (0-1, higher = more similar). Default 0.7.

min 0 · max 1 · default: 0.7

categoriesstring[]

Filter topics by keywords/categories (OR logic: topic must have ANY of the listed categories). Case-insensitive. For v2 topics a category is a catalog keyword slug (see topics.filterOptions), matched through the topic's open keyword attribution.

excludeCategoriesstring[]

Exclude topics by keywords/categories (OR logic: topic must have NONE of the listed categories). Case-insensitive. For v2 topics a category is a catalog keyword slug.

issueTypesstring[]

excludeIssueTypesstring[]

sourcesstring[]

Filter topics by message sources (OR logic: topic must have messages from ANY listed source). Case-insensitive; duplicates are ignored.

min items 1

excludeSourcesstring[]

Exclude topics by message sources (OR logic: topic must have NO messages from ANY listed source). Case-insensitive; duplicates are ignored.

min items 1

dateRangeobject

Filter topics by time range overlap

sortBystring

Sort order. 'groups' sorts by the number of groups. Use 'similarity' with embeddingSearch for best results.

default: "date"

Allowed:dategroupslifecycleprioritysimilarity

sortOrderstring

default: "desc"

Allowed:ascdesc

prioritiesstring[]

excludePrioritiesstring[]

lifecycleStatesstring[]

Filter topics by lifecycle state. "unknown" also matches topics with no lifecycle assessment.

companiesstring[]

Filter topics by company IDs (OR logic: topic must have messages from people associated with ANY listed company).

excludeCompaniesstring[]

Exclude topics by company IDs (OR logic: topic must have NO messages from people associated with ANY listed company).

productsstring<uuid> | any[]

Filter topics by product IDs (OR logic: topic must have messages in a channel mapped to ANY listed product). Pass "none" to also match topics with no product attribution at all.

excludeProductsstring<uuid> | any[]

Exclude topics by product IDs (OR logic: topic must have NO messages in a channel mapped to ANY listed product). Pass "none" to exclude topics with no product attribution at all.

sourceContainersstring<uuid>[]

Filter topics by source container IDs (OR logic: topic must draw evidence from ANY listed container). v2 only.

min items 1

excludeSourceContainersstring<uuid>[]

Exclude topics by source container IDs (OR logic: topic must draw evidence from NONE of the listed containers). v2 only.

min items 1

personsstring[]

Filter topics by person IDs (OR logic: topic must have messages from ANY listed person).

excludePersonsstring[]

Exclude topics by person IDs (OR logic: topic must have messages from NONE of the listed people).

ticketStatusesstring[]

Filter by linked ticket presence. "has_ticket" = has any linked ticket, "none" = no linked ticket.

excludeTicketStatusesstring[]

Exclude by linked ticket presence. "has_ticket" excludes topics with tickets, "none" excludes topics without tickets.

teamResponsestring[]

Filter by team response status. "not_responded" = no team member replied, "fully_responded" = team replied in all groups, "partially_responded" = team replied in some groups.

pageinteger

default: 1

limitinteger

max 100 · default: 10

Responses

200

dataobject[]required

Show properties

Array of object

authorsobject[]required

Show properties

Array of object

displayNamestring | nullrequired

Optional display name for the author.

Show properties

Any of:

string

string

null

null

idstring<uuid>required

Show properties

Any of:

string<uuid>

string<uuid>

string<uuid>

string<uuid>

isBotbooleanrequired

Whether the author is a bot account.

sourceAuthorIdstringrequired

Author identifier in the source system.

sourceAvatarUrlstring<uri> | nullrequired

Avatar image URL from the source system.

Show properties

Any of:

string<uri>

string<uri>

null

null

sourceNamestringrequired

Source system where the author originates.

matches ^[a-z0-9]+(?:-[a-z0-9]+)*$

eventCountintegerrequired

Number of events grouped under this topic.

idstring<uuid>required

Show properties

Any of:

string<uuid>

string<uuid>

string<uuid>

string<uuid>

issueTypestring | nullrequired

Optional issue classification for the topic.

Show properties

Any of:

string

string

null

null

keywordsstring[]required

Keywords associated with the topic.

lifecycleStatestring | nullrequired

Most recent LLM-assessed lifecycle state for this topic.

Show properties

Any of:

string

string

null

null

lifecycleStateConfidencenumber | nullrequired

Confidence for the most recent lifecycle assessment.

Show properties

Any of:

number

number

null

null

linkedTicketobject | nullrequired

Show properties

Any of:

object

displayNamestringrequired

linkTypestringrequired

Allowed:issueproject

urlstring<uri>required

null

null

messageCountnumberrequired

personsobject[]required

Show properties

Array of object

avatarUrlstring | nullrequired

Show properties

Any of:

string

string

null

null

companyobject | nullrequired

Show properties

Any of:

object

domainstring | nullrequired

Show properties

Any of:

string

string

null

null

idstringrequired

isOrgCompanybooleanrequired

logoUrlstring | nullrequired

Show properties

Any of:

string

string

null

null

namestringrequired

null

null

displayNamestringrequired

idstringrequired

isBotbooleanrequired

isStaffbooleanrequired

prioritystringrequired

Priority level: very_low, low, default, high, or very_high

Allowed:defaulthighlowvery_highvery_low

similaritynumber

Cosine similarity score (0-1, higher = more similar). Only present when embeddingSearch is used.

sourcesstring[]required

staffResponseGroupCountnumberrequired

summarystringrequired

Descriptive summary of the topic.

timeRangeEndany

End of the time range covered by the topic.

timeRangeStartany

Start of the time range covered by the topic.

titlestringrequired

Short human-readable title of the topic.

totalGroupCountnumberrequired

updatedAtstring<date-time>

Timestamp when the topic was last updated.

limitintegerrequired

The page size used for this response.

pageintegerrequired

The 1-based page number returned.

totalCountintegerrequired

Total number of items matching the query, across all pages.

min 0

400

Invalid request (validation failed).

codestringrequired

Machine-readable error code, e.g. NOT_FOUND.

dataany

Optional structured error details.

definedbooleanrequired

True if the error was declared in the procedure contract.

messagestringrequired

Human-readable error message.

statusintegerrequired

HTTP status code.

401

Missing or invalid API key.

codestringrequired

Machine-readable error code, e.g. NOT_FOUND.

dataany

Optional structured error details.

definedbooleanrequired

True if the error was declared in the procedure contract.

messagestringrequired

Human-readable error message.

statusintegerrequired

HTTP status code.

403

The API key does not have access to this resource.

codestringrequired

Machine-readable error code, e.g. NOT_FOUND.

dataany

Optional structured error details.

definedbooleanrequired

True if the error was declared in the procedure contract.

messagestringrequired

Human-readable error message.

statusintegerrequired

HTTP status code.

404

The requested resource was not found.

codestringrequired

Machine-readable error code, e.g. NOT_FOUND.

dataany

Optional structured error details.

definedbooleanrequired

True if the error was declared in the procedure contract.

messagestringrequired

Human-readable error message.

statusintegerrequired

HTTP status code.

429

Rate limit exceeded.

codestringrequired

Machine-readable error code, e.g. NOT_FOUND.

dataany

Optional structured error details.

definedbooleanrequired

True if the error was declared in the procedure contract.

messagestringrequired

Human-readable error message.

statusintegerrequired

HTTP status code.

500

Internal server error.

codestringrequired

Machine-readable error code, e.g. NOT_FOUND.

dataany

Optional structured error details.

definedbooleanrequired

True if the error was declared in the procedure contract.

messagestringrequired

Human-readable error message.

statusintegerrequired

HTTP status code.

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer tokenRemember on this deviceInclude my values in samples

Parameters

viewqueryDeprecated and ignored. Topics are always served from the current pipeline, whichever value is sent. Accepted so existing requests keep working; omit it in new integrations.searchqueryKeyword search on title (max 100 chars). Wrap in double-quotes for exact token matching (e.g. "persona" matches the whole word and excludes "personal"). Ignored if embeddingSearch is provided.embeddingSearchquerySemantic search query using vector similarity. When provided, finds topics by meaning instead of keywords. Overrides the search parameter.minSimilarityqueryMinimum cosine similarity threshold for embeddingSearch (0-1, higher = more similar). Default 0.7.categoriesqueryFilter topics by keywords/categories (OR logic: topic must have ANY of the listed categories). Case-insensitive. For v2 topics a category is a catalog keyword slug (see topics.filterOptions), matched through the topic's open keyword attribution.excludeCategoriesqueryExclude topics by keywords/categories (OR logic: topic must have NONE of the listed categories). Case-insensitive. For v2 topics a category is a catalog keyword slug.issueTypesqueryexcludeIssueTypesquerysourcesqueryFilter topics by message sources (OR logic: topic must have messages from ANY listed source). Case-insensitive; duplicates are ignored.excludeSourcesqueryExclude topics by message sources (OR logic: topic must have NO messages from ANY listed source). Case-insensitive; duplicates are ignored.dateRangequeryFilter topics by time range overlapsortByquerySort order. 'groups' sorts by the number of groups. Use 'similarity' with embeddingSearch for best results.sortOrderqueryprioritiesqueryexcludePrioritiesquerylifecycleStatesqueryFilter topics by lifecycle state. "unknown" also matches topics with no lifecycle assessment.companiesqueryFilter topics by company IDs (OR logic: topic must have messages from people associated with ANY listed company).excludeCompaniesqueryExclude topics by company IDs (OR logic: topic must have NO messages from people associated with ANY listed company).productsqueryFilter topics by product IDs (OR logic: topic must have messages in a channel mapped to ANY listed product). Pass "none" to also match topics with no product attribution at all.excludeProductsqueryExclude topics by product IDs (OR logic: topic must have NO messages in a channel mapped to ANY listed product). Pass "none" to exclude topics with no product attribution at all.sourceContainersqueryFilter topics by source container IDs (OR logic: topic must draw evidence from ANY listed container). v2 only.excludeSourceContainersqueryExclude topics by source container IDs (OR logic: topic must draw evidence from NONE of the listed containers). v2 only.personsqueryFilter topics by person IDs (OR logic: topic must have messages from ANY listed person).excludePersonsqueryExclude topics by person IDs (OR logic: topic must have messages from NONE of the listed people).ticketStatusesqueryFilter by linked ticket presence. "has_ticket" = has any linked ticket, "none" = no linked ticket.excludeTicketStatusesqueryExclude by linked ticket presence. "has_ticket" excludes topics with tickets, "none" excludes topics without tickets.teamResponsequeryFilter by team response status. "not_responded" = no team member replied, "fully_responded" = team replied in all groups, "partially_responded" = team replied in some groups.pagequerylimitquery

Request

curl -X GET 'https://api.modem.dev/v1/topics' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'

const response = await fetch("https://api.modem.dev/v1/topics", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json"
  }
});

import requests

response = requests.get(
    "https://api.modem.dev/v1/topics",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json"
    },
)

Response

{
  "data": [
    {
      "authors": [
        {
          "displayName": "string",
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "isBot": true,
          "sourceAuthorId": "string",
          "sourceAvatarUrl": "http://example.com",
          "sourceName": "string"
        }
      ],
      "eventCount": 0,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "issueType": "bug_report",
      "keywords": [
        "string"
      ],
      "lifecycleState": "completed",
      "lifecycleStateConfidence": 0,
      "linkedTicket": {
        "displayName": "string",
        "linkType": "issue",
        "url": "http://example.com"
      },
      "messageCount": 0,
      "persons": [
        {
          "avatarUrl": "string",
          "company": {
            "domain": "string",
            "id": "string",
            "isOrgCompany": true,
            "logoUrl": "string",
            "name": "string"
          },
          "displayName": "string",
          "id": "string",
          "isBot": true,
          "isStaff": true
        }
      ],
      "priority": "default",
      "similarity": 0,
      "sources": [
        "string"
      ],
      "staffResponseGroupCount": 0,
      "summary": "string",
      "timeRangeEnd": null,
      "timeRangeStart": null,
      "title": "string",
      "totalGroupCount": 0,
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "limit": 1,
  "page": 1,
  "totalCount": 0
}

{
  "code": "NOT_FOUND",
  "data": null,
  "defined": true,
  "message": "string",
  "status": 404
}

{
  "code": "NOT_FOUND",
  "data": null,
  "defined": true,
  "message": "string",
  "status": 404
}

{
  "code": "NOT_FOUND",
  "data": null,
  "defined": true,
  "message": "string",
  "status": 404
}

{
  "code": "NOT_FOUND",
  "data": null,
  "defined": true,
  "message": "string",
  "status": 404
}

{
  "code": "NOT_FOUND",
  "data": null,
  "defined": true,
  "message": "string",
  "status": 404
}

{
  "code": "NOT_FOUND",
  "data": null,
  "defined": true,
  "message": "string",
  "status": 404
}