> ## Documentation Index > Fetch the complete documentation index at: https://docs.surfacd.com/llms.txt > Use this file to discover all available pages before exploring further. # Get Theme > A single theme with its narratives, per-platform sentiment split, and trajectory across the date range. ## OpenAPI ````yaml /openapi.json get /api/v1/projects/{project}/reputation/themes/{theme} openapi: 3.1.0 info: title: Surfacd Public API version: 1.0.0 description: >- Public API for Surfacd. Team-scoped operations live under `/api/v1/team/...`; project collections live under `/api/v1/projects`; project-scoped operations live under `/api/v1/projects/{project}/...`. All endpoints require a Bearer team API key created in Team Settings. The API key selects the team for team-level and collection endpoints. servers: - url: https://app.surfacd.com description: Production security: - bearerAuth: [] tags: - name: Projects description: Project management endpoints. Reads only in this version. - name: Prompts description: Prompt management endpoints. Reads only in this version. - name: Team description: Team settings and plan details for the current team. - name: Reporting description: >- Read-only reporting endpoints for projects (brand rankings, mentions, visibility, matrix analysis, source data). - name: Reference description: Reference data used by create, update, and reporting filters. - name: Tags description: Project tag management endpoints. - name: Reputation description: >- Read-only reputation analytics for a project: sentiment overview and trends, themes, narratives, the AI responses behind them, and the sources those responses cite. Requires the Reputation capability on the project's team; without it these endpoints return `403`. paths: /api/v1/projects/{project}/reputation/themes/{theme}: parameters: - $ref: '#/components/parameters/ProjectUuid' - $ref: '#/components/parameters/ThemeUuid' get: tags: - Reputation summary: Get Theme description: >- A single theme with its narratives, per-platform sentiment split, and trajectory across the date range. operationId: v1ProjectsReputationThemesShow parameters: - name: start_date in: query required: true schema: type: string format: date - name: end_date in: query required: true schema: type: string format: date description: Must be on or after `start_date`. - name: tags in: query required: false schema: type: array items: type: string description: >- Tag UUID or name filters. Repeat as `tags[]=`. Discover tags with `GET /api/v1/projects/{project}/tags`. style: form explode: true - name: services in: query required: false schema: type: array items: type: string description: >- AI platform provider filters such as `chatgpt` or `perplexity`. Repeat as `services[]=`. Discover providers with `GET /api/v1/platforms`. style: form explode: true - name: countries in: query required: false schema: type: array items: type: string description: >- Country code filters such as `US` or `GB`. Repeat as `countries[]=`. Discover codes with `GET /api/v1/countries`. style: form explode: true - name: topics in: query required: false schema: type: array items: type: string description: >- Topic UUID or name filters. Use `no_topic` for prompts without a topic. Repeat as `topics[]=`. Discover topics with `GET /api/v1/projects/{project}/topics`. style: form explode: true - name: prompt in: query required: false schema: type: string format: uuid description: Prompt UUID filter. - name: brand in: query required: false schema: type: string format: uuid description: >- Brand UUID to scope the reputation data to. Must belong to the project. Defaults to the project's primary brand; when the project has no primary brand an explicit `brand` is required. Discover brand UUIDs with `GET /api/v1/projects/{project}/brands`. responses: '200': description: The theme detail. content: application/json: schema: type: object properties: theme: $ref: '#/components/schemas/ThemeDetail' required: - theme '403': $ref: '#/components/responses/ReputationNotEnabled' '404': description: Theme not found in this project. content: application/json: schema: type: object properties: message: type: string required: - message '422': $ref: '#/components/responses/ValidationError' components: parameters: ProjectUuid: name: project in: path required: true description: Project UUID. schema: type: string format: uuid ThemeUuid: name: theme in: path required: true description: The theme UUID. schema: type: string format: uuid schemas: ThemeDetail: type: object description: >- A single theme with its narratives, per-platform sentiment split, and trajectory. properties: uuid: type: string format: uuid label: type: string description: type: - string - 'null' narrative_count: type: integer response_share: type: number format: float sentiment_breakdown: $ref: '#/components/schemas/ReputationSentimentBreakdown' sentiment_score: type: integer first_seen_at: type: - string - 'null' format: date-time last_seen_at: type: - string - 'null' format: date-time narratives: type: array items: $ref: '#/components/schemas/NarrativeSummary' services: type: array items: $ref: '#/components/schemas/ReputationServiceChip' trajectory: type: array items: $ref: '#/components/schemas/NarrativeSparklinePoint' sentiment_by_model: type: array items: $ref: '#/components/schemas/SentimentByModel' previous_sentiment_score: type: - integer - 'null' previous_response_share: type: - number - 'null' format: float required: - uuid - label - description - narrative_count - response_share - sentiment_breakdown - sentiment_score - first_seen_at - last_seen_at - narratives - services - trajectory - sentiment_by_model - previous_sentiment_score - previous_response_share ReputationSentimentBreakdown: type: object description: Mention counts split by sentiment valence. properties: positive: type: integer neutral: type: integer negative: type: integer required: - positive - neutral - negative NarrativeSummary: type: object description: >- A narrative (a recurring storyline) with its windowed metrics. `response_share` is the share of in-scope responses that mention the narrative. properties: uuid: type: string format: uuid label: type: string description: type: - string - 'null' sentiment: $ref: '#/components/schemas/BrandSentiment' description: Overall sentiment of the narrative across the window. response_share: type: number format: float first_seen_at: type: - string - 'null' format: date-time last_seen_at: type: - string - 'null' format: date-time sparkline: type: array items: $ref: '#/components/schemas/NarrativeSparklinePoint' theme: oneOf: - $ref: '#/components/schemas/ReputationThemeChip' - type: 'null' services: type: array items: $ref: '#/components/schemas/ReputationServiceChip' previous_response_share: type: - number - 'null' format: float momentum: oneOf: - $ref: '#/components/schemas/ReputationTrajectory' - type: 'null' required: - uuid - label - description - sentiment - response_share - first_seen_at - last_seen_at - sparkline - theme - services - previous_response_share - momentum ReputationServiceChip: type: object description: A compact AI platform reference attached to a reputation entity. properties: name: type: string display_name: type: string required: - name - display_name NarrativeSparklinePoint: type: object description: >- One day of mention volume, split by sentiment, for an entity's sparkline. properties: date: type: string format: date-time count: type: integer positive_count: type: integer negative_count: type: integer neutral_count: type: integer required: - date - count - positive_count - negative_count - neutral_count SentimentByModel: type: object description: >- Per-platform sentiment distribution and Net Sentiment Index (0-100). `previous_score` is null when the prior window had no mentions for that platform. properties: service_name: type: string service_display_name: type: string positive: type: integer neutral: type: integer negative: type: integer score: type: integer description: Net Sentiment Index for this platform (0-100). previous_score: type: - integer - 'null' required: - service_name - service_display_name - positive - neutral - negative - score - previous_score ValidationError: type: object description: Returned when one or more request parameters fail validation. properties: message: type: string errors: type: object additionalProperties: type: array items: type: string required: - message - errors BrandSentiment: type: string enum: - positive - negative - neutral description: The sentiment valence of a mention or narrative. ReputationThemeChip: type: object description: A compact theme reference (the parent theme of a narrative). properties: uuid: type: string format: uuid label: type: string required: - uuid - label ReputationTrajectory: type: string enum: - emerging - surging - steady - cooling - dormant description: >- The volume-axis momentum of a reputation entity over the active window versus the equal-length previous window. responses: ReputationNotEnabled: description: >- Reputation is not available: the team's plan does not include the Reputation capability, or the project has not enabled it. content: application/json: schema: type: object properties: message: type: string required: - message ValidationError: description: Validation failed. content: application/json: schema: $ref: '#/components/schemas/ValidationError' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: token description: >- Team API key created in Team Settings. Use it with URLs for the same team. ````