# GreenHill ReportQuest API

> An authenticated investment-data and reporting API. Start here when the user gives you a ReportQuest API key, personal access token (PAT), or access token and asks you to answer questions or build reports from ReportQuest data.

Base URL: https://api.reportquest.com

Only send credentials to this base URL. Never print, log, persist, or place credentials in a URL, query string, report, or diagnostic response.

Determine the credential type without asking the user:

- A ReportQuest access token currently has the JWT structure of exactly three non-empty Base64URL segments separated by two periods. If the supplied value starts with `Bearer `, use the value after that prefix. Use this credential directly on authenticated requests and do not call the token exchange endpoint.
- A ReportQuest API key or PAT is exactly 65 characters: a leading `1` followed by 64 characters from the uppercase Base32 alphabet `A-Z` and `2-7`, with no periods. If the supplied value starts with `Token ` or `Bearer `, use the value after that prefix. Follow the PAT guidance below.
- If a credential matches neither format, do not send it to the API. Report that it is not a recognized ReportQuest credential.

ReportQuest API keys and PATs remain valid until they expire or are revoked. Use them directly as Bearer credentials for protected requests.

## Authentication

For protected requests, send either the PAT or an API-issued access token:

```http
Authorization: Bearer <PAT_OR_ACCESS_TOKEN>
```

Exchanging a PAT for a time-limited API JWT is optional. To do so, make this request with an empty body:

```http
POST https://api.reportquest.com/api/v1/Auth/Token
Authorization: Token <API_KEY_OR_PAT>
```

Capture `access_token`, `token_type`, `expires_in`, and `expires_at`. The exchange does not invalidate the PAT. The returned access token can be used on subsequent requests:

```http
Authorization: Bearer <ACCESS_TOKEN>
```

If the user supplied an access token, skip the exchange and use it directly. If the user supplied a PAT, use it directly unless the current workflow specifically benefits from a time-limited JWT. Do not send an access token to the token exchange endpoint.

## Required discovery sequence

Before retrieving account or report data, use the JWT or PAT to retrieve:

1. `GET /api/v1/Users/WhoAmI`
2. `GET /swagger/v1/swagger.json`
3. `GET /api/v1/Reporting/Recipes`

Use WhoAmI to confirm the authenticated client and user are consistent with the user's request. Stop before retrieving client data if they conflict.

OpenAPI is authoritative for routes, authorization, parameters, schemas, units, dates, null behavior, ordering, warnings, and errors. Reporting Recipes are authoritative for cross-operation composition, field selection, preservation rules, financial-safety rules, and unsupported assumptions. This public bootstrap document only explains how to obtain those authenticated contracts and does not override them.

## Account identity

`accountId` is an internal GreenHill identifier with no semantic meaning to an API user. It is durable for the current API session and expected to remain stable for the foreseeable future, but consumers should not persist it long-term because it may change in the future.

Users normally identify accounts by account number. Resolve an account number to `accountId` with either:

- `GET /api/v1/Account?accountNumber=<ACCOUNT_NUMBER>` for a direct single-account lookup. Include `accountGroupId` when needed to disambiguate.
- `GET /api/v1/Accounts?searchText=<SEARCH_TEXT>` to search entitled accounts by account number, account name, or short name.

After resolving the account, use its `accountId` for other endpoints during the current task or API session.

## Agent resources

- [Agent getting-started guide](https://api.reportquest.com/agent-guide.md): Public credential handling, account resolution, discovery, safety, and troubleshooting instructions.
- [Human landing page and interactive documentation](https://api.reportquest.com/): Public; the interactive documentation prompts for a PAT.
- [OpenAPI contract](https://api.reportquest.com/swagger/v1/swagger.json): Requires an API-issued JWT or PAT using the Bearer scheme.
- [Reporting recipes](https://api.reportquest.com/api/v1/Reporting/Recipes): Requires the same Bearer credential.