> ## Documentation Index
> Fetch the complete documentation index at: https://help.statisfy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a report

> Creates a report, with its widgets if you send them, in one go: all of it or none. `name` is unique across the workspace (a taken name is a 409). A widget is a chart, metric or table that runs SQL (see `sql`), or a text widget. visibility defaults to team. The owner, by email, is a current member of your workspace; left out, a team report has no owner and only admins can change it in the app, and a private report needs one (in the app no one else sees it, admins included). At most 50 widgets per call; add more with POST /v1/reports/{report_id}/widgets.



## OpenAPI

````yaml /api/statisfy-api.openapi.json post /v1/reports
openapi: 3.1.0
info:
  description: >-
    The agent-first Statisfy API. Authenticate with an API key (`Authorization:
    Bearer stfy_live_…`), then call `GET /v1/meta/capabilities` to discover
    every operation and its schemas.
  title: Statisfy API
  version: 1.0.0
servers:
  - url: https://api.statisfy.com
    description: Production
security: []
paths:
  /v1/reports:
    post:
      tags:
        - reports
      summary: Create a report
      description: >-
        Creates a report, with its widgets if you send them, in one go: all of
        it or none. `name` is unique across the workspace (a taken name is a
        409). A widget is a chart, metric or table that runs SQL (see `sql`), or
        a text widget. visibility defaults to team. The owner, by email, is a
        current member of your workspace; left out, a team report has no owner
        and only admins can change it in the app, and a private report needs one
        (in the app no one else sees it, admins included). At most 50 widgets
        per call; add more with POST /v1/reports/{report_id}/widgets.
      operationId: reports_create
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                description:
                  anyOf:
                    - maxLength: 2000
                      type: string
                    - type: 'null'
                  default: null
                  title: Description
                name:
                  description: Unique across the workspace
                  maxLength: 255
                  minLength: 1
                  title: Name
                  type: string
                owner:
                  anyOf:
                    - maxLength: 320
                      minLength: 3
                      pattern: ^[^@\s]+@[^@\s]+$
                      type: string
                    - type: 'null'
                  default: null
                  description: >-
                    The email of a current member of your workspace: they can
                    change it in the app. Left out, a team report has no owner
                    and only admins can change it in the app. A private report
                    needs one
                  title: Owner
                visibility:
                  default: team
                  description: >-
                    team (everyone in the workspace sees it on the reports page)
                    or private (only its owner does; it needs an owner)
                  enum:
                    - team
                    - private
                  title: Visibility
                  type: string
                widgets:
                  items:
                    $ref: '#/components/schemas/ReportWidgetInput'
                  maxItems: 50
                  title: Widgets
                  type: array
              required:
                - name
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
          description: Successful Response
      security:
        - HTTPBearer: []
components:
  schemas:
    ReportWidgetInput:
      additionalProperties: false
      properties:
        chart:
          anyOf:
            - $ref: '#/components/schemas/ReportChartInput'
            - type: 'null'
          default: null
          description: 'For a chart, metric or table: its display settings'
        markdown:
          anyOf:
            - type: boolean
            - type: 'null'
          default: null
          description: 'For a text widget: show `text` as Markdown (default true)'
          title: Markdown
        position:
          anyOf:
            - $ref: '#/components/schemas/ReportWidgetPositionInput'
            - type: 'null'
          default: null
          description: >-
            Where it sits on the report's grid (12 columns wide). Left out or
            null, it goes at the left below the lowest widget, sized as the
            reports page sizes a new one (metric 3x2, bar_chart 6x4, line_chart
            6x4, area_chart 6x4, pie_chart 4x4, scatter_chart 6x4, table 12x4,
            text 4x2)
        sql:
          anyOf:
            - maxLength: 20000
              minLength: 1
              type: string
            - type: 'null'
          default: null
          description: >-
            For a chart, metric or table: one SELECT over the report views, as
            POST /v1/reports/query takes it (WITH queries are fine), except that
            a UNION, INTERSECT or EXCEPT can't be the whole statement (one can
            be in a subquery). On the reports page, a report's filter on a
            view's column is added to the outer SELECT's WHERE, so on a LEFT
            JOINed view it also drops the rows the join didn't match. It reaches
            the view through the outer FROM: the view itself, or a WITH query or
            subquery whose SELECT returns the column under the same name or with
            a bare *. The widget skips a filter it can't reach that way, such as
            through a renamed or aggregated column, a v.*, or a UNION, and one
            on a view the outer FROM reads twice. There, a viewer who sees only
            their own accounts reads every report view in it limited to those
            accounts, wherever it is named (people_internal_view, your
            workspace's own people, belongs to no account and isn't limited).
            What is saved is the checked statement, as POST /v1/reports/query
            returns it in `sql`: without comments or your workspace's schema
            name, with some spellings normalized
          title: Sql
        text:
          anyOf:
            - maxLength: 20000
              type: string
            - type: 'null'
          default: null
          description: 'For a text widget: its content'
          title: Text
        title:
          maxLength: 255
          minLength: 1
          title: Title
          type: string
        type:
          enum:
            - metric
            - bar_chart
            - line_chart
            - area_chart
            - pie_chart
            - scatter_chart
            - table
            - text
          title: Type
          type: string
      required:
        - type
        - title
      title: ReportWidgetInput
      type: object
    Report:
      properties:
        created_at:
          format: date-time
          title: Created At
          type: string
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        id:
          title: Id
          type: string
        name:
          description: Unique across the workspace
          title: Name
          type: string
        owner:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The owner's email: besides admins, only the owner can change it in
            the app. Null when it has no owner, or its owner is no longer a user
          title: Owner
        updated_at:
          format: date-time
          title: Updated At
          type: string
        visibility:
          description: >-
            team (Public in the app: everyone in the workspace sees it on the
            reports page) or private (only its owner sees it there; admins can
            change it but don't see it listed). The API lists both
          enum:
            - team
            - private
          title: Visibility
          type: string
        widgets:
          items:
            $ref: '#/components/schemas/ReportWidget'
          title: Widgets
          type: array
      required:
        - id
        - name
        - description
        - visibility
        - owner
        - widgets
        - created_at
        - updated_at
      title: Report
      type: object
    ReportChartInput:
      additionalProperties: false
      description: >-
        Chart settings to write, in the read's names; a key that isn't one of
        them is refused.
      properties:
        colors:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          default: null
          description: The palette, as CSS colors
          title: Colors
        compact_notation:
          anyOf:
            - enum:
                - K
                - M
                - B
                - T
              type: string
            - type: 'null'
          default: null
          title: Compact Notation
        currency_symbol:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Currency Symbol
        decimal_digits:
          anyOf:
            - maximum: 20
              minimum: 0
              type: integer
            - type: 'null'
          default: null
          title: Decimal Digits
        max_series:
          anyOf:
            - minimum: 1
              type: integer
            - type: 'null'
          default: null
          description: Show the top N series by total
          title: Max Series
        orientation:
          anyOf:
            - enum:
                - vertical
                - horizontal
              type: string
            - type: 'null'
          default: null
          title: Orientation
        page_size:
          anyOf:
            - minimum: 1
              type: integer
            - type: 'null'
          default: null
          description: A table's rows per page
          title: Page Size
        pivot_column:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: A table's column whose values become columns
          title: Pivot Column
        series_column:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: A column whose values split the data into series
          title: Series Column
        show_data_labels:
          anyOf:
            - type: boolean
            - type: 'null'
          default: null
          title: Show Data Labels
        show_legend:
          anyOf:
            - type: boolean
            - type: 'null'
          default: null
          title: Show Legend
        stacked:
          anyOf:
            - type: boolean
            - type: 'null'
          default: null
          title: Stacked
        value_column:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: The column a pivot spreads
          title: Value Column
        value_format:
          anyOf:
            - enum:
                - number
                - currency
                - percent
                - compact
              type: string
            - type: 'null'
          default: null
          description: 'How the widget''s values read: a metric''s value, a chart''s axis'
          title: Value Format
        x_axis:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: The column on the x axis
          title: X Axis
        y_axis:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          default: null
          description: The columns plotted, one series each
          title: Y Axis
      title: ReportChartInput
      type: object
    ReportWidgetPositionInput:
      additionalProperties: false
      description: >-
        A position to write: on the page's 12-column grid, within the rows the
        page can sort.
      properties:
        h:
          description: Height, in rows
          maximum: 100
          minimum: 1
          title: H
          type: integer
        w:
          description: Width, in columns; x + w is at most 12
          maximum: 12
          minimum: 1
          title: W
          type: integer
        x:
          description: Columns from the left of the grid
          maximum: 11
          minimum: 0
          title: X
          type: integer
        'y':
          description: Rows from the top
          maximum: 10000
          minimum: 0
          title: 'Y'
          type: integer
      required:
        - x
        - 'y'
        - w
        - h
      title: ReportWidgetPositionInput
      type: object
    ReportWidget:
      properties:
        built_with:
          description: >-
            sql (it runs SQL: `sql` holds it), builder (made with the visual
            query builder; the API doesn't return its query), or text (a text
            widget: `text` holds it)
          enum:
            - sql
            - builder
            - text
          title: Built With
          type: string
        chart:
          $ref: '#/components/schemas/ReportChart'
        id:
          title: Id
          type: string
        markdown:
          anyOf:
            - type: boolean
            - type: 'null'
          description: >-
            A text widget's Markdown option: true shows `text` as Markdown,
            false as plain text
          title: Markdown
        position:
          anyOf:
            - $ref: '#/components/schemas/ReportWidgetPosition'
            - type: 'null'
          description: >-
            Where it sits on the report's grid; null if what's stored can't be
            read
        sql:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The widget's SQL as saved in the app: it may have comments or your
            workspace's schema name. On the reports page it runs with the
            report's filters and the viewer's scope added, under the app's own
            checks, so POST /v1/reports/query may refuse it or return different
            rows
          title: Sql
        text:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            A text widget's content. The app shows it as Markdown when the
            widget's Markdown option is on (new text widgets have it on),
            otherwise as plain text
          title: Text
        title:
          title: Title
          type: string
        type:
          description: >-
            metric, bar_chart, line_chart, area_chart, pie_chart, scatter_chart,
            table or text
          title: Type
          type: string
      required:
        - id
        - title
        - type
        - built_with
        - chart
        - position
      title: ReportWidget
      type: object
    ReportChart:
      description: A widget's display settings, as the reports page stores them.
      properties:
        colors:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: The palette, as CSS colors
          title: Colors
        compact_notation:
          anyOf:
            - enum:
                - K
                - M
                - B
                - T
              type: string
            - type: 'null'
          title: Compact Notation
        currency_symbol:
          anyOf:
            - type: string
            - type: 'null'
          title: Currency Symbol
        decimal_digits:
          anyOf:
            - maximum: 20
              minimum: 0
              type: integer
            - type: 'null'
          title: Decimal Digits
        max_series:
          anyOf:
            - minimum: 1
              type: integer
            - type: 'null'
          description: Show the top N series by total
          title: Max Series
        orientation:
          anyOf:
            - enum:
                - vertical
                - horizontal
              type: string
            - type: 'null'
          title: Orientation
        page_size:
          anyOf:
            - minimum: 1
              type: integer
            - type: 'null'
          description: A table's rows per page
          title: Page Size
        pivot_column:
          anyOf:
            - type: string
            - type: 'null'
          description: A table's column whose values become columns
          title: Pivot Column
        series_column:
          anyOf:
            - type: string
            - type: 'null'
          description: A column whose values split the data into series
          title: Series Column
        show_data_labels:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Show Data Labels
        show_legend:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Show Legend
        stacked:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Stacked
        value_column:
          anyOf:
            - type: string
            - type: 'null'
          description: The column a pivot spreads
          title: Value Column
        value_format:
          anyOf:
            - enum:
                - number
                - currency
                - percent
                - compact
              type: string
            - type: 'null'
          description: 'How the widget''s values read: a metric''s value, a chart''s axis'
          title: Value Format
        x_axis:
          anyOf:
            - type: string
            - type: 'null'
          description: The column on the x axis
          title: X Axis
        y_axis:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: The columns plotted, one series each
          title: Y Axis
      title: ReportChart
      type: object
    ReportWidgetPosition:
      properties:
        h:
          description: Height, in rows
          minimum: 1
          title: H
          type: integer
        w:
          description: Width, in columns
          minimum: 1
          title: W
          type: integer
        x:
          description: Columns from the left of the report's grid
          minimum: 0
          title: X
          type: integer
        'y':
          description: Rows from the top
          minimum: 0
          title: 'Y'
          type: integer
      required:
        - x
        - 'y'
        - w
        - h
      title: ReportWidgetPosition
      type: object
  securitySchemes:
    HTTPBearer:
      scheme: bearer
      type: http
      description: >-
        An API key, sent as `Authorization: Bearer stfy_live_…`. See
        [Authentication](/rest-api/authentication) for how to get one and which
        scopes it needs.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.