# Docs

- v1
  - [What is predictAI?](/docs/v1): The Prediction OS — one platform that turns your company's data into answers for every decision that depends on what happens next.

  - **Guides**
  - [Quickstart](/docs/v1/guides/quickstart): Push a signal, create a goal, and get your first forecast — in about five minutes.
  - [SDKs](/docs/v1/guides/sdks): Official Python and Node.js clients — install once, and every endpoint is a method call.
  - Core concepts
    - [Core concepts](/docs/v1/guides/core-concepts): The seven ideas that make everything else in predictAI make sense.
    - [Workspaces & organizations](/docs/v1/guides/core-concepts/workspaces-and-organizations): How tenancy works — who owns what, and what X-Workspace-Id does.
    - [Signals, segments & time series](/docs/v1/guides/core-concepts/signals-segments-time-series): How your data is represented — and what models actually train on.
    - [Models & pipelines](/docs/v1/guides/core-concepts/models-and-pipelines): The two nouns people mix up — a model is what trains; a pipeline is how and when it trains.
    - [Trainings & champions](/docs/v1/guides/core-concepts/trainings-and-champions): What a training run produces, how runs are scored, and what "champion" means.
    - [Deployments & promotions](/docs/v1/guides/core-concepts/deployments-and-promotions): How a trained model becomes a live endpoint — and the difference between shared and dedicated serving.
    - [Goals & discovery runs](/docs/v1/guides/core-concepts/goals-and-discovery): The autopilot layer — declare an outcome and the platform builds the forecasting system for you.
    - [The forecasting loop](/docs/v1/guides/core-concepts/the-forecasting-loop): How the pieces fit together, end to end — with the API call for every step.
  - [Authentication](/docs/v1/guides/authentication): API tokens, the two headers every request needs, and token scopes.
  - [Errors & responses](/docs/v1/guides/errors): Response envelopes, status codes, and how to handle every kind of failure.
  - [Rate limits & credits](/docs/v1/guides/rate-limits): How the platform meters usage — credits for actions, quotas for objects.
  - [Glossary](/docs/v1/guides/glossary): Every term the docs use, in one place.

  - **Examples**
  - Examples
    - [Examples](/docs/v1/examples): Complete, runnable walkthroughs — from your first push to autopilot goals, scenarios, and alerts.
    - [Hello, predictAI](/docs/v1/examples/hello-predictai): The smallest possible program — push values, read them back, and see your data start to connect.
    - [A forecast with zero training](/docs/v1/examples/zero-shot-forecast): Deploy a pretrained foundation model zero-shot and get a probabilistic forecast in three calls.
    - [CSV to live forecast](/docs/v1/examples/csv-to-live-forecast): The full production loop — load history from a CSV, define a segment, train a model, deploy the winner, serve forecasts.
    - [Race a model pool](/docs/v1/examples/race-a-model-pool): Train a custom LSTM and a fine-tuned foundation model in the same run — deploy whichever wins.
    - [A goal on autopilot](/docs/v1/examples/goal-on-autopilot): Name an outcome, let the platform find its drivers, train champions, and keep a forecast live — then ask it why.
    - [What-if scenarios](/docs/v1/examples/what-if-scenarios): Move a driver, replay an event, and watch the forecast respond — counterfactuals served by the live champion.
    - [Alerts that watch the forecast](/docs/v1/examples/alerts-and-notifications): Put a condition on the future — get told the moment the forecast crosses it, on the channels you choose.
    - [An anomaly goal, end to end](/docs/v1/examples/anomaly-goal-end-to-end): Upload a CSV in one call, create an anomaly goal, watch everything happen live over WebSockets, and wire alerts — the whole platform in one sitting.

  - **API Reference**
  - [API Reference](/docs/v1/reference): Base URL, headers, conventions, and every endpoint prefix in one place.

  - **Building blocks**
  - Ingestion
    - [Ingestion](/docs/v1/ingestion): Bring data in — connect databases, files, APIs, and webhooks, and keep signals flowing on a schedule.
    - [Concepts](/docs/v1/ingestion/concepts): Data sources, connectors, jobs, executions — and how events differ from signals.
    - [Data sources](/docs/v1/ingestion/data-sources): Create, list, inspect, update, and delete sources — plus schema introspection and connection tests.
    - [Connect & import](/docs/v1/ingestion/connect-and-import): Inspect a connection, create a source with ready-to-run syncs, upload files, and stage multi-file datasets.
    - [Jobs](/docs/v1/ingestion/jobs): Create sync jobs, schedule them, pause and resume, trigger on demand, and preview upcoming runs.
    - [Executions](/docs/v1/ingestion/executions): Track ingestion runs — status, progress, errors, cancellation, retries, and workspace stats.
    - [OAuth connectors](/docs/v1/ingestion/oauth): Connect providers like Stripe and X with a consent flow instead of pasted credentials.
    - [Webhooks](/docs/v1/ingestion/webhooks): Let external systems push data in — per-source URLs, HMAC-SHA256 signatures, and events vs signal delivery.
    - [Endpoints](/docs/v1/ingestion/endpoints): Every ingestion route at a glance.
  - Signals
    - [Signals](/docs/v1/signals): Named time series — the data atoms everything else on the platform is built from.
    - [Concepts](/docs/v1/signals/concepts): Signal keys and types, units and groups, display names, and push vs pull ingestion.
    - [Push & manage](/docs/v1/signals/push-and-manage): Push values, list and inspect signals, delete, and manage display names, units, and groups.
    - [Events](/docs/v1/signals/events): Discrete, timestamped occurrences — recorded under named streams, automatically scored, and shown alongside your signals.
    - [Analysis](/docs/v1/signals/analysis): Correlation, relevance, and causality between signals.
    - [Endpoints](/docs/v1/signals/endpoints): Every signal and event route at a glance.
  - Segments
    - [Segments](/docs/v1/segments): The exact table a model trains on — columns, grid, window, normalization, and engineered features.
    - [Concepts](/docs/v1/segments/concepts): The four decisions a segment pins down — columns, grid, window, and normalization — and why each exists.
    - [Create & manage](/docs/v1/segments/create-and-manage): Create, list, inspect, edit, and delete segments.
    - [Normalization](/docs/v1/segments/normalization): Every gap-filling strategy, fallback chains, per-field overrides, point-in-time safety, and templates.
    - [Engineered features](/docs/v1/segments/engineered-features): The full catalog of derived columns — lags, rolling statistics, differences, event and calendar features.
    - [Preview](/docs/v1/segments/preview): See the actual rows a segment produces — including dry runs of configurations you haven't saved yet.
    - [Endpoints](/docs/v1/segments/endpoints): Every segment route at a glance.
  - Models
    - [Models](/docs/v1/models): The trainable artifacts — custom architectures, foundation models, and your own uploads, all in one catalog.
    - [Concepts](/docs/v1/models/concepts): Model kinds, how models relate to pipelines, and how catalog visibility works.
    - [Custom models](/docs/v1/models/custom-models): Create your own architecture, browse your models and the public catalog, and fetch the workspace recommendation.
    - [Foundation models](/docs/v1/models/foundation): Pretrained forecasting models — browse what's available, deploy zero-shot, or fine-tune an adapter on your data. One API for every model, predictfm included.
    - [BYOM](/docs/v1/models/byom): Bring your own model — upload a pre-trained artifact, validate it, and register it as a model you can deploy.
    - [Endpoints](/docs/v1/models/endpoints): Every model route at a glance — core catalog, foundation models, and BYOM.
  - Pipelines
    - [Pipelines](/docs/v1/pipelines): Training workflows — bind a model to your data, on a schedule, with automation.
    - [Concepts](/docs/v1/pipelines/concepts): Anatomy of a pipeline — segment, models, schedule, and the automation around them.
    - [Create & manage](/docs/v1/pipelines/create-and-manage): Create, list, inspect, edit, and delete pipelines.
    - [Train now](/docs/v1/pipelines/train-now): Trigger a training run on demand — and every reason the platform might say no.
    - [Promotion decisions](/docs/v1/pipelines/promotion-decisions): Approve or dismiss a winning training when the promotion policy is manual.
    - [Endpoints](/docs/v1/pipelines/endpoints): Every pipeline route at a glance.
  - Trainings
    - [Trainings](/docs/v1/trainings): The run history — every training is scored, immutable, and deployable.
    - [Concepts](/docs/v1/trainings/concepts): The training lifecycle, how runs are scored, champions, and cost.
    - [Browse runs](/docs/v1/trainings/browse-runs): List training runs with filters and pagination; inspect one run's full report.
    - [Endpoints](/docs/v1/trainings/endpoints): Every training route at a glance.
  - Inference
    - [Inference](/docs/v1/inference): Run forecasts against deployed models — by deployment, pipeline, or goal — and inspect the history.
    - [Concepts](/docs/v1/inference/concepts): Addressing styles, raw vs segment inference, sync vs async responses, and the audit trail.
    - [Run a forecast](/docs/v1/inference/run-a-forecast): Get predictions out of a deployed model — by goal, pipeline, or pinned deployment.
    - [Segment-based inference](/docs/v1/inference/segment-based-inference): Let the platform prepare model input from live segment data — options, async behavior, and when to go raw.
    - [History & usage](/docs/v1/inference/history-and-usage): List past inferences, audit a single one, and chart a deployment's request volume.
    - [Endpoints](/docs/v1/inference/endpoints): Every inference route at a glance.
  - Deployments
    - [Deployments](/docs/v1/deployments): Put a trained model into live serving — deploy, monitor, scale, retry, and retire.
    - [Concepts](/docs/v1/deployments/concepts): The deployment lifecycle — statuses, serving modes, type auto-detection, and readiness.
    - [Deploy a trained model](/docs/v1/deployments/deploy): Create a deployment — put a completed training into live serving with one call.
    - [Manage deployments](/docs/v1/deployments/manage): List, inspect, retry, unpromote, delete, and clean up deployments.
    - [Serving status](/docs/v1/deployments/serving-status): Check what's live — per pipeline, per serving mode, or fleet-wide.
    - [Scale Dedicated deployments](/docs/v1/deployments/scale-dedicated): Set the replica count on a Dedicated deployment's reserved serving capacity.
    - [Endpoints](/docs/v1/deployments/endpoints): Every deployment route at a glance.
  - Goals
    - [Goals](/docs/v1/goals): Outcome-driven forecasting — declare what you want forecast and the platform builds, deploys, and maintains the system for you.
    - [Concepts](/docs/v1/goals/concepts): What a goal is, how discovery runs work, and how champions, the graph, and cost fit together.
    - [Create & manage](/docs/v1/goals/create-and-manage): Create, list, inspect, edit, and delete goals — plus the free previews to use before you pay.
    - [Discovery](/docs/v1/goals/discovery): What a discovery run does stage by stage, how to re-run one, and how to take manual control.
    - [Tournament & champion](/docs/v1/goals/tournament): How candidate models compete, how to read the leaderboard, and how to pick or cancel a champion.
    - [Forecast](/docs/v1/goals/forecast): Read the goal's live forecast and track record, force a refresh, and see the pressure behind it.
    - [Graph](/docs/v1/goals/graph): The discovered structure — nodes, scored lagged edges, multi-hop paths, and full edge evidence.
    - [Scenarios](/docs/v1/goals/scenarios): What-if simulations over the discovered graph — move a driver, inject an event, and see the forecast respond.
    - [Analyst](/docs/v1/goals/analyst): Ask the goal questions in plain language — streamed answers grounded in its forecast, graph, and what-if engine.
    - [Fleet goals](/docs/v1/goals/fleet): One goal per population — score every member with a zero-shot foundation model, rank them, and get a live leaderboard with verified receipts.
    - [Alerts](/docs/v1/goals/alerts): Conditions on the goal's forecast, evaluated after every champion serve — with a live preview before you save.
    - [Activity & pricing](/docs/v1/goals/activity-and-pricing): The goal's activity feed and audit timeline, what goals cost, and publishing the goal's segment.
    - [Endpoints](/docs/v1/goals/endpoints): Every goal route at a glance, grouped by what it does.
  - Billing
    - [Billing](/docs/v1/billing): Credits for actions, quotas for objects — check, estimate, and pay, all by API.
    - [Concepts](/docs/v1/billing/concepts): The credit ledger, what costs credits, plan tiers, and the quotas each plan enforces.
    - [Balance & usage](/docs/v1/billing/balance-and-usage): Read your credit balance and your live quota usage.
    - [Estimate before you spend](/docs/v1/billing/estimate): Price any operation in advance, and read your full resolved rate card.
    - [Endpoints](/docs/v1/billing/endpoints): Every billing route at a glance.

  - **Platform**
  - Workspaces
    - [Workspaces](/docs/v1/workspaces): Tenancy — organizations own workspaces, workspaces scope everything else.
    - [Concepts](/docs/v1/workspaces/concepts): What X-Workspace-Id gates, how organization roles work, and how regions pin your data.
    - [Find your workspace ID](/docs/v1/workspaces/find-your-workspace): List your workspaces and pick the uid that every other API call needs.
    - [Manage workspaces](/docs/v1/workspaces/manage-workspaces): Create, inspect, edit, and delete workspaces; list the regions you can create in.
    - [Workspace members](/docs/v1/workspaces/members): Share a single workspace — list, add, and remove members without organization-wide access.
    - [Organizations](/docs/v1/workspaces/organizations): List your organizations, create one, manage its details, and control member roles.
    - [Invitations](/docs/v1/workspaces/invitations): Invite someone to an organization by email; verify the token, then accept or decline.
    - [Endpoints](/docs/v1/workspaces/endpoints): Every workspace and organization route at a glance.
  - Account
    - [Account](/docs/v1/account): Your identity and credentials — the profile behind the token, and the API tokens themselves.
    - [API tokens](/docs/v1/account/api-tokens): Create, list, edit, revoke, and regenerate the pa_live_ tokens that authenticate programmatic access.
    - [Profile](/docs/v1/account/profile): Who am I, and update your profile.
    - [Endpoints](/docs/v1/account/endpoints): Every account route at a glance.
  - Notifications
    - [Notifications](/docs/v1/notifications): How the platform tells you things — the feed, delivery channels, and per-event preferences.
    - [Concepts](/docs/v1/notifications/concepts): Events and the feed, and how channels differ from preferences.
    - [Read the feed](/docs/v1/notifications/feed): List your notifications, mark one read, or mark everything read.
    - [Live stream](/docs/v1/notifications/live-stream): Push new feed items to your client over Server-Sent Events.
    - [Channels](/docs/v1/notifications/channels): Deliver notifications to Slack, Teams, PagerDuty, or your own webhook.
    - [Preferences](/docs/v1/notifications/preferences): The event catalog, and muting or rerouting each event per channel.
    - [Endpoints](/docs/v1/notifications/endpoints): Every notifications route at a glance.
  - Realtime
    - [Realtime](/docs/v1/realtime): Live events over WebSockets — trainings, deployments, forecasts, and goal alerts, without polling.
    - [Connect & authenticate](/docs/v1/realtime/connect): Open a WebSocket to the gateway, present your token, and keep the connection healthy.
    - [Channels](/docs/v1/realtime/channels): The three channel kinds — workspace, goal, and user — and who can subscribe to what.
    - [Wire protocol](/docs/v1/realtime/protocol): Every frame on the wire — client actions, server responses, and delivery semantics.
    - [Event catalog](/docs/v1/realtime/events): Every realtime event the platform emits, by channel — names, triggers, and payload highlights.
    - [Endpoints](/docs/v1/realtime/endpoints): The realtime surface at a glance — one WebSocket endpoint, five frame actions.