# API quickstart

Authenticate and make your first company search request.

Source: <https://docs.finbar.com/api-mcp/api>

The REST API accepts HTTPS requests and returns JSON. Its base URL is:

```text
https://api.finbar.com/v1
```

This walkthrough uses `curl` from a terminal. You need a Finbar account with
API access and a REST API credential from the web app's **API** panel.

## 1. Get an access token

Follow [Authentication](https://docs.finbar.com/api-mcp/authentication.md) to create a credential and
exchange its client ID and secret for an access token. Request
`entities:read` permission for this example.

Set `ACCESS_TOKEN` in your terminal to the returned `access_token`.

## 2. Search for a company

```bash
curl --fail-with-body --silent --show-error --get \
  'https://api.finbar.com/v1/entities' \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode 'q=Apple' \
  --data-urlencode 'limit=5'
```

`GET /entities` searches the companies available to your account. `q` is the
search text; `limit` is the requested number of matches. The authorization
header supplies your token.

**GET /v1/entities — 200 response**

Example response. IDs and values are illustrative.

```json
{
  "entities": [
    {
      "entity_id": "O-03049bdc0cb94012b761a4c3046c2a2d",
      "name": "Apple Inc.",
      "score": 0.98
    }
  ],
  "next_cursor": "eyJ2IjoxLCJiaW5kaW5nIjoiLi4uIn0"
}
```

## 3. Select the company

Check the `name` in the returned `entities` array and save the matching
`entity_id`. “Entity” is the API's term for a company record. Its ID is used
in subsequent requests; a company name or ticker cannot replace it.

If `entities` is empty, no available company matched. Try a different name
or ticker. If there are several matches, [read company details](https://docs.finbar.com/api-mcp/entities.md)
to confirm the one you need.

## Make the next request

| Task                                | Guide                                                                      | Additional permission |
| ----------------------------------- | -------------------------------------------------------------------------- | --------------------- |
| Read company information            | [Companies](https://docs.finbar.com/api-mcp/entities.md)                   | None                  |
| Read company wiki                   | [Companies](https://docs.finbar.com/api-mcp/entities.md#read-company-wiki) | None                  |
| Find reports and read their content | [Documents](https://docs.finbar.com/api-mcp/documents.md)                  | `documents:read`      |
| Discover financial metrics          | [Dataset catalogue](https://docs.finbar.com/api-mcp/catalogue.md)          | `datasets:read`       |
| Retrieve financial values           | [Dataset queries](https://docs.finbar.com/api-mcp/dataset-query.md)        | `datasets:read`       |
| Check request usage                 | [Usage and limits](https://docs.finbar.com/api-mcp/usage.md)               | `usage:read`          |

For additional pages of results and failed requests, see
[errors and pagination](https://docs.finbar.com/api-mcp/errors.md).