# API reference

Base URL: https://pretick.ai. All customer paths stay on this domain.

## Onboarding and usage

- `POST /v1/trial`, unauthenticated: `{"email":"you@example.com"}`. Sends an eligible trial key by email; one trial per email and signup limits apply. Requires the user's instruction to send to that address. It does not return a key or replenish existing accounts.
- `GET /v1/usage`, Bearer auth: returns `balance_cents` and up to 100 recent request records. Two cents pays for one successful forecast. Usage queries are free.
- `POST /v1/timeseries/forecast`, Bearer auth: numerical inference, $0.02 per successful call. Maximum JSON body 400,000 bytes. Start with one concurrent request.

## Simple request

```json
{"data":"102, 108, 111, 104, 99, 106"}
```

This requests six predictions. Optional `horizon` overrides the length. `data` also accepts a numeric array, two time/value columns, two rows, or alternating date/value lines. There must be 3-1,024 observations. Supported separators include commas, semicolons, pipes, tabs, spaces and newlines. Commas are separators, not thousands markers. Use decimal periods. Calendar inference is described in SKILL.md and in returned `time_schedule` when applicable.

## Advanced request

```json
{
  "history":{"columns":["sales","temperature"],"values":[[102,18],[108,19],[111,20],[104,18],[99,17],[106,19]]},
  "frequency":"1d",
  "targets":["sales"],
  "horizon":3,
  "quantiles":[0.1,0.5,0.9]
}
```

Advanced history supports 3-2,048 rows and 1-8 unique columns. Each row has one finite numeric value per column, with magnitude at most 1e12. Targets are a unique subset of the columns; others are past-only covariates. Horizon is required, 1-1,024. Frequency is interval metadata (positive integer followed by `s`, `min`, `h`, `d`, or `w`), not a calendar feature. Quantiles are 1-9 sorted unique levels within 0.1-0.9. The optional model is `pretick-default`.

For multiple targets, `predictions` is a row matrix in `prediction_columns` order. `forecasts` retains each target's median and quantile arrays. Full precision is in JSON. Other fields: `times` when supplied in simple text input, optional `time_schedule`, `model_version`, `horizon`, `frequency`, `usage`, `request_id`, `cost_cents`, `balance_cents`.

## Errors

| Status | Action |
|---|---|
| 400 | Correct input; validation errors are not charged. |
| 401 | Configure a valid Pretick key. |
| 402 | The user can top up at https://pretick.ai/pricing with the same email. |
| 413 | Reduce the payload below 400,000 bytes. |
| 429 | Trial signup limit; wait or contact support. |
| 503 | Check error and refund state. Responses include failure_reason, request_id, and optional upstream_status (for example 502). Busy/failed inference is refunded; `refund_pending` or `accounting_pending` needs review with the request ID. |

Allow roughly 60 seconds for the full HTTP request. The service allows 45 seconds for inference. No automatic retries: every successful repeated call costs another two cents. A timeout may have completed server-side; check usage before requesting another forecast.

## Market-research workflow

Use a specified historical dataset and document ticker/instrument, price type, adjustments, units and observation dates. Pretick receives numbers; it does not resolve a ticker or fetch live quotes. Example `examples/market-research.txt` is synthetic and must not be represented as actual prices.

For an explicitly requested backtest, split chronologically, predict only from each historical training window, then compare against the held-out outcomes and a last-observed-value baseline. Disclose the number of paid calls before running a batch. Report errors rather than asserting trading profitability. If evaluating a trading strategy, account for its transaction costs and decision rules separately. No built-in backtest endpoint exists in this release.