# REST calls

Use REST when requested or when it is the available authenticated connection. The dataset workflow and result meanings in `SKILL.md` also apply here.

The base URL is `https://api.finbar.com/v1`. Use the user's configured authentication with `Authorization: Bearer <access token>`. Dataset operations require `datasets:read`, `entities:read` and `documents:read` permissions. Do not place credentials in saved datasets or messages. If access is missing, explain the required connection rather than attempting paid calls repeatedly.

| MCP operation | REST equivalent |
| --- | --- |
| `build_dataset` | `POST /datasets/build` |
| `update_dataset` | `POST /datasets/update` |
| `get_dataset_run` | `GET /datasets/runs/{run_id}` |
| `cancel_dataset_run` | `POST /datasets/runs/{run_id}/cancel` |
| `get_dataset_result` | `POST /datasets/runs/{run_id}/result` |
| Complete JSON download | `GET /datasets/runs/{run_id}/bundle` |

For Build/Update, move `idempotency_key` from the MCP example into the `Idempotency-Key` HTTP header. Send the remaining JSON with `Content-Type: application/json`. A successful start returns HTTP 202 and a run ID; it does not mean research is complete.

For result retrieval, the run ID belongs in the URL, not the JSON body. Send `{}` for the first page. Subsequent bodies contain the returned cursor, for example `{"cursor": "<next_cursor>"}`. Optional `row_id`, exact `period` and `limit` filters must stay the same across pages. `limit` defaults to 25 and cannot exceed 100; the byte limit can produce smaller pages.

Bundle downloads support up to 2 MiB. If the service returns `dataset_bundle_too_large`, use result pages. Keep the full structured result in the saved file; summarize it for the user. Retrieve error details and request IDs from responses, and honor the returned retry delay when rate-limited.

Use [public API documentation](https://docs.finbar.com/api-mcp/api) for authentication and company discovery. Use the documented API contract rather than guessing routes for MCP tool names.