# South African Premier Soccer League — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Access real-time South African Premier Soccer League data including live scores, fixtures, results, standings, and match details. Search for clubs, news articles, and other PSL information to stay updated on the league.

**Category:** Sports | **Website:** [psl.co.za/](https://psl.co.za/) | **Docs:** [parse.bot/marketplace/96b972a0-e8bc-47ea-8de9-17f325892a05/psl-co-za-api](https://parse.bot/marketplace/96b972a0-e8bc-47ea-8de9-17f325892a05/psl-co-za-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/south-africa-psl/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Get clubs list

Retrieve a list of all clubs across divisions from the PSL website navigation. Returns clubs grouped by division (Premier Division and National First Division).

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/south-africa-psl/get-clubs-list \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get fixtures

Retrieve upcoming match fixtures for a given tournament. Returns all scheduled matches with dates, times, teams, and venues. May return an empty array when no fixtures are scheduled (e.g., end of season).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `team` | string | No | Filter fixtures by team name (exact match, case-insensitive) |
| `tournament` | string | No | Tournament slug |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/south-africa-psl/get-fixtures \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"team":"<string>","tournament":"<string>"}'
```

### Get live scores

Retrieve currently live match scores. Returns an empty list with a descriptive message when no matches are live.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/south-africa-psl/get-live-scores \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get match details

Retrieve detailed information for a specific match including stats, lineups, and commentary. The match_id can be obtained from the get_results endpoint.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `match_id` | string | Yes | Match ID slug from get_results (e.g., 2593619-durban-city-vs-amazulu-fc) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/south-africa-psl/get-match-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"match_id":"<string>"}'
```

### Get news article

Retrieve full content of a news article including title, date, body text, and images. The article_id can be obtained from the get_news_list endpoint.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `article_id` | string | Yes | Article ID slug from get_news_list (e.g., 5615164-city-promotion-hopes-dashed-in-magesi) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/south-africa-psl/get-news-article \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"article_id":"<string>"}'
```

### Get news list

Retrieve latest news articles from the PSL website. Returns article summaries with IDs, titles, dates, URLs, and thumbnails.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/south-africa-psl/get-news-list \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get results

Retrieve past match results for a given tournament. Returns completed matches with scores, teams, venues, and match IDs that can be used with get_match_details.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `team` | string | No | Filter results by team name (exact match, case-insensitive) |
| `tournament` | string | No | Tournament slug |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/south-africa-psl/get-results \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"team":"<string>","tournament":"<string>"}'
```

### Get standings

Retrieve the current league standings/log table for a tournament. Returns all teams with position, points, wins, draws, losses, and goal statistics.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `tournament` | string | No | Tournament slug |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/south-africa-psl/get-standings \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"tournament":"<string>"}'
```

### Search items

Search for articles on the site. Note: This feature may be temporarily unavailable on the PSL website.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search keyword |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/south-africa-psl/search-items \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.