> ## Documentation Index > Fetch the complete documentation index at: https://docs.surnex.io/llms.txt > Use this file to discover all available pages before exploring further. # Create a report > Create a new blank report for a project. The report is created with no pages or widgets. Use POST /reports/{report_id}/pages to add pages, then POST /pages/{page_id}/widgets to populate them with data widgets. An optional date range (preset or explicit start/end dates) can be configured at creation time and overridden per widget data fetch. ## OpenAPI ````yaml https://api.surnex.io/openapi.json post /v1/projects/{project_id}/reports openapi: 3.1.0 info: title: Surnex API description: |- Surnex SEO Platform API — api.surnex.io Provides the complete backend for the Surnex SEO dashboard including: - Multi-tenant organization management - Project tracking (domains) - Keyword rank tracking (Phase 1+) - Backlink analysis (Phase 3+) - Site auditing (Phase 4+) - Stripe billing integration - MCP endpoint for AI agents at /mcp version: 0.1.0 servers: [] security: [] paths: /v1/projects/{project_id}/reports: post: tags: - Reports summary: Create a report description: >- Create a new blank report for a project. The report is created with no pages or widgets. Use POST /reports/{report_id}/pages to add pages, then POST /pages/{page_id}/widgets to populate them with data widgets. An optional date range (preset or explicit start/end dates) can be configured at creation time and overridden per widget data fetch. operationId: create_report_v1_projects__project_id__reports_post parameters: - name: project_id in: path required: true schema: type: string format: uuid title: Project Id - name: X-API-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ReportCreate' responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/APIResponse_ReportResponse_' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - HTTPBearer: [] components: schemas: ReportCreate: properties: name: type: string maxLength: 255 minLength: 1 title: Name description: Display name for the report. description: anyOf: - type: string - type: 'null' title: Description description: Optional longer description of the report's purpose. date_range_start: anyOf: - type: string format: date - type: 'null' title: Date Range Start description: Inclusive start date for the report's data range. date_range_end: anyOf: - type: string format: date - type: 'null' title: Date Range End description: Inclusive end date for the report's data range. date_range_preset: anyOf: - type: string - type: 'null' title: Date Range Preset description: >- Relative date range shortcut. One of '7d', '30d', '90d'. Takes precedence over explicit start/end dates when set. type: object required: - name title: ReportCreate description: Request body for creating a new report. APIResponse_ReportResponse_: properties: success: type: boolean title: Success default: true data: anyOf: - $ref: '#/components/schemas/ReportResponse' - type: 'null' type: object title: APIResponse[ReportResponse] HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ReportResponse: properties: id: type: string format: uuid title: Id name: type: string title: Name description: anyOf: - type: string - type: 'null' title: Description date_range_start: anyOf: - type: string format: date - type: 'null' title: Date Range Start date_range_end: anyOf: - type: string format: date - type: 'null' title: Date Range End date_range_preset: anyOf: - type: string - type: 'null' title: Date Range Preset is_archived: type: boolean title: Is Archived schedule_enabled: type: boolean title: Schedule Enabled default: false pages: items: $ref: '#/components/schemas/ReportPageResponse' type: array title: Pages created_by: anyOf: - type: string format: uuid - type: 'null' title: Created By created_at: type: string format: date-time title: Created At updated_at: type: string format: date-time title: Updated At type: object required: - id - name - is_archived - pages - created_at - updated_at title: ReportResponse description: Full report record including all pages and their widgets. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError ReportPageResponse: properties: id: type: string format: uuid title: Id name: type: string title: Name sort_order: type: integer title: Sort Order layout_columns: type: integer title: Layout Columns widgets: items: $ref: '#/components/schemas/ReportWidgetResponse' type: array title: Widgets created_at: type: string format: date-time title: Created At type: object required: - id - name - sort_order - layout_columns - widgets - created_at title: ReportPageResponse description: A report page with its ordered list of widgets. ReportWidgetResponse: properties: id: type: string format: uuid title: Id widget_type: type: string title: Widget Type data_source: anyOf: - type: string - type: 'null' title: Data Source title: type: string title: Title config: additionalProperties: true type: object title: Config position_x: type: integer title: Position X position_y: type: integer title: Position Y width: type: integer title: Width height: type: integer title: Height created_at: type: string format: date-time title: Created At type: object required: - id - widget_type - title - config - position_x - position_y - width - height - created_at title: ReportWidgetResponse description: A single report widget as returned by the API. securitySchemes: HTTPBearer: type: http scheme: bearer ````