# Aira Connect API

> Server-to-server API over an Aira organization: company search, company detail and the identity behind an API key. Version 1.

## Quick start

Base URL: https://ai.aira.app/api
Auth: `Authorization: Bearer aira_live_…` on every request. Keys are issued in Connect settings and are unscoped.
Envelope: successes are `{ "data": …, "meta": … }`, errors are `{ "error": { "code", "message" }, "request_id" }`.
Pagination: collections are cursor based. Echo `meta.next_cursor` back as `cursor`.
Versioning: the version is in the path. Changes within `/v1` are additive only.

This is a server-side API. No CORS headers are sent, and state-changing requests carrying an `Origin` header are rejected.
There is no sandbox and no test key: every key is live and portfolio writes are real. The testing guide linked under Docs explains how to build against it safely.

## Endpoints

- `GET /v1/me`: Retrieve the organization the API key belongs to (operationId: `getMe`)
- `POST /v1/companies/search`: Search companies (operationId: `searchCompanies`)
- `GET /v1/companies/{id}`: Retrieve a company (operationId: `getCompany`)
- `GET /v1/companies/{id}/contacts`: List a company’s contacts (operationId: `listCompanyContacts`)
- `GET /v1/companies/{id}/filings`: List a company’s filings (operationId: `listCompanyFilings`)
- `GET /v1/companies/{id}/news`: List one company’s news (operationId: `listCompanyNews`)
- `GET /v1/news`: List news for your portfolio (operationId: `listNews`)
- `POST /v1/portfolio/companies`: Add companies to your portfolio (operationId: `addPortfolioCompanies`)
- `GET /v1/filings`: List filings for your portfolio (operationId: `listFilings`)
- `GET /v1/similar-companies`: List similar companies (operationId: `listSimilarCompanies`)
- `GET /v1/quotas`: Retrieve your current quota usage (operationId: `getQuotas`)

## Errors (22 codes)

Branch on `error.code`, never on the message.

- invalid_cursor (HTTP 400, not retryable): The `cursor` was not one this API issued, or is old enough that it can no longer be decoded.
- invalid_id_prefix (HTTP 400, not retryable): An id was well formed but carried the wrong resource prefix, for example a `pfe_` id where a `cmp_` id belongs.
- invalid_request (HTTP 400, not retryable): The request did not match the documented schema.
- limit_exceeds_maximum (HTTP 400, not retryable): The `limit` you asked for is above the maximum this endpoint accepts.
- query_invalid (HTTP 400, not retryable): A search query used an unknown field, an operator that field does not support, a value of the wrong type, a node with more than one key, or no query at all.
- query_too_complex (HTTP 400, not retryable): A search query went past a published complexity limit: nesting depth, total leaves, branches in a single `or`, or the length of an `in` list.
- invalid_api_key (HTTP 401, not retryable): The key does not authenticate anything. Revoked, expired and never-issued keys all return this same code, so the response tells you nothing about which of the three it was.
- missing_api_key (HTTP 401, not retryable): The request carried no `Authorization` header, or one this API could not parse.
- company_not_in_portfolio (HTTP 403, not retryable): The company exists and you can read its summary, but it is not in your portfolio — and its contacts are only available for companies you hold.
- monitored_company_limit_reached (HTTP 403, not retryable): Your organization is at its monitored-company limit, so this company was not added. Every company in your portfolio carries ongoing monitoring, and that ceiling is separate from your portfolio-add allowance.
- origin_not_allowed (HTTP 403, not retryable): A state-changing request arrived with an `Origin` header, which means it came from a browser.
- portfolio_add_limit_reached (HTTP 403, not retryable): Your organization has spent its portfolio-add allowance for the current period, so this company was not added. Quota counts distinct companies, so re-adding one you already hold never causes this.
- not_found (HTTP 404, not retryable): The resource does not exist, or is not visible to your organization.
- daily_row_limit_exceeded (HTTP 429, retryable, honour the Retry-After header): Your organization reached its daily limit for company records. The limit counts records served across every endpoint that returns companies, and it resets at midnight UTC.
- rate_limit_exceeded (HTTP 429, retryable, honour the Retry-After header): Your organization sent more requests per minute than this class of endpoint allows. The budget is shared by every key your organization holds, so issuing a second key does not double it.
- research_concurrency_exceeded (HTTP 429, retryable, honour the Retry-After header): Your organization already has the maximum number of research requests running. Research is limited by how many run at once rather than by how fast you submit them, and requests started in the Aira app count towards the same ceiling.
- internal_error (HTTP 500, retryable, no Retry-After header is sent, back off yourself): Something failed on our side.
- api_unavailable (HTTP 503, retryable, no Retry-After header is sent, back off yourself): The API is switched off, either for your organization or for everyone. Your key is fine.
- filings_unavailable (HTTP 503, retryable, no Retry-After header is sent, back off yourself): The filings data source did not respond in time. Your request was valid and your cursor is still good.
- news_unavailable (HTTP 503, retryable, honour the Retry-After header): We could not read the news corpus for your request. The upstream store timed out or answered with something we will not serve.
- similar_companies_unavailable (HTTP 503, retryable, no Retry-After header is sent, back off yourself): The lookalike feed could not be read. This is an upstream failure, not a statement about your data.
- search_timeout (HTTP 504, retryable, no Retry-After header is sent, back off yourself): A search ran longer than the upstream budget allows. A broad query over a large market is the usual cause.

## Docs

- [OpenAPI document](https://developers.aira.app/openapi.json): the machine-readable contract, generated from the running implementation.
- [Complete reference](https://developers.aira.app/llms-full.txt): every operation, field and error code in one file.
- [API reference](https://developers.aira.app): the same contract rendered, with copy-pasteable examples, the error codes reference and the testing guide.