reports

Generate the report and send it either through email or through an instant save file interface

Code
Parameters
----------
json_dict : dict
    The json_dict dict have the format
    ::
    {
        'reportName': 'Advance Premium',
        'searchParameters': '',
        'deliveryType': 'saveFile'
    }

call_sql_agent_service

Call SQL Agent Service with streaming response support

Check the status of a report process

Code
Parameters
----------
report_process_id : str
    The id of the report process to check

Returns
-------
success : bool
    True if successful, False if not
messages : list of str
    List of human-readable error messages
data : report process information

Complete a BriteData migration: archive source, save SQL report, mark completed.

Code
Order matters: the source BriteData report must be archived BEFORE
save_report runs, otherwise save_report's name-collision guard blocks
the new SQL report (it shares the source's name). The archive commits
independently via safe_commit so the source is durably hidden before
save_report runs.

Step 1 (archive source) commits independently via safe_commit().
Step 2 (save_report) commits independently via its own safe_commit().
Step 3 (mark migration completed) flushes only - committed by the
@api_request decorator at end of request.

If step 2 fails after step 1 succeeded, the archive is rolled back
via ``restore_source_report`` (rename back to original, ``hidden=False``)
and an error is returned. Without that rollback the source would
remain renamed + hidden even though no replacement was saved -- the
user would lose the working source on every validation / permission
/ SQL error.

If step 3 fails after steps 1+2 succeed, the new SQL report id is
persisted on the migration row via ``attach_sql_report`` + an
independent ``safe_commit`` immediately after step 2 so a retry is
deterministic: the next ``complete_britedata_migration`` call detects
the persisted ``sql_report_id`` and resumes from step 3 (mark
completed) without re-running archive or ``save_report``. Without
this durable link, retry would call ``save_report`` again and hit
its name-collision guard on the archived source's reused name.

Idempotent resume paths:
  * ``status=completed`` AND ``sql_report_id`` set
    -> returns ``retrieve_report(sql_report_id)`` directly with no
      mutation (whole completion was already done).
  * ``sql_report_id`` set but ``status != completed``
    -> skips steps 1+2 and only runs step 3 against the persisted
      ``sql_report_id``.

Parameters
----------
id : str
    Migration record UUID (POST body). Required.
report : dict
    Report data in save_report format (POST body). Required.
migration_summary : str
    Agent Changes Summary text (POST body). Optional.

Returns
-------
standard_response payload for the new SQL Editor report (retrieve_report
shape), or standard_error on validation/lookup/save failure.

POST /api/v2/reports/create_report_cadence

Code
Body: { report_id, cadence }

Parameters
----------
report_id : str
cadence : str
    One of the report cadences (daily, weekly, monthly, ...).

Returns
-------
success : bool
messages : list of str
data : dict
    {cadence: {...}, legacy_run_when_retired: bool}

Creates a new Report Category

Code
Parameters
----------
category_name : str
    The name of the new Report Category

Returns
-------
success : bool
    True if successful, false if not
messages : list of str
    List of human-readable error messages
data : dict
    The data response having the form:
    ::

        {
            'id': 'Some UUID id',
            'name': 'Category Name'
        }

POST a new parameter set onto a cadence.

Code
Parameters
----------
report_id : str
cadence_id : str
parameter_overrides : dict
    Keyed by declared parameter name; each value is
    {type: literal|sql_expression, value: <any>}.
position : int, optional
    Defaults to the next free position on the cadence.
name : str, optional
    Defaults to "Schedule <position>".

Returns
-------
success : bool
messages : list of str
data : dict
    The created schedule.

Get a preview of the selected dataframe

Code
Parameters
----------
df_name : str
    the name of the dataframe
numberOfRows : int
    The number of rows to take from head of dataframe for sample
prepared : boolean
    Indicated if this dataframe is a prepared dataframe (defaults to false)

Returns
-------
success : bool
    True if successful, False if not
messages : list of str
    List of human-readable error messages
data : dict with dataframe preview

Deletes file from File table

Code
Parameters
----------
report_id : str, required
    UUID of the report associated with the file
file_id : str, required
    UUID of the file wishing to delete

Returns
-------
success : bool
    True if successful, False if not
messages : list of str
    List of human-readable error messages
data : dict of File deleted

Deletes an existing Report

Code
Parameters
----------
report_id : str, required
    The UUID of the existing Report

Returns
-------
success : bool
    True if successful, false if not
messages : list of str
    List of human-readable error messages

DELETE a cadence and the schedules that fire on it.

Code
Parameters
----------
report_id : str
cadence_id : str

Returns
-------
success : bool
messages : list of str
data : dict
    {deleted: str}

Deletes an existing Report Category

Code
Parameters
----------
category_id : str, required
    The UUID of the existing Report Category

Returns
-------
success : bool
    True if successful, false if not
messages : list of str
    List of human-readable error messages

DELETE one schedule, unless it is the cadence's last one.

Code
Parameters
----------
report_id : str
cadence_id : str
schedule_id : str

Returns
-------
success : bool
messages : list of str
data : dict
    {deleted: str}

Count the schedules and export settings a duplicate could inherit

Code
Backs the Duplicate dialog's checkboxes.

Parameters
----------
report_id : str
    The id of the report to inspect

Returns
-------
success : bool
    True if successful, False if not
messages : list of str
    List of human-readable error messages
data : dict
    ``{'cadences': int, 'schedules': int, 'has_export_options': bool,
    'has_delivery_password': bool, 'has_custom_permissions': bool}``

Download a report file

Code
Parameters
----------
file_id : str
    The id of the file to download
as_url : bool
    Answer with a presigned S3 url in the body instead of a redirect to it.
    Browsers need this: fetch() follows a redirect as a cross-origin request
    and the storage buckets have no CORS configuration.

Returns
-------
A 303 to the report file, or - with as_url - a standard response carrying
download_url and filename.

Duplicate a SQL Runner report as a new draft

Code
Sheets, parameters and documentation always travel with the copy.
Permissions, run history and the category never do: the copy lands in the
draft category.

Parameters
----------
report_id : str
    The id of the report to duplicate
copy_schedules : bool, optional
    Recreate the cadences and schedules, all disabled. Defaults to False.
copy_export_options : bool, optional
    Carry the delivery settings at report and schedule level. The stored
    password comes along only when the source has no permission rows of
    its own. Defaults to False.

Returns
-------
success : bool
    True if successful, False if not
messages : list of str
    List of human-readable error messages
data : dict
    ``{'id': ..., 'name': ..., 'cadences_copied': int,
    'schedules_copied': int, 'export_options_copied': bool,
    'password_copied': bool}``

Export a single report's definition as a downloadable JSON file

Code
On success the response body is the report definition JSON, served as a
file download (``Content-Type: application/json`` and
``Content-Disposition: attachment; filename="<report name>.json"``) so it
can be saved and later fed to :func:`import_report`. The database-managed
report id is stripped so the payload can be recreated in any environment,
and the report's category is emitted by name (``category_name``) rather
than a non-portable ``category_id``. Errors return the standard
``standard_error`` envelope.

The file is written for another environment, so it always records the
report as a draft (``draft`` and the "Draft (Unpublished)" category) and
never carries a delivery password.

Parameters
----------
report_id : str
    The id of the report to export

Returns
-------
file : application/json
    A downloadable JSON file (the report definition), having the form:
    ::

        {
            'name': 'Report Name',
            'description': 'Report Description',
            'report_runner': 'sql_runner',
            'custom': True,
            'draft': True,                     # always, see above
            'date_type': 'single',
            'output_format': 'excel',
            'output_file_delimiter': ',',
            'category_name': 'Draft (Unpublished)',
            'report_parameters': [...],
            'export_options': {...},           # never carries a password
            'additional_report_settings': {...},
            'report_sheets': [
                {
                    'name': 'Sheet 1',
                    'order': 0,
                    'sql_query': 'SELECT * FROM v_some_view',
                    'formatting': {...},
                },
            ],
        }

Get the prepared.yml file

Code
Parameters
----------

Returns
-------
success : bool
    True if successful, False if not
messages : list of str
    List of human-readable error messages
data : dict with yaml information

Code
Generate the Consolidated Declaration Statements
@policy_group: The policy group to generate the Consolidated Declaration Statements for

Returns full migration record with YAML, conversion map, and date type.

Code
Parameters
----------
id : str
    Migration record UUID (query param).

Returns
-------
success : bool
messages : list
data : dict
    Full migration record including yaml, template, conversion_map,
    conversion_map_confidence_score, conversion_map_confidence_score_reason,
    date_type, report_name.

Retrieves documentation for a single report or all reports

Code
Parameters
----------
report_id : str, optional
    The id of the report to get documentation for

Returns
-------
success : bool
    True if successful, False if not
messages : list of str
    List of human-readable error messages
data : dict or list
    Single report documentation or list of all reports documentation

List past executions of a single report, newest first, paginated.

Code
Backs the Reports Run tab's "load more past executions".

Parameters
----------
report_id : str
    The id of the report whose executions to list.
limit : int, optional
    Page size (default 10, capped at 50).
offset : int, optional
    Number of rows to skip (default 0).

Returns
-------
success : bool
messages : list of str
data : dict
    {executions: [...], total: int, limit: int, offset: int, hasMore: bool}

Get report versions for a specific report

Code
Parameters
----------
report_id : str, required
    The UUID of the report to get versions for

Returns
-------
success : bool
    True if successful, False if not
messages : list of str
    List of human-readable error messages
data : list
    List of report versions with their information
    ::
    [
        {
            'id': 'version UUID',
            'version_number': '1.0.0',
            'version_hash': 'hash string',
            'change_log': {...},  # JSON object with change information
            'date_deployed': '2023-10-07T10:30:00Z'
        }
    ]

Gets authentication token from S3 Gateway for DF and PDF retrieval. S3 Gateway is a service that allows restricted access to S3 assets.

Code
This call will return an Authentication key used for making calls to
S3 Gateway. The Authentication key will be restricted to dataframes
for the client associated with the login.
`NOTE: Only users with roles of Admin or Vendor can receive a S3 Auth key`

Parameters
----------

Returns
-------
success : bool
    True if successful, False if not

messages : list of str
    List of human-readable error messages

data : dict
    Authentication key and expiration time
    ::
    {
        'client': 'Client Name',
        'expires': 'UTC Time',
        'key': 'UUID Authentication key'
    }

Per-cadence completion status of scheduled reports (config vs actual).

Code
Answers "did my scheduled reports finish?" operationally: each report
configured for a cadence is classified against that cadence's latest
run-batch as Completed, Failure, Running or Not started.

Returns
-------
success : bool
messages : list of str
data : dict
    {cadences: [{cadence, setProcessId, lastRunAt, total, completed, failed,
                 running, notStarted,
                 reports: [{reportId, reportName, status, finishedAt,
                            fileId, error}]}]}
    Only cadences with at least one configured (and readable) report appear.

Create or update a report permission grant.

Code
Parameters
----------
report_id : str
    The id of the report (JSON body).
grantee_type : str
    One of contact, user_group, role, permission_level (JSON body).
grantee_id : str
    The id of the grantee (JSON body).
access : str
    One of none, read, write (JSON body).

Returns
-------
str
    JSON with success, messages, and data containing the saved permission.

Import a report definition, creating a new report

Code
Thin API layer: resolves the payload, deserializes it to a ``ReportExport``
domain object, hands it to ``ReportDefinitionService`` to validate and
persist, then serializes the created report (response built with
``standard_response`` / ``standard_error``). Accepts the definition as
``report_data`` (a dict or JSON string) or as ``file_data`` (the JSON text
of an exported file, mirroring ``import_line``), in the shape produced by
:func:`export_report`, and persists it as a **new** report. Any id carried
in the payload is ignored so an import always creates a fresh report, and
the report is marked ``custom`` so it stays editable. For ``sql_runner``
reports each sheet's SQL is validated before the report is written.

Importing fails if a report with the same ``name`` already exists -- the
caller must rename the incoming report (or rename/delete the existing one)
before retrying.

Parameters
----------
report_data : dict, optional
    The report definition to import (dict or JSON string). ``category_name``
    (optional) is resolved to a category in the target environment, creating
    it when it
    does not yet exist.
    ::

        {
            'name': 'Report Name',
            'description': 'Report Description',
            'output_format': 'excel',
            'date_type': 'single',
            'category_name': 'Category Name',
            'report_parameters': [...],
            'export_options': {...},
            'report_sheets': [
                {
                    'name': 'Sheet 1',
                    'order': 0,
                    'sql_query': 'SELECT * FROM v_some_view',
                },
            ],
        }
file_data : str, optional
    The JSON text of an exported report file (or base64 of it), following
    the ``file_data`` convention used by ``import_line``. Takes precedence
    over ``report_data``.
costGateOverrideReason, cost_gate_override_reason : str, optional
    Reason for overriding blocking SQL cost rules other than P19 (either
    spelling). Honoured for users with report permission admin rights and
    recorded in the new report's notes. A blocked import that an override
    would clear returns ``data={'costGateOverridable': True, 'rules': [...]}``.

Returns
-------
success : bool
    True if successful, False if not
messages : list of str
    List of human-readable error messages
data : dict
    The created report definition (same shape as :func:`export_report`)

Every schedule on the site, one row each

Code
Backs the Schedules page. A row is a schedule, since that is the thing a
person edits; a cadence with no schedule row of its own still fires and
contributes one row. Reports the caller cannot read are filtered out.

Returns
-------
success : bool
    True if successful, False if not
messages : list of str
    List of human-readable error messages
data : dict
    ``{'schedules': [{report_id, report_name, category_name, cadence_id,
    cadence, cadence_enabled, schedule_id, schedule_name, enabled,
    parameter_overrides, export_label, export_inherited, next_run}]}``

Returns BriteData migration rows for the current carrier.

Code
Includes every row with status pending or in_progress, whether or not it can
be migrated, so the UI can show the rest disabled with ``unsupported_reason``
(tooltip). ``migration_supported`` is true when the report's saved YAML parses,
which is what the migration agent reads; the tier is reported for display and is
not a gate. The SQL Editor should show the Migrate button only when
``has_eligible_migration`` is true.

When the migration feature is disabled (Setting
``reports.enable-britedata-migration`` is false), returns an empty list
with ``has_eligible_migration=False`` so the UI hides the Migrate button
gracefully without surfacing an error.

Returns
-------
success : bool
messages : list
data : dict
    {'migrations': [...], 'has_eligible_migration': bool}

    Each migration item includes:
    id, report_name, category_name, status, tier,
    conversion_map_confidence_score, date_type,
    migration_supported, unsupported_reason (null when supported).

Retrieves a list of df_cache files Parameters ---------- prefix : str Prefix of the files. Usually a date in YYYYMMDD format auth_token : str S3 authentication token prepared : bool, optional Get prepared df_cache files Returns ------- success : bool True if successful, False if not messages : dict List of error messages data : dict { 'files': [ { 'url': '...', #download link for file 'expired': '2014-09-08T08:02:17.127178', #expiration of url (ISO 8601) 'id': '...' #unique (in line) id for the file }, ] }

Returns list of all prepared, non prepared and facts dfs.

Code
parameters
----------

Returns
-------
success : bool
    True if successful, False if not
messages : dict
    List of error messages
data : dict
    {
        'prepared': [..],
        'nonprepared': [..],
        'facts': [..]
    }

Report files waiting in the Export Queue, newest first

Code
Backs the Export page. Files of reports the caller cannot read are left out.

Returns
-------
data : dict
    ``{'files': [{id, report_id, report_name, file, date, queued_at,
    method, method_key}]}``

Get list of files associated with report

Code
Parameters
----------
report_id : str, required
    UUID of the report associated with the file


Returns
-------
success : bool
    True if successful, False if not
messages : list of str
    List of human-readable error messages
data : list of related files

List grantee id and name options for the permissions picker.

Code
Parameters
----------
grantee_type : str
    One of contact, user_group, role, permission_level (JSON body).

Returns
-------
str
    JSON with success, messages, and data as a list of id/name objects.

GET /api/v2/reports/list_report_cadences?report_id=...

Code
Returns the report's cadences and the schedules that fire on each.

Parameters
----------
report_id : str

Returns
-------
success : bool
messages : list of str
data : dict
    {cadences: [{id, report_id, cadence, enabled, date_added, date_updated,
                 next_run, schedules: [...]}]}

List report permission rows and whether the user can edit them.

Code
Parameters
----------
report_id : str
    The id of the report (JSON body).

Returns
-------
str
    JSON with success, messages, and data containing permissions and can_write.

Export the selected queued files

Code
With Celery on, the export runs in the background and a second run within
15 minutes is refused.

Parameters
----------
file_ids : list of str
    ``files.id`` of the queued files (JSON body).

Take one file off the Export Queue without exporting it

Code
Parameters
----------
file_id : str
    ``files.id`` of the queued file (JSON body).

Renames an existing Report Category

Code
Parameters
----------
category_id : str, required
    The UUID of the existing Report Category
category_name : str, required
    The new name of the new Report Category

Returns
-------
success : bool
    True if successful, false if not
messages : list of str
    List of human-readable error messages
data : dict
    The data response having the form:
    ::

        {
            'id': 'Some UUID id',
            'name': 'Category Name'
        }

Discard an in-progress migration's saved draft and reset it to pending. Lets a user start a report's migration over from scratch instead of resuming the previously-saved (possibly stale) agent draft.

Code
Completed migrations cannot be reset here; the service raises and this
returns an error response.

Gated the same way as the other per-record migration endpoints:
``@report_permission_required(WRITE_ACCESS)`` against the source
BriteData report's ACL, plus the ``reports.enable-britedata-migration``
feature Setting.

Parameters
----------
id : str
    Migration record UUID (POST body param). Required.

Returns
-------
success : bool
messages : list
data : dict
    {'status': 'ok'} on success.

Retrieves a single report's full definition

Code
Parameters
----------
report_id : str
    The id of the report to retrieve

Returns
-------
success : bool
    True if successful, False if not
messages : list of str
    List of human-readable error messages
data : dict with report information

Retrieves all available Report Categories

Code
Parameters
----------

Returns
-------
success : bool
    True if successful, False if not
messages : list of str
    List of human-readable error messages
data : dict with report categories

Retrieves the cleaned exception text for a failed report's background job.

Code
Parameters
----------
job_id : str, required
    ``background_jobs.id`` for export-style rows, or ``report_processes.id``
    when the UI passes the process primary key (report-status ``jobId``).

Returns
-------
success : bool
messages : list of str
data : str
    ASCII-cleaned exception text, or an empty string.

Retrieves report processes from the past N hours

Code
Parameters
----------
hours : int, optional
    Number of hours to look back for report processes (default: 24)

Returns
-------
success : bool
    True if successful, false if not
messages : list of str
    List of human-readable error messages
data : dict
    The data response having the form:
    ::

        {
            'report_processes': [
                {
                    'id': 'Process UUID',
                    'parent_process_id': 'Parent Process UUID',
                    'report_id': 'Report UUID',
                    'report_name': 'Report Name',
                    'file_id': 'File UUID',
                    'report_start_date': 'MM/DD/YYYY',
                    'report_end_date': 'MM/DD/YYYY',
                    'started_at': 'MM/DD/YYYY HH:MM:SS',
                    'finished_at': 'MM/DD/YYYY HH:MM:SS',
                    'export_status': 'status',
                    'execution_step': 'step',
                    'execution_updated_at': 'MM/DD/YYYY HH:MM:SS',
                    'error_code': 'error code',
                    'error_message': 'error message',
                    'status': 'Running/Succeeded/Failed',
                    'duration': seconds,
                    'download_link': 'URL or None',
                    'additional_report_configuration': {...},
                    'report_parameters': {...}
                },
            ]
        }

Retrieves all available Reports, grouped in their Report Categories

Code
Parameters
----------

Returns
-------
success : bool
    True if successful, false if not
messages : list of str
    List of human-readable error messages
data : dict
    The data response having the form:
    ::

        {
            'report_categories': [
                {
                    'name': 'Category Name', 'id': 'Category UUID',
                    'reports': [
                        {
                            'name': 'Report Name', 'id': 'Report UUID',
                            'category_id': 'Parent Category UUID',
                            'description': 'Markdown Lite Description',
                            'output_format': 'xls, xml, csv, etc.',
                            'css': 'Custom CSS',
                            'yaml': {...}, # complex BriteData report YAML, in JSON format
                            'template': 'BriteData report template',
                            'custom': bool, # true if created by a user
                            'date_type': 'single/range',
                            'legacy': bool, # true if this is NOT a BriteData report
                            'run_when': 'manual, daily, weekly, monthly, or annually',
                            'cadences': ['daily', ...], # enabled SQL Runner cadences
                            'custom_start_date': 'MM/DD/YYYY',
                            'export_options': {...} # complex custom export options,
                        },
                    ]
                },
            ]
        }

Retrieves all available SQL Reports

Code
Parameters
----------

Returns
-------
success : bool
    True if successful, False if not
messages : list of str
    List of human-readable error messages
data : dict with sql reports

Remove a report permission grant.

Code
Parameters
----------
report_id : str
    The id of the report (JSON body).
grantee_type : str
    One of contact, user_group, role, permission_level (JSON body).
grantee_id : str
    The id of the grantee to revoke (JSON body).

Returns
-------
str
    JSON with success, messages, and empty data on success.

Start running a report and get the report process id

Code
Parameters
----------
report_name : str
    The name of the report to run
end_date : str, optional
    The end date or as of date of the report (supports yyyy-mm-dd, mm/dd/yyyy formats)
start_date : str, optional
    The start date of the report for range reports (supports yyyy-mm-dd, mm/dd/yyyy formats)
additional_report_configuration : dict, optional
    Additional report configuration to pass to reports that support it.
    Can include a 'parameters' key containing parameter VALUES for SQL queries.
    Parameter values must be provided as plain values (strings, numbers, dates).

    Example:
    {
        "parameters": [
            {"name": "CustomDate", "value": "06/13/2024"},
            {"name": "AnotherDate", "value": "2024-06-13"},
            {"name": "today", "value": "2024-06-13T17:19:05.183Z"},
            {"name": "status", "value": "active"}
        ]
    }

    Parameters with defaults:
    - If a parameter is not provided but has a default value defined in the report,
      the default will be used automatically.
    - SQL expression defaults (e.g., CURDATE()) are evaluated server-side.

    Standard parameters provided automatically:
    - RunDateTime: current execution timestamp (always available)

Returns
-------
success : bool
    True if successful, False if not
messages : list of str
    List of human-readable error messages
data : dict with report process id to pass to check_report_process_status

Persist the most recent agent-generated report_json for a migration.

Code
Called by the SQL Editor after the migration agent emits a fresh
``report_json`` fence (initial response and every follow-up iteration).
The persisted draft is returned by ``start_britedata_migration`` on the
next Resume so the user does not have to re-run the agent.

Parameters
----------
id : str
    Migration record UUID (POST body param). Required.
draft_report_json : str
    JSON-serialized report payload. Empty / null clears the draft.

Returns
-------
success : bool
messages : list
data : dict
    {'status': 'ok'} on success.

Saves a new or updates existing report

Code
Parameters
----------
report_data : dict
    The report data to save
    ::
        {
            'id': 'Report ID', # when updating an existing report
            'name': 'Report Name',
            'description': 'Report Description',
            'output_format': 'xlsx, csv',
            'custom': bool, # true if created by a user
            'date_type': 'single/range',
            'report_parameters': [  # optional, list of parameter definitions
                {
                    'name': 'creationTimestamp',
                    'type': 'DateTime',
                    'extra_info': {
                        'default_value': 'NOW()',  # SQL expression default
                        'default_value_type': 'sql_expression'  # 'sql_expression' or omit for static values
                    }
                },
                {
                    'name': 'reportDate',
                    'type': 'Date',
                    'extra_info': {
                        'default_value': 'CURDATE()',
                        'default_value_type': 'sql_expression'
                    }
                },
                {
                    'name': 'status',
                    'type': 'String',
                    'extra_info': {}
                },
                {
                    'name': 'amount',
                    'type': 'Number',
                    'extra_info': {}
                },
                {
                    'name': 'category',
                    'type': 'Enum',
                    'extra_info': {
                        'enumOptions': [
                            {'text': 'Active', 'value': 'Active'},
                            {'text': 'Inactive', 'value': 'Inactive'},
                            {'text': 'Pending', 'value': 'Pending'}
                        ],
                        'default_value': 'Active'  # static default (no default_value_type)
                    }
                }
            ],
            'export_options': {
                'filename': 'Output File Name.xlsx',
            },
            'report_sheets': [
                {
                    'name': 'Sheet Name',
                    'order': 0,
                    'sql_query': 'SELECT * FROM v_some_view',
                    'include_totals_row': False,
                    'formatting': {
                        'column_name': {
                            'type': 'type_string',
                        }
                    }
                },
            ]
        }

Returns
-------
success : bool
    True if successful, False if not
messages : list of str or dict
    List of human-readable error messages. On success, SQL cost rule
    warnings come back as ``{'_warning_': [...]}``.
data : dict with report information

``report_data`` may carry ``costGateOverrideReason`` (or ``cost_gate_override_reason``)
to override blocking SQL cost rules other than P19; it is honoured for users with
report permission admin rights and recorded in the report's notes. A blocked
save that an override would clear returns ``data={'costGateOverridable': True,
'rules': [...]}``.

send_prompt

Sets a migration record status to in_progress.

Code
Re-entry policy:
- If already in_progress: 200 OK, returns current record.
- If completed: returns error response.

If the migration has a persisted ``draft_report_json`` from a previous
agent run, it is returned alongside the status. The frontend uses this
to skip the agent invocation on Resume and load the draft directly into
the SQL Editor.

Parameters
----------
id : str
    Migration record UUID (POST body param).

Returns
-------
success : bool
messages : list
data : dict
    {'status': str, 'draft_report_json': str | None}

PATCH a cadence's enabled flag.

Code
Per-schedule export options live on update_report_schedule; this endpoint
does not accept them.

Parameters
----------
report_id : str
cadence_id : str
enabled : bool, optional

Returns
-------
success : bool
messages : list of str
data : dict
    {id, enabled}

PATCH a report's default export options.

Code
Unlike save_report this does not reject stock reports: export options are
per-tenant delivery configuration, not part of the stock report definition.
Sentinel semantics match update_report_schedule.

Parameters
----------
report_id : str
export_options : dict or None, optional

Returns
-------
success : bool
messages : list of str
data : dict
    {id, export_options}

PATCH a schedule's parameter overrides, position, name, enabled flag and/or export options.

Code
`export_options` is three-state: omit it to leave the column alone, pass
None to clear the override (the schedule then inherits
Report.export_options), or pass a dict to set it. Protected fields
(password) round-trip through a sentinel so clients can echo back the
redacted value without losing the stored one.

Parameters
----------
report_id : str
cadence_id : str
schedule_id : str
parameter_overrides : dict, optional
position : int, optional
enabled : bool, optional
name : str, optional
export_options : dict or None, optional

Returns
-------
success : bool
messages : list of str
data : dict
    The updated schedule.

Uploads file in Files table and stores to S3

Code
Parameters
----------
report_id : str, required
    UUID of the report uploading files for
title : str, required
    Title of the file being uploaded
data : basestring, required
    Base64-encoded of the file
kwargs : dict, optional
    Additional parameters in file creation. Must be
    valid args. See File model for full list of properties.
    ::
        {
            'reference_id': 'Some UUID'
        }

Returns
-------
success : bool
    True if successful, False if not
messages : list of str
    List of human-readable error messages
data : dict of new File model