<div class="section-label"><span class="num">01</span> API</div>
<div class="section-title">The hosted Prediction Engine, <em>v2</em>.</div>
The CSA Prediction Engine API is a REST service. You post a prediction task, receive a job id, then retrieve results. Three prediction paths are available: **Grid**, **MaxFit**, and **PSR** (partial-sample regression).
This chapter documents **API v2**. A v3 API for the rust-powered engine is in development; until that contract is published, this is the hosted API to integrate against.
> [!note]
> Endpoint pages embed the live v2 OpenAPI specs ([basic](https://github.com/CambridgeSportsAnalytics/prediction_engine_quickstart/blob/main/docs/api_specs/basic.json), [extended](https://github.com/CambridgeSportsAnalytics/prediction_engine_quickstart/blob/main/docs/api_specs/extended.json)) rather than copying field tables. Those names are not the same as the local engine’s [[Settings/Options|Settings]] names.
<div class="pillars">
<div class="pillar">
<div class="pillar-num">↳ 01</div>
<div class="pillar-title">Grid</div>
<div class="pillar-text">Evaluate attribute combinations and thresholds, then form a fit-weighted composite.</div>
</div>
<div class="pillar">
<div class="pillar-num">↳ 02</div>
<div class="pillar-title">MaxFit</div>
<div class="pillar-text">Search thresholds (and censor types) for the strongest fit on a fixed attribute set.</div>
</div>
<div class="pillar">
<div class="pillar-num">↳ 03</div>
<div class="pillar-title">PSR</div>
<div class="pillar-text">Partial-sample regression at the thresholds you choose.</div>
</div>
</div>
<p> </p>
<div class="section-label"><span class="num">02</span> Base URL</div>
```http
https://api.csanalytics.io/v2/prediction-engine
```
All paths in this chapter are relative to that host. HTTPS with TLS 1.2 or above is required.
## Authentication
Every request needs both an organization API key and a user access id. Your CSA account manager issues these.
| Variable | Where | Description |
| --- | --- | --- |
| <span class="mono">x-api-key</span> | Header | Organization API key |
| <span class="mono">access_id</span> | JSON body | Individual user access id |
Also send:
| Header | Value |
| --- | --- |
| <span class="mono">Content-Type</span> | <span class="mono">application/json</span> |
| <span class="mono">Connection</span> | <span class="mono">keep-alive</span> |
## How a job runs
Prediction calls are asynchronous.
```mermaid
sequenceDiagram
participant You
participant API
You->>API: POST /grid, /maxfit, or /psr
API-->>You: job_id, job_code
You->>API: GET /results
API-->>You: prediction JSON
```
1. **POST** a prediction path with <span class="mono">y</span>, <span class="mono">X</span>, <span class="mono">theta</span>, and <span class="mono">access_id</span>.
2. The response is a task receipt: <span class="mono">job_id</span> and <span class="mono">job_code</span>.
3. **GET** [[API/Prediction Engine/Results|Results]] with that receipt to read the forecast and insights.
Append [[API/Prediction Engine/Binary|/binary]] to any prediction path for categorical / logistic-scale outcomes. No other parameter changes.
## Requests and responses
| Method | Action |
| --- | --- |
| POST | Submit a prediction task |
| GET | Retrieve results for a job |
Bodies and responses are UTF-8 JSON. Arrays are two-dimensional — see [[API/Getting Started/Arrays|Arrays]]. Numerics are single precision — see [[API/Getting Started/Precision|Precision]].
A successful POST returns HTTP 200 with the task receipt. Payload and rate limits return 413 and 429: [[API/Getting Started/Payload Limits|Payload Limits]] · [[API/Getting Started/Throttle Limits|Throttle Limits]].
<p> </p>
<div class="section-label"><span class="num">03</span> In this chapter</div>
<div class="solution-list">
<div class="solution-row">
<div class="solution-num">/01</div>
<div class="solution-title">Getting Started</div>
<div class="solution-desc">How to shape arrays, what precision means, and the payload and throttle limits.</div>
</div>
<div class="solution-row">
<div class="solution-num">/02</div>
<div class="solution-title">Prediction Engine</div>
<div class="solution-desc">REST endpoints: Grid, MaxFit, PSR, the /binary qualifier, and retrieving results.</div>
</div>
<div class="solution-row">
<div class="solution-num">/03</div>
<div class="solution-title">Python Client</div>
<div class="solution-desc">The current v2 pip client (<span class="mono">csa_prediction_engine</span>) for this API.</div>
</div>
</div>
<div class="solution-list">
<div class="solution-row">
<div class="solution-num">↳</div>
<div class="solution-title"><a href="/API/Getting%20Started/Arrays">Arrays</a></div>
<div class="solution-desc">Numbers, vectors, and matrices as 2-D JSON arrays.</div>
</div>
<div class="solution-row">
<div class="solution-num">↳</div>
<div class="solution-title"><a href="/API/Getting%20Started/Precision">Precision</a></div>
<div class="solution-desc">float32 by default; read results to six decimal places.</div>
</div>
<div class="solution-row">
<div class="solution-num">↳</div>
<div class="solution-title"><a href="/API/Getting%20Started/Payload%20Limits">Payload Limits</a></div>
<div class="solution-desc">POST bodies must stay under 10 MB.</div>
</div>
<div class="solution-row">
<div class="solution-num">↳</div>
<div class="solution-title"><a href="/API/Getting%20Started/Throttle%20Limits">Throttle Limits</a></div>
<div class="solution-desc">Too many requests in a short window return 429.</div>
</div>
<div class="solution-row">
<div class="solution-num">↳</div>
<div class="solution-title"><a href="/API/Prediction%20Engine/Grid">Grid</a></div>
<div class="solution-desc">POST /grid — the primary hosted analysis path.</div>
</div>
<div class="solution-row">
<div class="solution-num">↳</div>
<div class="solution-title"><a href="/API/Prediction%20Engine/MaxFit">MaxFit</a></div>
<div class="solution-desc">POST /maxfit — strongest fit on a fixed attribute set.</div>
</div>
<div class="solution-row">
<div class="solution-num">↳</div>
<div class="solution-title"><a href="/API/Prediction%20Engine/PSR">PSR</a></div>
<div class="solution-desc">POST /psr — partial-sample regression at chosen thresholds.</div>
</div>
<div class="solution-row">
<div class="solution-num">↳</div>
<div class="solution-title"><a href="/API/Prediction%20Engine/Binary">Binary</a></div>
<div class="solution-desc">Append /binary for categorical analysis.</div>
</div>
<div class="solution-row">
<div class="solution-num">↳</div>
<div class="solution-title"><a href="/API/Prediction%20Engine/Results">Results</a></div>
<div class="solution-desc">GET /results — core and extended result fields.</div>
</div>
<div class="solution-row">
<div class="solution-num">↳</div>
<div class="solution-title"><a href="/API/Python%20Client/Introduction">Python Client</a></div>
<div class="solution-desc">Install and call the v2 Python package.</div>
</div>
</div>
> [!tip]
> New to the hosted API? Post [[API/Prediction Engine/Grid|Grid]] with the required body, then poll [[API/Prediction Engine/Results|Results]]. For the same math running locally, see [[Functions/Overview|Functions]].
<div class="btn-row center">
<a class="btn-primary" href="/API/Prediction%20Engine/Grid">Start with Grid</a>
<a class="btn-ghost" href="/API/Python%20Client/Introduction">Python Client</a>
</div>