> For the complete documentation index, see [llms.txt](https://betmatic.gitbook.io/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://betmatic.gitbook.io/documentation/api-reference/overview.md).

# Overview

Betmatic REST API. The base URL is `https://betmatic.app/api`. JSON is used for request bodies and non-empty responses. An active Betmatic subscription is required.

> **How Betmatic executes your API bets.** `POST /notification/create/` does not place a bet by itself — it creates a bet **instruction** and broadcasts it to your running bot machines. The desktop bot application, with sessions Online, is what actually places the bets at the bookmakers. If no bot is running (or no session matches your targeting), the API still returns **200** — but nothing is placed. Before integrating, make sure the bot is installed and sessions are running.

***

## Your first bet in 10 minutes

1. **Log in** — `POST /account/login/` with your email and password; keep the returned token.
2. **Confirm a session is live** — `GET /bookieaccount/` and check at least one session has `"bot_running": true`. If none do, start the bot and sessions first.
3. **Find a race** — `GET /competition/namecodes/` and pick an upcoming race (note its `name`, `code`, `event_number`).
4. **Place a $1 test bet** — `POST /notification/create/` with `"stake": 1`, a unique `"label"`, and `target_session` set to one session ID, so the test touches exactly one account:

```bash
curl -X POST https://betmatic.app/api/notification/create/ \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Fixed Wager",
    "sports": "RACING",
    "competition": "FLEMINGTON",
    "code": "Galloping",
    "event_number": 6,
    "market": "Fixed Win",
    "selection": "3",
    "stake": 1,
    "label": "api-test-001",
    "target_session": "101"
  }'
```

5. **Check the placement** — `GET /bet/notification/{id}/` with the returned `id`; each session's record shows `submit_result` and the odds taken.

Full field reference: [Create a Bet](/documentation/placing-bets/create-bet.md). Complete worked examples: [Bet Examples](/documentation/placing-bets/bet-examples.md).

***

## Testing safely

There is no sandbox environment or dry-run flag on the API — every accepted instruction can place real money. The dry-run facility is the **Simulation tab** on the website's Tip Connect page, which shows exactly which sessions would act on a bet without placing it; it is not available via the API. A safe integration recipe:

1. Simulate on the website first to confirm your sessions and filters behave as expected.
2. Then send **$1 real bets** targeted at a single session (`target_session`) with a unique `label`.
3. Only scale stakes once the results in [Bet Records](/documentation/bet-history/bet-records.md) match what you intended.

***

## Base URL

```
https://betmatic.app/api
```

***

## Authentication

All authenticated endpoints require an `Authorization` header:

```
Authorization: Token <your_token>
```

Tokens are valid for **60 days**. Obtain a token via `POST /account/login/`. A token can be refreshed via `POST /account/refresh_token/`, but only within 7 days of login — after that, log in again.

***

## Error Responses

| Status | Meaning                                                                                                |
| :----: | ------------------------------------------------------------------------------------------------------ |
|   400  | Bad Request — validation error, check request fields                                                   |
|   401  | Unauthorized — token missing, invalid, or expired                                                      |
|   403  | Forbidden — insufficient permissions, or subscription inactive/expired on subscription-gated endpoints |
|   404  | Not Found — resource doesn't exist                                                                     |
|   500  | Internal Server Error — contact support if repeated                                                    |

Most JSON validation errors use one of these shapes:

```json
{"error": "Description of what went wrong"}
```

or, for field-level validation failures:

```json
{"field_name": ["Validation error message"]}
```

***

## Pagination

Paginated endpoints return a standard envelope:

```json
{
  "count": 150,
  "next": "https://betmatic.app/api/notification/?page=2",
  "previous": null,
  "total_pages": 15,
  "results": [...]
}
```

Control pagination with these query parameters:

| Parameter   |          Default          | Max | Description                                                           |
| ----------- | :-----------------------: | :-: | --------------------------------------------------------------------- |
| `page`      |             1             |  —  | Page number. An out-of-range page returns page 1 rather than an error |
| `page_size` | Endpoint-specific (10–20) | 100 | Results per page                                                      |

> **Note:** `count` is never reported below `1`, even when there are no results — rely on the `results` array length.

***

## Rate Limits

Only the credential endpoints are rate-limited: `POST /account/login/` at **30/min**, and signup, password reset and email verification at **5/min** each. The betting and data endpoints currently have no enforced rate limit — bots are expected to poll them — but keep polling reasonable (a few requests per second at most) so this can stay the case.

***

## Idempotency

`POST /notification/create/` performs **no duplicate detection** — sending the same request twice creates two bet instructions, and retrying a timed-out request can double-bet. Protect yourself client-side:

1. Put a **unique `label`** on every instruction (e.g. your own order ID).
2. If a create request times out or errors ambiguously, call `GET /notification/?label=<your-label>` **before** retrying — if the notification exists, the first attempt landed.

***

## Webhooks

There are none — Betmatic does not call your servers. Poll the endpoints above for state changes, or request access to the private [WebSocket](/documentation/real-time/websocket.md) for pushed bet-history and odds events (email <support@betmatic.io>).

***

## Key Concepts

### Notifications vs Bet History

These are two distinct layers of data and it is important to understand the difference.

**A Notification** (`GET /notification/`) is a single bet instruction. When you call `POST /notification/create/`, one notification is created — regardless of how many bookmaker sessions place the bet. The notification tracks the overall intent: what you bet, on what, for how much, and the rolled-up result across all sessions.

**Bet History** (`GET /bet/`) is the per-bookmaker breakdown. For every notification, there is one bet record per session that attempted to place it. If a notification was sent to 8 sessions, there will be up to 8 bet records — each with its own odds, stake, and result at that specific bookmaker.

|              | `GET /notification/`                         | `GET /bet/`                                             |
| ------------ | -------------------------------------------- | ------------------------------------------------------- |
| Rows per bet | 1 (one per instruction)                      | 1 per bookmaker session                                 |
| Use for      | Checking what was bet and the overall result | Auditing exact odds, stakes, and outcomes per bookmaker |
| Outcome data | Aggregate `profit` across sessions           | Per-session `status` and `profit`                       |

***

## Quick Reference

| Method | Endpoint                          | Auth | Description                              |
| ------ | --------------------------------- | :--: | ---------------------------------------- |
| POST   | `/account/login/`                 |  No  | Get auth token                           |
| POST   | `/account/refresh_token/`         |  No  | Refresh token                            |
| POST   | `/account/signup/`                |  No  | Create account                           |
| POST   | `/account/logout/`                |  Yes | Disconnect bot session                   |
| POST   | `/account/forgot_password/`       |  No  | Send reset email                         |
| POST   | `/account/reset_password/`        |  No  | Set new password                         |
| GET    | `/bookie/names/`                  |  Yes | List all bookmakers                      |
| GET    | `/bookie/{id}/`                   |  Yes | Bookmaker capabilities                   |
| GET    | `/bookie/markets/`                |  Yes | Supported sports markets                 |
| GET    | `/bet/codes/`                     |  Yes | List racing codes                        |
| GET    | `/bet/markets/`                   |  Yes | List bet markets                         |
| GET    | `/competition/namecodes/`         |  Yes | Race schedule                            |
| GET    | `/event/list/`                    |  Yes | Sports events                            |
| GET    | `/event/{id}/`                    |  Yes | Event detail with markets and selections |
| GET    | `/notification/types/`            |  Yes | Supported notification types             |
| POST   | `/notification/create/`           |  Yes | Create a bet                             |
| GET    | `/notification/`                  |  Yes | List bets                                |
| GET    | `/notification/scheduled/`        |  Yes | List scheduled bets                      |
| POST   | `/notification/{id}/trigger/`     |  Yes | Trigger scheduled bet                    |
| POST   | `/notification/{id}/cancel/`      |  Yes | Cancel a bet                             |
| GET    | `/bet/`                           |  Yes | Granular bet history                     |
| GET    | `/bet/notification/{id}/`         |  Yes | Bet records for one notification         |
| POST   | `/bet/search/`                    |  Yes | Fetch known bet record IDs               |
| GET    | `/notification/{id}/race/detail/` |  Yes | Race detail for a notification           |
| GET    | `/bet/summary/`                   |  Yes | Bet summary stats                        |
| GET    | `/bookieaccount/`                 |  Yes | List sessions                            |
| GET    | `/bookieaccount/{id}/`            |  Yes | Single session detail                    |
| POST   | `/bookieaccount/control/{id}/`    |  Yes | Start/stop one session                   |
| POST   | `/bookieaccount/control/`         |  Yes | Start/stop all sessions                  |
| GET    | `/account/readiness/`             |  Yes | Bot readiness snapshot                   |
| GET    | `/account/connect_activity/`      |  Yes | Bot connection activity                  |
| GET    | `/bot/logs/`                      |  Yes | Customer-visible bot logs                |
| GET    | `/bot/logs/{notification_id}/`    |  Yes | Logs for one notification                |
| POST   | `/pick/tipster/publish/`          |  Yes | Publish a pick to a tip package          |
| POST   | `/pick/tipster/message/`          |  Yes | Send a pre-alert to package subscribers  |

***

## Pages

### Authentication

* [Authentication](/documentation/api-reference/authentication.md) — Login, signup, token refresh, logout, password reset

### Data

* [Bookmakers](/documentation/data/bookmakers.md) — All supported bookmakers with IDs and capabilities
* [Markets & Codes](/documentation/data/markets-and-codes.md) — Available markets and racing codes
* [Race Schedule](/documentation/data/race-schedule.md) — Upcoming racing fixtures across multiple days
* [Sports Events](/documentation/data/sports-events.md) — Upcoming sports events for AFL, NBA, Tennis, and more

### Placing Bets

* [Bet Types](/documentation/placing-bets/bet-types.md) — Fixed Wager, Fixed Profit, and High Odds First explained (plus package-generated Serial)
* [Create a Bet](/documentation/placing-bets/create-bet.md) — Full endpoint reference for `POST /notification/create/`
* [Session Targeting](/documentation/placing-bets/session-targeting.md) — Target specific bookmakers or sessions
* [Scheduling](/documentation/placing-bets/scheduling.md) — Save and auto-trigger bets
* [Bet Examples](/documentation/placing-bets/bet-examples.md) — 23 complete worked examples

**Scheduled Bets**

* [Scheduled Bets](/documentation/placing-bets/scheduled-bets.md) — View saved-but-not-yet-triggered bets
* [Trigger & Cancel](/documentation/placing-bets/trigger-and-cancel.md) — Fire or cancel a scheduled bet

### Bet History

* [List Bets](/documentation/bet-history/list-bets.md) — Paginated list of notifications (one per bet instruction)
* [Bet Records](/documentation/bet-history/bet-records.md) — Granular per-bookmaker placement history
* [Bet Lookup](/documentation/bet-history/bet-lookup.md) — Retrieve all placements for a notification or fetch known bet IDs
* [Bet Summary](/documentation/bet-history/bet-summary.md) — Aggregate win/loss counts

### Sessions & Account

* [Sessions](/documentation/sessions-and-account/sessions.md) — List, view, and control bookmaker sessions
* [Bot Diagnostics](/documentation/sessions-and-account/diagnostics.md) — Readiness, connection activity, and customer-visible logs

### Tipster Integrations

* [Tipster Publishing](/documentation/tipster-integrations/tipster-publishing.md) — Publish picks to an approved Tip Connect package

### Real-Time

* [WebSocket](/documentation/real-time/websocket.md) — Verified private real-time account events