# Market API

Your markets and their companies on a scoped bearer key, with the same rows as the token feed.

Three routes over your own markets, on a bearer key holding `markets:read`. Building and refreshing a market stays in the browser.

```bash
curl -s -H 'Authorization: Bearer pxk_…' 'https://prospex.ch/api/v1/markets'
curl -s -H 'Authorization: Bearer pxk_…' 'https://prospex.ch/api/v1/markets/41'
curl -s -H 'Authorization: Bearer pxk_…' \
  'https://prospex.ch/api/v1/markets/41/companies?bucket=core&band=strong,good'
```

## What each route costs

| Route | What it costs |
| --- | --- |
| GET /api/v1/markets | Your markets, with their state and their Core count. Costs no rows. |
| GET /api/v1/markets/\<id> | One market's definition, the queries the build ran, and its state. Costs no rows. |
| GET /api/v1/markets/\<id>/companies | One page of the ranking. One row of the daily budget per company. |

The two metadata routes spend nothing. Reading the companies costs a row each.

Another account's market answers **404**.

## Resolved paths

| Name | Path |
| --- | --- |
| market_index | /api/v1/markets |
| market_detail | /api/v1/markets/\<str:market_id> |
| market_companies | /api/v1/markets/\<str:market_id>/companies |

## Parameters

| Parameter | Meaning |
| --- | --- |
| bucket | `core` (the default) or `explore`. The token feed calls this `tab`; both are published and neither is being renamed. |
| band | `strong`, `good`, `possible` or `weak`, repeated or comma-separated. Narrows what this page shows within the ranking. |
| limit | Rows per page, up to 100. |
| cursor | Opaque, and carrying the build it was issued under. |

A parameter this route does not accept answers **400 `unknown_parameter`**. That includes `tab`, which is the token feed's name for `bucket`.

## A row

A row here is identical to a row from the market's token feed. The [market feed page](https://prospex.ch/docs/market-feed/) has the field table.

Each row carries up to 3 recent events on the company, so a workflow that has just been told "this company fits, and here is why" also knows what kind of week the company is having.

## Fit is a word

| Band | What it claims |
| --- | --- |
| strong | Answers your definition at least as well as the customers you called ideal. |
| good | A clear match on your definition, below the anchored cut. |
| possible | Worth a look. Partial match on your definition. |
| weak | Ranked below both buckets. |

No route carries a numerical score. The underlying number varies by query and by pool, so it is not comparable across markets. Use the band word.

## Pagination

Follow `next_url`. It is absolute, carries every parameter you sent, and carries no credential.

The cursor carries the build it was issued under. A market's order changes only when a build refreshes it, so a cursor from an older build answers **400 `invalid_parameter`**. Start again without a cursor.

Maximum page size 100. `version` is `1`, the same contract the token feed publishes.