openapi: 3.2.0
info:
  title: SpringServe UI Scheduled Reports API
  version: 1.0.0
  description: "> **_NOTE:_** This document covers the v1 API (`/api/v1`). You can find additional documentation on the v1 API (`/api/v1`) on the \n[Magnite Help Center](https://help.magnite.com/), which is broken into sections for endpoints relevant to \n[SpringServe](https://help.magnite.com/help/api-documentation) and [Clearline](https://help.magnite.com/help/api-documentation-06dd4d3). \nYou can also find V1 swagger documentation by selecting ‘SpringServe API V1’ from the dropdown at the top right corner \nof this page. Please note we are in the process of creating V1 endpoints for all existing V0 endpoints, but while that work \nis in progress not all endpoints will be supported on V1. We advise reviewing both swagger pages to determine what \nis supported in each version.\n\n# Authentication\nWhen using this API documentation server, by default it will authenticate API calls using cookie-based authentication against the selected server.  If you are properly logged into the SpringServe server and your session is still active, then the API calls should automatically authenticate.  \n\nOutside of this API documentation server you should use either Token Based or Bearer authentication.  You may also these authentication methods on this server as well,\n which will take precedence over any cookie/session based authentication.\n### Token Based Authentication\nUse the [POST /api/v1/auth](#/Auth/auth_post) endpoint to generate an API token that is then passed in the `Authorization: <token>` header\n\n### Bearer Authentication\nUse the [POST /api/v1/auth](#/Auth/auth_post) endpoint to authenticate and get a bearer token that is then passed in the `Authorization: Bearer <token>` header\n\n# Active Account Context\nA given request always runs in the context of currently active account for the authenticated user making the request.  The active account can be determined via\nthe [GET /api/v1/accounts/current](#/Accounts/accounts_current_get) endpoint and updated via [POST /api/v1/accounts/{id}/set_current](#/Accounts/accounts_id_set_current_post).\nThe active account can also be overridden for an authenticated request by passing the `x-auth-context` header.\n\n# Common List Resource Functionality\n\n## List Resource Requests\nVirtually all List endpoints (e.g. `GET /api/v1/demand_tags`) support the following via request query parameters:\n* Pagination via the `page` (first page is page `1`) and `per` (how many results per page, default is `50`, max is `1000`) query parameters.\n* Searching via the `search` query param\n* Sorting via the comma-delimited `sort` query param - e.g. `sort=name,-id` would sort by name ascending, then by id descending.  By default,\nonly first-level (directly on the entity, not on associations) attributes are sortable.  Some endpoints expose additional/custom orderable fields, \nwhich are documented with that endpoint.\n* Filtering via the query param `<attribute>=<value>` e.g. `id=3` for every first-level (not on associations) attribute on the entity.  Some\n  endpoints expose additional filters which are called out in the documentation for that endpoint.  You can also add an optional operator to the filter via the format `<attribute>::<operator>=<value>`, \n  e.g. `id::gt=3` to filter for ids greater than 3 or `updated_at::lte=2025-01-01` to filter for updated_at less than or equal to 2025-01-01.  \n  The following operators are supported:\n  * `::gt` - greater than\n  * `::gte` - greater than or equal to\n  * `::lt` - less than\n  * `::lte` - less than or equal to\n  * `::in` - in the comma-delimited list of values\n  * `::null` - attribute is null (`true` or `1`) or not null (`false` or `0`)\n* Inclusion of associated resources via the comma-delimited `includes` attribute. The common List Result body has `includable_fields` metadata\n  that tells you which associations are includable.  If not specified, a logical default set of associations are included.  You may pass\n  `includes=` as a blank entry to not include any associations, which can speed up API results if the associated data is not needed.\n* Inclusion of additional data (e.g. quickstats) via the `additional_data` query param.  Possible values come from the `additional_data_fields`\narray on a list response.\n\n## List Resource Responses\nVirtually all List endoints have the same result format:\n* `count` - how many results are in this response\n* `total_count` - how many results are their across all pages of results\n* `current_page` - the current page of results (first page is `1`)\n* `total_pages` - how many total pages of results there are\n* `includable_fields` - assocations of the current resource that `can` be included in the result via the `include` query param.  Note: this is not necessarily what is included\nin the current result, but rather what is possible to request.\n* `additional_data_fields` - additional data, beyond normal associations, that can be included on the result (e.g. quickstats) via the `additional_data` query param.\n* `results` - The array of resource results  \n\n# Common Show Resource Functionality\nMost endpoints to retrieve a single resource, e.g. `GET /api/v1/demand_tags` allow to include associated resources on the result via the same `includes` query\nparamater as the List requests.  See the List response the resource for which associations are includable.\n"
servers:
- url: https://console.springserve.com/api/v1
  description: SpringServe console. Added by API Evangelist from the published documentation (springserve.atlassian.net/wiki/spaces/SSD/pages/1573617663/API+-+Getting+Started, "Base Url https://console.springserve.com/"); the document Magnite serves declares no servers[] block because the Swagger UI infers the host from window.location.
- url: https://console.clearline.magnite.com/api/v1
  description: ClearLine console. The identical contract is served from ClearLine's own host; base URL published at springserve.atlassian.net/wiki/spaces/CLD/pages/3649929217/Clearline+API+SDK.
security:
- api_key: []
- bearer_token: []
tags:
- name: Scheduled Reports
paths:
  /api/v1/scheduled_reports:
    get:
      tags:
      - Scheduled Reports
      summary: Index
      parameters:
      - in: query
        name: id
        schema:
          type: array
          items:
            type: integer
      - in: query
        name: page
        schema:
          type: integer
      - in: query
        name: per
        schema:
          type: integer
      - in: query
        name: sort
        schema:
          type: array
          items:
            type: string
      - in: query
        name: account_id
        schema:
          type: array
          items:
            type: integer
      - in: query
        name: user_account_id
        schema:
          type: array
          items:
            type: integer
      - in: query
        name: user_id
        schema:
          type: array
          items:
            type: integer
      - in: query
        name: is_active
        schema:
          type: array
          items:
            type: boolean
      - in: query
        name: search
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
      operationId: scheduled_reports_get
    post:
      tags:
      - Scheduled Reports
      summary: Create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/scheduledReport'
            examples:
              simple:
                $ref: '#/components/examples/scheduled_report_create_simple'
              full:
                $ref: '#/components/examples/scheduled_report_create_full'
      responses:
        '201':
          $ref: '#/components/responses/scheduledReport'
        '422':
          $ref: ref/errors.yaml#/components/responses/validationError
      operationId: scheduled_reports_post
  /api/v1/scheduled_reports/{id}:
    get:
      tags:
      - Scheduled Reports
      summary: Show
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          $ref: '#/components/responses/scheduledReport'
        '404':
          $ref: ref/errors.yaml#/components/responses/notFoundError
      operationId: scheduled_reports_id_get
    patch:
      tags:
      - Scheduled Reports
      summary: Update
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/scheduledReport'
            examples:
              simple:
                $ref: '#/components/examples/scheduled_report_update_simple'
              full:
                $ref: '#/components/examples/scheduled_report_update_full'
      responses:
        '200':
          $ref: '#/components/responses/scheduledReport'
      operationId: scheduled_reports_id_patch
    delete:
      tags:
      - Scheduled Reports
      summary: Delete
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: No content
      operationId: scheduled_reports_id_delete
  /api/v1/scheduled_reports/bulk_update:
    put:
      summary: Bulk Update
      requestBody:
        content:
          application/json:
            examples:
              single:
                $ref: '#/components/examples/scheduled_report_bulk_update_single'
              multiple:
                $ref: '#/components/examples/scheduled_report_bulk_update_multiple'
            schema:
              type: object
        required: true
      responses:
        '200':
          description: Bulk update completed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Status message describing the bulk update results
                examples:
                - message: 'Successfully updated 1 Scheduled Report: 1'
      tags:
      - Scheduled Reports
      operationId: scheduled_reports_bulk_update_same_attributes_put
components:
  schemas:
    partialUserAccount:
      type: object
      properties:
        id:
          type: integer
          examples:
          - 1
        user_id:
          type: integer
          examples:
          - 1
        user:
          readOnly: true
          allOf:
          - $ref: '#/components/schemas/partialUser'
        account_id:
          type: integer
          examples:
          - 1
    scheduledReport:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
          examples:
          - 1
        name:
          type: string
          examples:
          - Example Scheduled Report
        account_id:
          type: integer
          readOnly: true
          examples:
          - 1
        user_account_id:
          type: integer
          readOnly: true
          examples:
          - 1
        is_active:
          type: boolean
          default: true
        interval:
          type: string
          default: ad_hoc
          enum:
          - ad_hoc
          - daily
          - weekly
          - monthly
        message:
          type: string
        timezone:
          type: string
          examples:
          - UTC
        start_date:
          type: string
          examples:
          - '2025-01-01T00:00:00Z'
        end_date:
          type: string
          examples:
          - '2025-12-31T23:59:59Z'
        weekdays:
          type: array
          items:
            type: string
            enum:
            - Sunday
            - Monday
            - Tuesday
            - Wednesday
            - Thursday
            - Friday
            - Saturday
          default: []
        day_of_month:
          type: integer
          oneOf:
          - enum:
            - -1
          - type: integer
            exclusiveMinimum: 1
            exclusiveMaximum: 28
        hour:
          type: integer
        last_scheduled_success:
          type: string
          readOnly: true
        permissions:
          type: string
          enum:
          - attach_csv
          - link_sharing
          - require_login
          default: require_login
        created_at:
          type: string
          readOnly: true
        updated_at:
          type: string
          readOnly: true
        report_params:
          $ref: ref/reports.yaml#/components/schemas/reportParameters
        scheduled_report_recipients:
          type: array
          items:
            $ref: '#/components/schemas/scheduledReportRecipient'
        scheduled_report_external_recipients:
          description: '***NOTE:*** external recipients are automatically deleted from scheduled reports which have the "require_login" permission

            '
          type: array
          items:
            $ref: '#/components/schemas/scheduledReportExternalRecipient'
        user_account:
          readOnly: true
          allOf:
          - $ref: '#/components/schemas/partialUserAccount'
    partialUser:
      type: object
      properties:
        id:
          type: integer
          examples:
          - 1
        email:
          type: string
          examples:
          - example@example.com
        name:
          type:
          - string
          - 'null'
          examples:
          - Example User
    scheduledReportExternalRecipient:
      type: object
      properties:
        id:
          type: integer
        email:
          type: string
          examples:
          - example@example.com
        report_type:
          type: string
          enum:
          - supply_client
          - unrestricted
          default: supply_client
        created_at:
          type: string
          readOnly: true
        updated_at:
          type: string
          readOnly: true
      examples:
      - email: example@example.com
    scheduledReportRecipient:
      type: object
      properties:
        id:
          type: integer
        user_account_id:
          type: integer
        user_account:
          readOnly: true
          allOf:
          - $ref: '#/components/schemas/partialUserAccount'
        created_at:
          type: string
          readOnly: true
        updated_at:
          type: string
          readOnly: true
      examples:
      - user_account_id: 1
  examples:
    scheduled_report_bulk_update_multiple:
      summary: Multiple
      value:
        is_active: false
        object_ids:
        - 1
        - 2
    scheduled_report_update_full:
      summary: Full
      value:
        name: Scheduled Report Name
        is_active: true
        interval: monthly
        day_of_month: 1
        hour: 8
        timezone: America/New_York
        start_date: '2026-01-01'
        end_date: '2026-12-31'
        permissions: require_login
        message: Your scheduled report is ready.
        report_params:
          date_range: Yesterday
          interval: day
          timezone: Etc/UTC
          currency: USD
          dimensions:
          - supply_tag_id
          - demand_tag_id
          metrics:
          - impressions
          - revenue
          - fill_rate
          - cpm
        scheduled_report_recipients:
        - user_account_id: 1
        scheduled_report_external_recipients:
        - email: example@example.com
          report_type: supply_client
    scheduled_report_update_simple:
      summary: Simple
      value:
        name: Scheduled Report Name
        is_active: true
    scheduled_report_create_simple:
      summary: Simple
      value:
        name: Scheduled Report Name
        interval: daily
        start_date: '2026-10-01'
        hour: 8
        report_params:
          date_range: Yesterday
          dimensions:
          - supply_tag_id
          metrics:
          - impressions
          - revenue
    scheduled_report_bulk_update_single:
      summary: Single
      value:
        is_active: true
        object_ids:
        - 1
    scheduled_report_create_full:
      summary: Full
      value:
        name: Scheduled Report Name
        is_active: true
        interval: weekly
        weekdays:
        - Monday
        - Wednesday
        hour: 8
        timezone: America/New_York
        start_date: '2026-01-01'
        end_date: '2026-12-31'
        permissions: require_login
        message: Your scheduled report is ready.
        report_params:
          date_range: Yesterday
          interval: day
          timezone: Etc/UTC
          currency: USD
          dimensions:
          - supply_tag_id
          - demand_tag_id
          filters:
          - dimension: supply_tag_id
            type: values
            values:
            - 1
            is_include: true
            is_exact_match: false
          metrics:
          - impressions
          - revenue
          - fill_rate
          - cpm
        scheduled_report_recipients:
        - user_account_id: 1
        scheduled_report_external_recipients:
        - email: example@example.com
          report_type: supply_client
  responses:
    scheduledReport:
      description: A scheduled report
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/scheduledReport'
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: Authorization
      description: SpringServe authorization token based authentication.
    bearer_token:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: SpringServe authorization bearer token based authentication.  This key is included in the response from the /api/v0/auth and /api/v1/auth endpoints.  This key will be automatically set if you run the example for /api/v0/auth or /api/v1/auth
x-servers-added-by: https://apievangelist.com — not present in the upstream document; see openapi/_original/ for the verbatim spec.