clariBI

{'type': 'object', 'required': ['handoff_id'], 'properties': {'handoff_id': {'type': 'string', 'format': 'uuid', 'description': 'The id returned by request_oauth_integration_url.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['handoff_id', 'provider', 'integration_type', 'status'], 'properties': {'error': {'type': ['string', 'null'], 'description': 'Failure reason when status is "failed".'}, 'status': {'type': 'string', 'description': 'One of pending, connected, failed, expired.'}, 'provider': {'type': 'string'}, 'created_at': {'type': ['string', 'null'], 'format': 'date-time'}, 'handoff_id': {'type': 'string', 'format': 'uuid'}, 'completed_at': {'type': ['string', 'null'], 'format': 'date-time'}, 'connection_id': {'type': ['string', 'null']}, 'data_source_id': {'type': ['string', 'null'], 'description': 'The created data source, present once status is "connected".'}, 'integration_type': {'type': 'string'}}}

{'type': 'object', 'properties': {'tier': {'type': 'string', 'description': 'Optional. Return only this tier (free, trial, lite, starter, professional, enterprise).'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['currency', 'tiers', 'billing_url'], 'properties': {'tiers': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'name', 'price_monthly_usd', 'price_yearly_usd'], 'properties': {'id': {'type': 'string'}, 'name': {'type': 'string', 'description': 'Display name of the tier.'}, 'max_users': {'type': 'integer'}, 'ai_credits': {'type': 'integer'}, 'storage_gb': {'type': 'number'}, 'data_sources': {'type': 'integer'}, 'duration_days': {'type': 'integer', 'description': 'Trial length in days; 0 for paid tiers.'}, 'price_yearly_usd': {'type': 'number'}, 'headline_features': {'type': 'array', 'items': {'type': 'string'}}, 'price_monthly_usd': {'type': 'number'}}}}, 'currency': {'type': 'string', 'description': 'ISO currency code, always "USD".'}, 'billing_url': {'type': 'string', 'format': 'uri'}}}

{'type': 'object', 'required': ['tier'], 'properties': {'tier': {'enum': ['starter', 'professional', 'enterprise'], 'type': 'string', 'description': 'Target subscription tier.'}, 'billing_period': {'enum': ['monthly', 'yearly'], 'type': 'string', 'default': 'monthly', 'description': 'Billing cadence for the checkout. Defaults to monthly.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['checkout_url', 'session_id', 'tier', 'billing_period'], 'properties': {'tier': {'type': 'string'}, 'session_id': {'type': 'string', 'description': 'Stripe Checkout Session id.'}, 'checkout_url': {'type': 'string', 'format': 'uri', 'description': 'Stripe Checkout URL. Open in a browser to complete payment.'}, 'billing_period': {'type': 'string', 'description': 'monthly or yearly.'}}}

{'type': 'object', 'required': ['name', 'source_type', 'source_id', 'metric_path'], 'properties': {'name': {'type': 'string', 'maxLength': 255, 'minLength': 1}, 'source_id': {'type': 'string', 'description': 'UUID of the report, dashboard, goal, or data source.'}, 'transform': {'enum': ['auto', 'none', 'log'], 'type': 'string', 'default': 'auto', 'description': 'Series transform applied before fitting. Log helps revenue/traffic series with growing variance. Auto detects when log is beneficial; none forces raw scale.'}, 'aggregation': {'enum': ['auto', 'sum', 'mean', 'last', 'max'], 'type': 'string', 'default': 'auto', 'description': 'How multiple raw points falling into the same bucket are combined. Auto picks sum for additive metrics, mean otherwise. Use Mean for rates (CTR, conversion, latency).'}, 'description': {'type': 'string', 'maxLength': 5000}, 'granularity': {'enum': ['hourly', 'daily', 'weekly', 'monthly', 'quarterly', 'annual'], 'type': 'string', 'default': 'daily', 'description': 'Bucket size for the time series. Hourly requires an hourly data source; the engine refuses to fabricate hourly buckets from daily data.'}, 'metric_path': {'type': 'string', 'description': 'Dot-path to the numeric column. For data_source: the metric key (e.g. "revenue"). For goal: "value" or "percentage". For report: the path inside the insights JSON. For dashboard: "widget_id:metric_name".'}, 'source_type': {'enum': ['report', 'dashboard', 'goal', 'data_source'], 'type': 'string', 'description': 'Which clariBI artifact the metric lives on. Most callers should start with data_source for raw connector metrics or goal to forecast a tracked KPI.'}, 'horizon_days': {'type': 'integer', 'default': 30, 'maximum': 168, 'minimum': 1, 'description': 'How many BUCKETS ahead to project. The per-granularity cap applies: hourly 168, daily 90, weekly 52, monthly 24, quarterly 8, annual 5. The field name is "_days" for backwards compatibility — it counts buckets of the chosen granularity.'}, 'non_negative': {'type': 'boolean', 'description': 'When true, point + lower band clamped at zero. Omit to let the engine heuristic decide (via non_negative_auto=true).'}, 'method_override': {'type': 'string', 'maxLength': 40, 'description': 'Force a specific forecasting method instead of auto-selecting via walk-forward CV. Valid names: naive, seasonal_naive, moving_average, drift, linear_trend, ar_p, holt_winters, holt_winters_multiplicative, holt_winters_damped, theta, gradient_boost, ensemble_top3. Empty = auto.'}, 'include_anomalies': {'type': 'boolean', 'default': True}, 'narration_enabled': {'type': 'boolean', 'default': True, 'description': 'When true, every completed run gets an AI-generated narrative attached (summary, highlights, risks, recommendations, methodology). Costs 1-2 extra AI credits per run.'}, 'non_negative_auto': {'type': 'boolean', 'default': True, 'description': 'When true (default), the backend heuristic owns non_negative and re-evaluates per run based on the metric path. Set false alongside non_negative to lock the choice.'}, 'schedule_frequency': {'enum': ['daily', 'weekly', 'monthly', 'manual'], 'type': 'string', 'default': 'monthly', 'description': 'How often the forecast re-runs. Manual schedules only run when called explicitly via run_forecast.'}, 'include_changepoints': {'type': 'boolean', 'default': True}, 'include_correlations': {'type': 'boolean', 'default': True}, 'schedule_day_of_week': {'type': 'integer', 'maximum': 6, 'minimum': 0}, 'schedule_day_of_month': {'type': 'integer', 'maximum': 31, 'minimum': 1}}, 'additionalProperties': False}

{'type': 'object', 'required': ['id', 'name', 'horizon_days', 'web_url'], 'properties': {'id': {'type': 'string', 'format': 'uuid'}, 'name': {'type': 'string'}, 'web_url': {'type': 'string', 'format': 'uri'}, 'granularity': {'type': 'string'}, 'next_run_at': {'type': ['string', 'null'], 'format': 'date-time'}, 'horizon_days': {'type': 'integer'}, 'metric_label': {'type': 'string'}, 'schedule_frequency': {'type': 'string'}}}

{'type': 'object', 'required': ['title'], 'properties': {'title': {'type': 'string', 'maxLength': 200, 'minLength': 2, 'description': 'Display title for the generated report.'}, 'template_id': {'type': 'string', 'description': 'Optional registry ID of the marketplace template to render. If omitted, an empty report shell is created and you can attach a template later from the web app.'}, 'output_format': {'enum': ['json', 'pdf', 'html', 'excel', 'csv'], 'type': 'string', 'default': 'pdf', 'description': 'Output format. Must match one of ``GeneratedReport.OUTPUT_FORMATS``.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['report_id', 'status', 'web_url'], 'properties': {'status': {'type': 'string', 'description': 'Initial status, normally "pending". Poll get_report for progress.'}, 'web_url': {'type': 'string', 'format': 'uri'}, 'report_id': {'type': 'string', 'format': 'uuid'}}}

{'type': 'object', 'required': ['job_id'], 'properties': {'job_id': {'type': 'string', 'format': 'uuid', 'description': 'job_id returned by a prior run_analysis call.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['job_id', 'status', 'current_step', 'progress'], 'properties': {'error': {'type': 'string', 'description': 'Failure reason. Present when status is "failed".'}, 'job_id': {'type': 'string', 'format': 'uuid'}, 'result': {'type': 'object', 'description': 'Analysis envelope. Present when status is "completed".'}, 'status': {'type': 'string'}, 'progress': {'type': 'number', 'description': 'Completion fraction or percentage reported by the job.'}, 'current_step': {'type': 'string'}}}

{'type': 'object', 'properties': {}, 'additionalProperties': False}

{'type': 'object', 'required': ['subscription_tier', 'subscription_status', 'price_monthly_usd', 'price_yearly_usd', 'billing_url'], 'properties': {'billing_url': {'type': 'string', 'format': 'uri'}, 'trial_ends_at': {'type': ['string', 'null'], 'format': 'date-time'}, 'price_yearly_usd': {'type': 'number'}, 'price_monthly_usd': {'type': 'number'}, 'subscription_tier': {'type': 'string'}, 'subscription_status': {'type': 'string'}}}

{'type': 'object', 'required': ['dashboard_id'], 'properties': {'dashboard_id': {'type': 'string', 'format': 'uuid', 'description': 'UUID of the dashboard to fetch.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['id', 'name', 'status', 'web_url', 'is_public'], 'properties': {'id': {'type': 'string', 'format': 'uuid'}, 'name': {'type': 'string'}, 'status': {'type': 'string', 'description': 'Dashboard lifecycle status.'}, 'web_url': {'type': 'string', 'format': 'uri'}, 'is_public': {'type': 'boolean'}, 'created_at': {'type': ['string', 'null'], 'format': 'date-time'}, 'updated_at': {'type': ['string', 'null'], 'format': 'date-time'}, 'description': {'type': 'string'}, 'last_refresh': {'type': ['string', 'null'], 'format': 'date-time'}, 'configuration': {'type': 'object', 'description': 'Dashboard layout and widget configuration.'}, 'analysis_metadata': {'type': 'object', 'description': 'AnalysisEngine envelope captured when the dashboard was created.'}}}

{'type': 'object', 'required': ['data_source_id'], 'properties': {'data_source_id': {'type': 'string', 'format': 'uuid', 'description': 'UUID of the data source to fetch the schema for.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['id', 'name', 'source_type', 'status', 'schema'], 'properties': {'id': {'type': 'string', 'format': 'uuid'}, 'name': {'type': 'string'}, 'schema': {'type': 'object', 'description': 'Schema-shaped fields the preprocessing pipeline wrote into the source metadata (columns, column_types, sample_rows, row_count, ...). Empty until preprocessing has run or for source types with no column inventory.'}, 'status': {'type': 'string'}, 'source_type': {'type': 'string'}, 'last_sync_at': {'type': ['string', 'null'], 'format': 'date-time'}}}

{'type': 'object', 'required': ['forecast_id'], 'properties': {'forecast_id': {'type': 'string', 'format': 'uuid', 'description': 'UUID of the forecast to fetch.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['id', 'name', 'source_type', 'metric_path', 'horizon_days', 'web_url'], 'properties': {'id': {'type': 'string', 'format': 'uuid'}, 'name': {'type': 'string'}, 'web_url': {'type': 'string', 'format': 'uri'}, 'is_active': {'type': 'boolean'}, 'source_id': {'type': 'string'}, 'transform': {'type': 'string', 'description': 'auto / none / log'}, 'created_at': {'type': ['string', 'null'], 'format': 'date-time'}, 'updated_at': {'type': ['string', 'null'], 'format': 'date-time'}, 'aggregation': {'type': 'string', 'description': 'auto / sum / mean / last / max'}, 'description': {'type': 'string'}, 'granularity': {'type': 'string', 'description': 'One of: hourly, daily, weekly, monthly, quarterly, annual.'}, 'metric_path': {'type': 'string'}, 'next_run_at': {'type': ['string', 'null'], 'format': 'date-time'}, 'source_type': {'type': 'string', 'description': 'One of: report, dashboard, goal, data_source.'}, 'horizon_days': {'type': 'integer'}, 'metric_label': {'type': 'string'}, 'non_negative': {'type': 'boolean'}, 'latest_run_id': {'type': ['string', 'null'], 'format': 'uuid'}, 'method_override': {'type': 'string'}, 'include_anomalies': {'type': 'boolean'}, 'latest_run_status': {'type': ['string', 'null'], 'description': 'pending, running, completed, failed, refunded.'}, 'narration_enabled': {'type': 'boolean'}, 'non_negative_auto': {'type': 'boolean'}, 'schedule_frequency': {'type': ['string', 'null'], 'description': 'daily, weekly, monthly, or manual.'}, 'include_changepoints': {'type': 'boolean'}, 'include_correlations': {'type': 'boolean'}}}

{'type': 'object', 'required': ['forecast_id', 'run_id'], 'properties': {'run_id': {'type': 'string', 'format': 'uuid', 'description': "UUID of the run. Pass 'latest' to fetch the most recent run for the forecast."}, 'forecast_id': {'type': 'string', 'format': 'uuid'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['id', 'forecast_id', 'status'], 'properties': {'id': {'type': 'string', 'format': 'uuid'}, 'result': {'type': 'object', 'description': 'Forecast envelope. Contains keys: target, correlations, anomalies, changepoints, meta, and (when narration ran) narration. `target` carries lower/upper plus calibrated lower_50/upper_50, lower_80/upper_80, lower_95/upper_95 bands, the winning method, exogenous_driver when a leading-indicator was used, ensemble_components when the ensemble method won, transform applied, and non_negative flag. See docs/MCP_SERVER.md for the shape.'}, 'status': {'type': 'string'}, 'trigger': {'type': 'string'}, 'narration': {'type': ['object', 'null'], 'description': 'Peer of result.narration for convenience. Null when the run pre-dates narration OR was gated out (insufficient credits, org disabled, etc.).'}, 'created_at': {'type': ['string', 'null'], 'format': 'date-time'}, 'duration_ms': {'type': 'integer'}, 'forecast_id': {'type': 'string', 'format': 'uuid'}, 'completed_at': {'type': ['string', 'null'], 'format': 'date-time'}, 'error_message': {'type': 'string'}, 'credits_consumed': {'type': 'integer'}, 'credits_refunded': {'type': 'integer'}}}

{'type': 'object', 'required': ['forecast_id'], 'properties': {'forecast_id': {'type': 'string', 'format': 'uuid'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['runs'], 'properties': {'runs': {'type': 'array', 'items': {'type': 'object', 'properties': {'method': {'type': ['string', 'null']}, 'run_id': {'type': 'string', 'format': 'uuid'}, 'horizon': {'type': 'integer'}, 'created_at': {'type': ['string', 'null'], 'format': 'date-time'}, 'smape_actual': {'type': 'number', 'description': "sMAPE between the run's forecast and what actually happened. Lower is better; [0, 200]."}, 'observed_count': {'type': 'integer', 'description': 'How many of the forecast points now have an actual observation to compare against.'}, 'smape_backtest': {'type': 'number', 'description': "The run's own backtest sMAPE at the time it was generated. Compare against actual to spot drift over time."}}}, 'description': "Per-past-run accuracy ordered oldest-first. Each row compares one prior run's forecast against actuals that have since materialized."}}}

{'type': 'object', 'required': ['report_id'], 'properties': {'report_id': {'type': 'string', 'format': 'uuid', 'description': 'UUID of the report to fetch.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['id', 'title', 'status', 'web_url'], 'properties': {'id': {'type': 'string', 'format': 'uuid'}, 'title': {'type': 'string'}, 'status': {'type': 'string'}, 'web_url': {'type': 'string', 'format': 'uri'}, 'insights': {'type': 'object', 'description': 'Narrative insight blocks, when generated.'}, 'created_at': {'type': ['string', 'null'], 'format': 'date-time'}, 'description': {'type': 'string'}, 'completed_at': {'type': ['string', 'null'], 'format': 'date-time'}, 'download_url': {'type': ['string', 'null'], 'description': 'Present only once status is "completed".'}, 'output_format': {'type': 'string'}, 'output_file_path': {'type': 'string'}, 'report_period_end': {'type': ['string', 'null'], 'format': 'date-time'}, 'report_period_start': {'type': ['string', 'null'], 'format': 'date-time'}, 'data_quality_metrics': {'type': 'object', 'description': 'Per-source data-quality stats captured at generation time.'}}}

{'type': 'object', 'properties': {}, 'additionalProperties': False}

{'type': 'object', 'required': ['subscription_tier', 'subscription_status', 'ai_credits_used', 'ai_credits_limit', 'ai_credits_remaining'], 'properties': {'max_users': {'type': 'integer'}, 'trial_ends_at': {'type': ['string', 'null'], 'format': 'date-time'}, 'ai_credits_used': {'type': 'integer'}, 'ai_credits_limit': {'type': 'integer'}, 'storage_gb_limit': {'type': 'number'}, 'data_sources_used': {'type': 'integer'}, 'subscription_tier': {'type': 'string'}, 'data_sources_limit': {'type': 'integer'}, 'subscription_status': {'type': 'string'}, 'ai_credits_remaining': {'type': 'integer'}}}

{'type': 'object', 'required': ['name', 'url'], 'properties': {'url': {'type': 'string', 'description': 'Public http(s) URL of the file to ingest. The server fetches it once at call time; the URL is not re-fetched on subsequent analyses. Private networks (RFC 1918, loopback, link-local, cloud metadata) are blocked.'}, 'name': {'type': 'string', 'maxLength': 200, 'minLength': 2, 'description': 'Display name for the new data source.'}, 'format': {'enum': ['csv', 'tsv', 'json', 'xlsx', 'xls', 'txt', 'pdf'], 'type': 'string', 'description': 'Optional format hint. If omitted, the server infers it from the Content-Type header and URL extension.'}, 'description': {'type': 'string', 'maxLength': 1000, 'description': 'Optional human note stored on the data source.'}, 'wait_seconds': {'type': 'integer', 'default': 0, 'maximum': 60, 'minimum': 0, 'description': 'Seconds to block waiting for preprocessing before returning. 0 returns immediately.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['data_source_id', 'raw_data_id', 'name', 'format', 'status', 'bytes_fetched'], 'properties': {'name': {'type': 'string'}, 'format': {'type': 'string', 'description': 'Detected file format (csv, json, xlsx, ...).'}, 'status': {'type': 'string', 'description': 'Preprocessing status. Poll get_data_source_schema until "active".'}, 'web_url': {'type': ['string', 'null'], 'format': 'uri'}, 'raw_data_id': {'type': 'string'}, 'bytes_fetched': {'type': 'integer'}, 'data_source_id': {'type': 'string', 'format': 'uuid'}}}

{'type': 'object', 'properties': {'limit': {'type': 'integer', 'default': 20, 'maximum': 100, 'minimum': 1, 'description': 'Page size (1–100).'}, 'offset': {'type': 'integer', 'default': 0, 'minimum': 0, 'description': 'Row offset for pagination.'}, 'search': {'type': 'string', 'description': 'Optional substring match against dashboard name.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['total', 'offset', 'limit', 'items'], 'properties': {'items': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'name', 'status', 'web_url', 'is_public'], 'properties': {'id': {'type': 'string', 'format': 'uuid'}, 'name': {'type': 'string'}, 'status': {'type': 'string', 'description': 'Dashboard lifecycle status.'}, 'web_url': {'type': 'string', 'format': 'uri'}, 'is_public': {'type': 'boolean'}, 'created_at': {'type': ['string', 'null'], 'format': 'date-time'}, 'updated_at': {'type': ['string', 'null'], 'format': 'date-time'}, 'last_refresh': {'type': ['string', 'null'], 'format': 'date-time'}}}}, 'limit': {'type': 'integer'}, 'total': {'type': 'integer', 'description': 'Total dashboards matching the query.'}, 'offset': {'type': 'integer'}}}

{'type': 'object', 'properties': {'limit': {'type': 'integer', 'default': 50, 'maximum': 100, 'minimum': 1, 'description': 'Page size (1-100).'}, 'offset': {'type': 'integer', 'default': 0, 'minimum': 0, 'description': 'Row offset for pagination.'}, 'source_type': {'type': 'string', 'description': 'Filter by source_type (csv, postgresql, google_ads, meta_ads, jira, mcp, …).'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['total', 'offset', 'limit', 'items'], 'properties': {'items': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'name', 'source_type', 'status'], 'properties': {'id': {'type': 'string', 'format': 'uuid'}, 'name': {'type': 'string'}, 'status': {'type': 'string', 'description': 'Sync/preprocessing status.'}, 'row_count': {'type': ['integer', 'null'], 'description': 'Row count when preprocessing recorded one, else null.'}, 'created_at': {'type': ['string', 'null'], 'format': 'date-time'}, 'source_type': {'type': 'string'}, 'last_sync_at': {'type': ['string', 'null'], 'format': 'date-time'}}}}, 'limit': {'type': 'integer'}, 'total': {'type': 'integer', 'description': 'Total data sources matching the query.'}, 'offset': {'type': 'integer'}}}

{'type': 'object', 'properties': {'limit': {'type': 'integer', 'default': 20, 'maximum': 100, 'minimum': 1, 'description': 'Page size (1-100).'}, 'offset': {'type': 'integer', 'default': 0, 'minimum': 0, 'description': 'Row offset for pagination.'}, 'is_active': {'type': 'boolean', 'description': 'Filter by active forecasts. Omit to include both active and paused.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['total', 'offset', 'limit', 'items'], 'properties': {'items': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'name', 'source_type', 'metric_path', 'horizon_days', 'web_url'], 'properties': {'id': {'type': 'string', 'format': 'uuid'}, 'name': {'type': 'string'}, 'web_url': {'type': 'string', 'format': 'uri'}, 'is_active': {'type': 'boolean'}, 'source_id': {'type': 'string'}, 'transform': {'type': 'string', 'description': 'auto / none / log'}, 'created_at': {'type': ['string', 'null'], 'format': 'date-time'}, 'aggregation': {'type': 'string', 'description': 'auto / sum / mean / last / max'}, 'granularity': {'type': 'string', 'description': 'One of: hourly, daily, weekly, monthly, quarterly, annual.'}, 'metric_path': {'type': 'string'}, 'next_run_at': {'type': ['string', 'null'], 'format': 'date-time'}, 'source_type': {'type': 'string', 'description': 'One of: report, dashboard, goal, data_source.'}, 'horizon_days': {'type': 'integer'}, 'metric_label': {'type': 'string'}, 'non_negative': {'type': 'boolean'}, 'latest_run_id': {'type': ['string', 'null'], 'format': 'uuid'}, 'method_override': {'type': 'string'}, 'latest_run_status': {'type': ['string', 'null'], 'description': 'pending, running, completed, failed, refunded.'}, 'narration_enabled': {'type': 'boolean'}, 'non_negative_auto': {'type': 'boolean'}, 'schedule_frequency': {'type': ['string', 'null'], 'description': 'daily, weekly, monthly, or manual.'}}}}, 'limit': {'type': 'integer'}, 'total': {'type': 'integer'}, 'offset': {'type': 'integer'}}}

{'type': 'object', 'properties': {'limit': {'type': 'integer', 'default': 20, 'maximum': 100, 'minimum': 1, 'description': 'Page size (1-100).'}, 'offset': {'type': 'integer', 'default': 0, 'minimum': 0, 'description': 'Row offset for pagination.'}, 'status': {'type': 'string', 'description': 'Filter by status (pending, generating, completed, failed, cancelled).'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['total', 'offset', 'limit', 'items'], 'properties': {'items': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'title', 'status', 'web_url'], 'properties': {'id': {'type': 'string', 'format': 'uuid'}, 'title': {'type': 'string'}, 'status': {'type': 'string'}, 'web_url': {'type': 'string', 'format': 'uri'}, 'created_at': {'type': ['string', 'null'], 'format': 'date-time'}, 'completed_at': {'type': ['string', 'null'], 'format': 'date-time'}, 'download_url': {'type': ['string', 'null'], 'description': 'Present only once status is "completed".'}, 'output_format': {'type': 'string'}}}}, 'limit': {'type': 'integer'}, 'total': {'type': 'integer', 'description': 'Total reports matching the query.'}, 'offset': {'type': 'integer'}}}

{'type': 'object', 'required': ['forecast_id', 'run_id'], 'properties': {'run_id': {'type': 'string', 'format': 'uuid', 'description': "UUID of a COMPLETED run. Use get_forecast_run with run_id='latest' first if you want the most recent."}, 'forecast_id': {'type': 'string', 'format': 'uuid'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['narration'], 'properties': {'narration': {'type': 'object', 'description': "Narration payload (summary, highlights, risks, recommendations, methodology_note, credits_consumed, model_used, generated_at, fallback_reason). fallback_reason is null on success; one of 'insufficient_credits', 'llm_failed', 'disabled', 'org_disabled' when narration was skipped."}}}

{'type': 'object', 'required': ['email', 'organization_name', 'accept_terms'], 'properties': {'email': {'type': 'string', 'format': 'email', 'description': 'Work email for the new account.'}, 'last_name': {'type': 'string', 'maxLength': 100, 'description': "User's last name (optional)."}, 'first_name': {'type': 'string', 'maxLength': 100, 'description': "User's first name (optional)."}, 'accept_terms': {'type': 'boolean', 'description': 'Must be true. By passing true the user agrees to https://claribi.com/terms and https://claribi.com/privacy.'}, 'organization_name': {'type': 'string', 'maxLength': 200, 'minLength': 2, 'description': 'Display name for the organization workspace.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['pending_id', 'next_step', 'expires_in_seconds'], 'properties': {'email': {'type': 'string'}, 'next_step': {'type': 'string', 'description': 'Next tool to call: "verify_email" for a fresh signup, else "check_inbox".'}, 'pending_id': {'type': ['string', 'null'], 'description': 'Pass to verify_email. Null when no new registration was created.'}, 'expires_in_seconds': {'type': 'integer'}}}

{'type': 'object', 'required': ['provider'], 'properties': {'provider': {'enum': ['google', 'meta', 'jira', 'confluence'], 'type': 'string', 'description': 'OAuth provider to authorize. Currently supports the native-OAuth catalog: Google (Ads, Analytics 4, Search Console, Sheets, Drive, BigQuery), Meta Ads, and Atlassian Jira / Confluence.'}, 'integration_type': {'type': 'string', 'description': 'Per-provider sub-type. Google accepts google_ads, gsheets, ga4, gsc, gdrive, bigquery, gcs, gcp, basic. Meta accepts ads or basic. Jira and Confluence accept basic. Defaults to basic.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['handoff_id', 'authorize_url', 'provider', 'integration_type', 'expires_in_seconds', 'next_step'], 'properties': {'provider': {'type': 'string'}, 'next_step': {'type': 'string', 'description': 'Tool to call next, normally "check_integration_status".'}, 'handoff_id': {'type': 'string', 'format': 'uuid'}, 'authorize_url': {'type': 'string', 'format': 'uri', 'description': 'Open in a browser to grant consent.'}, 'integration_type': {'type': 'string'}, 'expires_in_seconds': {'type': 'integer'}}}

{'type': 'object', 'required': ['question'], 'properties': {'question': {'type': 'string', 'maxLength': 1000, 'minLength': 3, 'description': 'Natural language question to analyze. E.g. "What was revenue last quarter by region?".'}, 'session_id': {'type': 'string', 'description': 'Optional existing conversation session UUID.'}, 'wait_seconds': {'type': 'integer', 'default': 30, 'maximum': 60, 'minimum': 0, 'description': 'How long (seconds) to wait for the job to finish before returning a job_id for polling. 0 = always return immediately.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['job_id', 'status'], 'properties': {'job_id': {'type': 'string', 'format': 'uuid'}, 'result': {'type': 'object', 'description': 'Analysis envelope (headline metric, chart data, follow-ups). Present when status is "completed".'}, 'status': {'type': 'string', 'description': 'Job status, e.g. "completed", "running", "queued".'}, 'poll_url': {'type': 'string', 'format': 'uri', 'description': 'Present when the job is still running. Poll get_analysis_status instead for structured progress.'}, 'ai_credits_used': {'type': 'integer'}, 'ai_credits_limit': {'type': 'integer'}}}

{'type': 'object', 'required': ['forecast_id'], 'properties': {'forecast_id': {'type': 'string', 'format': 'uuid'}, 'wait_seconds': {'type': 'integer', 'default': 30, 'maximum': 60, 'minimum': 0, 'description': 'Seconds to wait for the run to finish before returning a poll handle. 0 = return immediately with the run_id.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['run_id', 'status'], 'properties': {'result': {'type': 'object', 'description': 'Present when status reaches "completed".'}, 'run_id': {'type': 'string', 'format': 'uuid'}, 'status': {'type': 'string', 'description': 'pending while queued, running mid-execution, completed/failed/refunded when terminal.'}, 'poll_tool': {'type': 'string', 'description': 'Tool to poll if the run is still running ("get_forecast_run").'}, 'credits_consumed': {'type': 'integer'}, 'credits_refunded': {'type': 'integer'}, 'credits_reserved': {'type': 'integer'}}}

{'type': 'object', 'required': ['name', 'format', 'data_base64'], 'properties': {'name': {'type': 'string', 'maxLength': 200, 'minLength': 2, 'description': 'Display name for the new data source. Shown in the web app and in subsequent list_data_sources calls.'}, 'format': {'enum': ['csv', 'tsv', 'json', 'xlsx', 'xls', 'txt', 'pdf'], 'type': 'string', 'description': 'File format. Drives MIME detection and the preprocessing route inside clariBI. csv covers comma-separated; tsv is tab-separated; xlsx is modern Excel; json must be a top-level array of objects or a single object.'}, 'data_base64': {'type': 'string', 'description': 'Base64-encoded file contents. Maximum 25 MB encoded (~18 MB raw). For larger payloads, host the file at a public URL and use ingest_url_data_source.'}, 'description': {'type': 'string', 'maxLength': 1000, 'description': 'Optional human-readable description. Surfaces in the web app and in get_data_source_schema.'}, 'wait_seconds': {'type': 'integer', 'default': 0, 'maximum': 60, 'minimum': 0, 'description': 'How long (seconds) to wait for preprocessing to finish before returning. 0 returns immediately with status="preprocessing"; the caller polls get_data_source_schema or list_data_sources.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['data_source_id', 'raw_data_id', 'name', 'format', 'status', 'bytes_uploaded'], 'properties': {'name': {'type': 'string'}, 'format': {'type': 'string', 'description': 'Detected file format (csv, json, xlsx, ...).'}, 'status': {'type': 'string', 'description': 'Preprocessing status. Poll get_data_source_schema until "active".'}, 'web_url': {'type': ['string', 'null'], 'format': 'uri'}, 'raw_data_id': {'type': 'string'}, 'bytes_uploaded': {'type': 'integer'}, 'data_source_id': {'type': 'string', 'format': 'uuid'}}}

{'type': 'object', 'required': ['pending_id', 'code', 'password'], 'properties': {'code': {'type': 'string', 'pattern': '^[0-9]{6}$', 'description': '6-digit verification code from the email.'}, 'password': {'type': 'string', 'minLength': 8, 'description': "A password for the new account. Must be at least 8 characters and pass Django's standard validators."}, 'pending_id': {'type': 'string', 'format': 'uuid', 'description': 'The pending_id returned by register_account.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['access_token', 'token_type', 'expires_in', 'scope', 'mcp_api_key', 'mcp_api_key_id', 'user_id', 'organization_id', 'tier'], 'properties': {'tier': {'type': 'string', 'description': 'New organization tier, always "trial".'}, 'scope': {'type': 'string', 'description': 'Space-separated granted scopes.'}, 'user_id': {'type': 'string'}, 'expires_in': {'type': 'integer', 'description': 'Access-token lifetime in seconds.'}, 'next_steps': {'type': 'array', 'items': {'type': 'string'}}, 'token_type': {'type': 'string', 'description': 'Always "Bearer".'}, 'mcp_api_key': {'type': 'string', 'description': 'Long-lived API key (claribi_mcp_...) for persistent client config.'}, 'access_token': {'type': 'string', 'description': 'OAuth bearer token for this conversation.'}, 'mcp_api_key_id': {'type': 'string', 'format': 'uuid'}, 'organization_id': {'type': 'string'}}}