> ## 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. # Report Entity Schema > The dimensions, measures, filter fields (with their role and operators) and related blocks one report entity accepts. Use it to build or validate a query body before calling `POST /api/v1/projects/{project}/reports/{entity}`. The schema is the same for every project. ## OpenAPI ````yaml /openapi.json get /api/v1/reports/{entity}/schema 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`. - name: Reports description: >- The report query endpoint. One `POST` per report entity (`visibility`, `sources`, `narratives`) takes dimensions, measures, filters, an optional compare window and paging, and returns a dataset any renderer can draw. The schema and values endpoints describe what a query accepts. See the Reports API guide in the docs for worked examples of every app report. paths: /api/v1/reports/{entity}/schema: parameters: - name: entity in: path required: true description: The report entity. schema: $ref: '#/components/schemas/ReportEntity' get: tags: - Reports summary: Report Entity Schema description: >- The dimensions, measures, filter fields (with their role and operators) and related blocks one report entity accepts. Use it to build or validate a query body before calling `POST /api/v1/projects/{project}/reports/{entity}`. The schema is the same for every project. operationId: v1ReferenceReportsSchema responses: '200': description: The entity schema. content: application/json: schema: $ref: '#/components/schemas/ReportSchema' components: schemas: ReportEntity: type: string enum: - visibility - sources - narratives description: >- A report entity. `visibility`: brand visibility, mentions, position, sentiment and rank; with the `answer` dimension, one row per AI answer (a list, no compare window). `sources`: cited domains, hostnames, URLs and pages. `narratives`: reputation narratives, themes and sentiment (needs the Reputation capability). ReportSchema: type: object description: >- What one entity accepts: its dimensions, measures, filter fields with roles and operators, and related blocks. properties: entity: $ref: '#/components/schemas/ReportEntity' title: type: string requires_dimensions: type: boolean entity_columns: type: array items: $ref: '#/components/schemas/ReportSchemaColumn' description: >- Columns every row carries before the dimension columns. Empty on every current entity. dimensions: type: array items: $ref: '#/components/schemas/ReportSchemaColumn' measures: type: array items: $ref: '#/components/schemas/ReportSchemaColumn' filter_fields: type: array items: $ref: '#/components/schemas/ReportFilterField' order_fields: type: array items: type: string description: >- Every field `order_by` accepts: dimensions, measures with their compare columns, and extra sort fields such as `answered_at` on `visibility`. related: type: object additionalProperties: type: string description: Related block id to a one-line description. required: - entity - title - requires_dimensions - entity_columns - dimensions - measures - filter_fields - order_fields - related ReportSchemaColumn: type: object properties: id: type: string title: type: string type: type: string enum: - dimension - measure - date format: type: string enum: - number - percent decimals: type: integer nullable: true prefix: type: string suffix: type: string lower_is_better: type: boolean description: >- For measures: whether a lower value is the better one, such as `avg_position`. required: - id - title - type - format - decimals - prefix - suffix - lower_is_better ReportFilterField: type: object properties: field: type: string role: type: string enum: - population - lens - page - entity - measure description: >- `population` narrows which AI answers count and takes `in` only. `lens` (`page_brand` on sources) names the brand the page columns describe and removes no rows. `page` narrows which cited pages count. `entity` hides rows by label and needs its dimension on the row. `measure` hides rows by a computed value. operators: type: array items: $ref: '#/components/schemas/ReportFilterOperator' required: - field - role - operators ReportFilterOperator: type: string enum: - in - not_in - eq - gt - gte - lt - lte - contains description: >- `in` and `not_in` take `values`. `eq`, `gt`, `gte`, `lt` and `lte` take a numeric `value`. `contains` takes a text `value` and matches a label case-insensitively. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: token description: >- Team API key created in Team Settings. Use it with URLs for the same team. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.