> ## Documentation Index > Fetch the complete documentation index at: https://modem.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # 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". ## OpenAPI ````yaml /api-reference/openapi.json get /topics openapi: 3.1.1 info: description: >- The public Modem API. Authenticate with an organization API key: `Authorization: Bearer modem_…`. title: Modem API version: 1.0.0 servers: - description: Production url: https://api.modem.dev/v1 security: - bearerAuth: [] paths: /topics: get: tags: - Topics summary: List topics description: >- 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". operationId: topics.list parameters: - allowEmptyValue: true allowReserved: true in: query name: view required: false schema: description: >- Topics source pipeline. 'v2' serves rows from the v2 ingest pipeline (v2_topics) and is only honored when the organization's v2-topics-view feature flag is on — without the flag the parameter is ignored and v1 is served. Omitted or 'v1' always serves the v1 pipeline. enum: - v1 - v2 title: View type: string - allowEmptyValue: true allowReserved: true in: query name: search required: false schema: description: >- 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. maxLength: 100 title: Search type: string - allowEmptyValue: true allowReserved: true in: query name: embeddingSearch required: false schema: description: >- Semantic search query using vector similarity. When provided, finds topics by meaning instead of keywords. Overrides the search parameter. maxLength: 1000 minLength: 1 title: Embedding Search type: string - allowEmptyValue: true allowReserved: true in: query name: minSimilarity required: false schema: default: 0.7 description: >- Minimum cosine similarity threshold for embeddingSearch (0-1, higher = more similar). Default 0.7. maximum: 1 minimum: 0 title: Minimum Similarity type: number - allowEmptyValue: true allowReserved: true explode: true in: query name: categories required: false schema: description: >- Filter topics by keywords/categories (OR logic: topic must have ANY of the listed categories). Case-insensitive. items: type: string title: Categories type: array style: deepObject - allowEmptyValue: true allowReserved: true explode: true in: query name: excludeCategories required: false schema: description: >- Exclude topics by keywords/categories (OR logic: topic must have NONE of the listed categories). Case-insensitive. items: type: string title: Exclude Categories type: array style: deepObject - allowEmptyValue: true allowReserved: true explode: true in: query name: issueTypes required: false schema: items: enum: - bug_report - complaint - discussion - feature_request - praise type: string type: array style: deepObject - allowEmptyValue: true allowReserved: true explode: true in: query name: excludeIssueTypes required: false schema: items: enum: - bug_report - complaint - discussion - feature_request - praise type: string type: array style: deepObject - allowEmptyValue: true allowReserved: true explode: true in: query name: sources required: false schema: description: >- Filter topics by message sources (OR logic: topic must have messages from ANY listed source). Case-insensitive; duplicates are ignored. items: type: string minItems: 1 title: Sources type: array style: deepObject - allowEmptyValue: true allowReserved: true explode: true in: query name: excludeSources required: false schema: description: >- Exclude topics by message sources (OR logic: topic must have NO messages from ANY listed source). Case-insensitive; duplicates are ignored. items: type: string minItems: 1 title: Exclude Sources type: array style: deepObject - allowEmptyValue: true allowReserved: true explode: true in: query name: dateRange required: false schema: description: Filter topics by time range overlap properties: end: format: date-time type: string start: format: date-time type: string required: - end - start title: Date range type: object style: deepObject - allowEmptyValue: true allowReserved: true in: query name: sortBy required: false schema: default: date description: >- Sort order. Use 'similarity' when using embeddingSearch for best results. enum: - date - groups - lifecycle - priority - similarity title: Sort By type: string - allowEmptyValue: true allowReserved: true in: query name: sortOrder required: false schema: default: desc enum: - asc - desc type: string - allowEmptyValue: true allowReserved: true explode: true in: query name: priorities required: false schema: items: description: 'Priority level: very_low, low, default, high, or very_high' enum: - default - high - low - very_high - very_low title: Priority type: string type: array style: deepObject - allowEmptyValue: true allowReserved: true explode: true in: query name: excludePriorities required: false schema: items: description: 'Priority level: very_low, low, default, high, or very_high' enum: - default - high - low - very_high - very_low title: Priority type: string type: array style: deepObject - allowEmptyValue: true allowReserved: true explode: true in: query name: lifecycleStates required: false schema: description: >- Filter topics by lifecycle state. "unknown" also matches topics with no lifecycle assessment. items: description: LLM-assessed lifecycle state for a topic. enum: - completed - dismissed - in_progress - open - unknown title: Topic Lifecycle State type: string title: Lifecycle States type: array style: deepObject - allowEmptyValue: true allowReserved: true explode: true in: query name: companies required: false schema: description: >- Filter topics by company IDs (OR logic: topic must have messages from people associated with ANY listed company). items: type: string title: Companies type: array style: deepObject - allowEmptyValue: true allowReserved: true explode: true in: query name: excludeCompanies required: false schema: description: >- Exclude topics by company IDs (OR logic: topic must have NO messages from people associated with ANY listed company). items: type: string title: Exclude Companies type: array style: deepObject - allowEmptyValue: true allowReserved: true explode: true in: query name: persons required: false schema: description: >- Filter topics by person IDs (OR logic: topic must have messages from ANY listed person). items: type: string title: Persons type: array style: deepObject - allowEmptyValue: true allowReserved: true explode: true in: query name: excludePersons required: false schema: description: >- Exclude topics by person IDs (OR logic: topic must have messages from NONE of the listed people). items: type: string title: Exclude Persons type: array style: deepObject - allowEmptyValue: true allowReserved: true explode: true in: query name: ticketStatuses required: false schema: description: >- Filter by linked ticket presence. "has_ticket" = has any linked ticket, "none" = no linked ticket. items: enum: - has_ticket - none type: string title: Ticket Statuses type: array style: deepObject - allowEmptyValue: true allowReserved: true explode: true in: query name: excludeTicketStatuses required: false schema: description: >- Exclude by linked ticket presence. "has_ticket" excludes topics with tickets, "none" excludes topics without tickets. items: enum: - has_ticket - none type: string title: Exclude Ticket Statuses type: array style: deepObject - allowEmptyValue: true allowReserved: true explode: true in: query name: teamResponse required: false schema: description: >- 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. items: enum: - fully_responded - not_responded - partially_responded type: string title: Team Response type: array style: deepObject - allowEmptyValue: true allowReserved: true in: query name: page required: false schema: default: 1 exclusiveMinimum: 0 type: integer - allowEmptyValue: true allowReserved: true in: query name: limit required: false schema: default: 10 exclusiveMinimum: 0 maximum: 100 type: integer responses: '200': content: application/json: schema: properties: data: items: properties: authors: items: properties: displayName: anyOf: - type: string - type: 'null' description: Optional display name for the author. title: Display Name id: anyOf: - format: uuid type: string - format: uuid type: string isBot: description: Whether the author is a bot account. title: Is Bot type: boolean sourceAuthorId: description: Author identifier in the source system. title: Source Author ID type: string sourceAvatarUrl: anyOf: - format: uri type: string - type: 'null' description: Avatar image URL from the source system. title: Source Avatar URL sourceName: description: Source system where the author originates. pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$ title: Source Name type: string required: - displayName - id - isBot - sourceAuthorId - sourceAvatarUrl - sourceName type: object type: array eventCount: description: Number of events grouped under this topic. title: Event Count type: integer id: anyOf: - format: uuid type: string - format: uuid type: string issueType: anyOf: - description: Classification for the topic as a type of issue. enum: - bug_report - complaint - discussion - feature_request - praise title: Issue Type type: string - type: 'null' description: Optional issue classification for the topic. title: Issue Type keywords: description: Keywords associated with the topic. items: type: string title: Keywords type: array lifecycleState: anyOf: - description: LLM-assessed lifecycle state for a topic. enum: - completed - dismissed - in_progress - open - unknown title: Topic Lifecycle State type: string - type: 'null' description: >- Most recent LLM-assessed lifecycle state for this topic. title: Lifecycle State lifecycleStateConfidence: anyOf: - maximum: 1 minimum: 0 type: number - type: 'null' description: Confidence for the most recent lifecycle assessment. title: Lifecycle State Confidence linkedTicket: anyOf: - properties: displayName: type: string linkType: enum: - issue - project type: string url: format: uri type: string required: - displayName - linkType - url type: object - type: 'null' messageCount: type: number persons: items: properties: avatarUrl: anyOf: - type: string - type: 'null' company: anyOf: - properties: domain: anyOf: - type: string - type: 'null' id: type: string isOrgCompany: type: boolean logoUrl: anyOf: - type: string - type: 'null' name: type: string required: - domain - id - isOrgCompany - logoUrl - name type: object - type: 'null' displayName: type: string id: type: string isBot: type: boolean isStaff: type: boolean required: - avatarUrl - company - displayName - id - isBot - isStaff type: object type: array priority: description: >- Priority level: very_low, low, default, high, or very_high enum: - default - high - low - very_high - very_low title: Priority type: string similarity: description: >- Cosine similarity score (0-1, higher = more similar). Only present when embeddingSearch is used. title: Similarity type: number sources: items: type: string type: array staffResponseGroupCount: type: number summary: description: Descriptive summary of the topic. title: Summary type: string timeRangeEnd: description: End of the time range covered by the topic. title: Time Range End timeRangeStart: description: Start of the time range covered by the topic. title: Time Range Start title: description: Short human-readable title of the topic. title: Title type: string totalGroupCount: type: number updatedAt: description: Timestamp when the topic was last updated. format: date-time title: Updated At type: string required: - authors - eventCount - id - issueType - keywords - lifecycleState - lifecycleStateConfidence - linkedTicket - messageCount - persons - priority - sources - staffResponseGroupCount - summary - title - totalGroupCount type: object type: array limit: description: The page size used for this response. exclusiveMinimum: 0 type: integer page: description: The 1-based page number returned. exclusiveMinimum: 0 type: integer totalCount: description: >- Total number of items matching the query, across all pages. minimum: 0 type: integer required: - data - limit - page - totalCount type: object description: OK '400': content: application/json: schema: $ref: '#/components/schemas/Error' description: Invalid request (validation failed). '401': content: application/json: schema: $ref: '#/components/schemas/Error' description: Missing or invalid API key. '403': content: application/json: schema: $ref: '#/components/schemas/Error' description: The API key does not have access to this resource. '404': content: application/json: schema: $ref: '#/components/schemas/Error' description: The requested resource was not found. '429': content: application/json: schema: $ref: '#/components/schemas/Error' description: Rate limit exceeded. '500': content: application/json: schema: $ref: '#/components/schemas/Error' description: Internal server error. components: schemas: Error: properties: code: description: Machine-readable error code, e.g. `NOT_FOUND`. examples: - NOT_FOUND type: string data: description: Optional structured error details. defined: description: True if the error was declared in the procedure contract. type: boolean message: description: Human-readable error message. type: string status: description: HTTP status code. examples: - 404 type: integer required: - code - defined - message - status type: object securitySchemes: bearerAuth: description: Organization API key (`modem_…`). scheme: bearer type: http ````