Metadata-Version: 2.4
Name: invinite_data_api
Version: 4.0.0
Summary: Typed Python client for the Invinite Data API
Home-page: 
Author: OpenAPI Generator community
Author-email: OpenAPI Generator Community <team@openapitools.org>
Project-URL: Homepage, https://data.invinite.com
Project-URL: Documentation, https://data.invinite.com/docs/sdks
Project-URL: Repository, https://github.com/outraday-org/invinite-data-api
Keywords: OpenAPI,OpenAPI-Generator,Invinite API
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: urllib3<3.0.0,>=2.1.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: pydantic>=2.11
Requires-Dist: typing-extensions>=4.7.1
Dynamic: author

<!--
  Canonical, hand-written README for the invinite-data-api PyPI package.
  scripts/package-data-sdk.mjs copies this over sdks/data/python/README.md (a git-ignored,
  generator-default file) before the Python build, so this is the page PyPI renders
  (pyproject.toml `readme = "README.md"`). Edit here, not in the generated tree.
  scripts/check-data-sdk-names.ts asserts every API class and `api.<method>(` call
  named below exists in the generated client.
-->

# invinite-data-api

Typed Python client for the [Invinite Data API](https://data.invinite.com) `/v2` at
`api.data.invinite.com` — companies, standardized and as-reported financials, metrics,
SEC filings and documents, 13F holdings, insider trades, IPOs, earnings events and
transcripts, guidance, investor documents and news. It is generated from the API's own
OpenAPI document, so its request and response models match the
[reference](https://data.invinite.com/docs).

The client is built on urllib3 + pydantic, needs Python 3.9+, and imports as
`invinite_data_api`.

## Install

```bash
pip install invinite-data-api
```

## Authentication

Create a `Configuration` with your `invd_` Data API key (or an Invinite Data OAuth
access token) as the access token. The client sends it as an
`Authorization: Bearer <token>` header on every request.

```python
import os
import invinite_data_api

config = invinite_data_api.Configuration(access_token=os.environ["INVINITE_DATA_API_KEY"])
```

## Quickstart

```python
import os
import invinite_data_api
from invinite_data_api import CompaniesApi

config = invinite_data_api.Configuration(access_token=os.environ["INVINITE_DATA_API_KEY"])

with invinite_data_api.ApiClient(config) as client:
    api = CompaniesApi(client)
    page = api.list_companies(q="NVDA", limit=5)
    for company in page.data:
        print(company.ticker, company.name, company.cik)
    nvidia = api.get_company(company="NVDA")
```

Every API class is named after a docs group (`CompaniesApi`, `FinancialsApi`,
`FilingsApi`, `EventsApi`, …) and every method after the operation's verb-first
`operationId` in snake_case (`list_filings`, `get_company`). Arguments keep the wire's
snake_case names; a range filter's dot becomes `_` (`filed_at_gte` for `filed_at.gte`)
and a Python keyword gets a `var_` prefix. The company is always a filter: `company`
takes a ticker or a CIK, or a comma list of up to 50. Date parameters take a
`datetime.date`.

## Lists, cursors and the pager

Every list answers ONE envelope: `data`, `has_more`, `next_cursor`, `meta`. Pass
`next_cursor` back as `cursor` with the SAME filters (changed filters answer
`400 cursor_mismatch`) until `has_more` is false — or let the pager do it:

```python
from invinite_data_api import FilingsApi
from invinite_data_api.pagination import iterate_items, iterate_pages

with invinite_data_api.ApiClient(config) as client:
    api = FilingsApi(client)
    for filing in iterate_items(api.list_filings, company="AAPL", form="10-K", limit=100):
        print(filing.accession, filing.form, filing.filed_at)
    for page in iterate_pages(api.list_filings, company="AAPL", max_pages=3):
        print(len(page.data), page.meta.coverage.state if page.meta.coverage else None)
```

Each page is one billed call. `meta.coverage.state` is `pending` / `partial` /
`complete`: a scope the store is still filling answers `200` with `data: []` and
`pending`, never an error.

## Reading credits

Each call reports what it cost in the `X-Credits-Charged` and `X-Credits-Remaining`
response headers. Every method has a `…_with_http_info` twin that returns the headers
beside the parsed value. `response.headers` is a plain `dict` keyed as the server sent the
names, so look them up case-insensitively:

```python
response = api.list_filings_with_http_info(company="AAPL")
headers = {name.lower(): value for name, value in response.headers.items()}
print(headers["x-credits-charged"])
print(headers["x-credits-remaining"])
page = response.data
```

## Error handling

On a non-2xx response the client raises `ApiException` (with per-status subclasses).
The body is an RFC 9457 `application/problem+json` document with a stable `code`
(`not_covered`, `invalid_parameter`, `cursor_mismatch`, `rate_limited`, …) and a
`request_id`. On `429` and `503`, wait for the `Retry-After` header before retrying.

```python
import json
from invinite_data_api.exceptions import ApiException

try:
    api.list_filings(company="NOPE")
except ApiException as error:
    problem = json.loads(error.body) if error.body else {}
    print(error.status, problem.get("code"), problem.get("detail"), problem.get("request_id"))
```

## Upgrading from 3.x

4.0.0 is generated from the `/v2` API only; the `/v1` classes are gone (the `/v1` routes keep
working until their announced sunset). Lists use the cursor envelope above instead of
`offset` / `next_url`, errors are problem documents instead of `{"error", "message"}`, and
booleans are real booleans.

| 3.x | 4.0.0 |
|---|---|
| `CompanyApi` | `CompaniesApi` (`list_companies`, `get_company`, filers, people) |
| `Standardized…Api`, `AsReported…Api` (24 classes) | `FinancialsApi` (6 operations: basis × plain / detailed / presentation, `statement` filter) |
| `FinancialMetricsApi`, `SegmentedFinancialsApi` | `MetricsApi` |
| `SECApi`, `InstitutionalOwnershipApi` | `FilingsApi`, `DocumentsApi`, `HoldingsApi` |
| `InsiderTradesApi`, `IPOsApi`, `NewsApi` | same class names, `/v2` operations |
| `EarningsCallsApi` | `EventsApi`, `TranscriptsApi`, `CallAnalyticsApi`, `GuidanceApi`, `InvestorDocumentsApi`, `WebhooksApi` |
| `MarketApi`, `MetadataApi` | `ReferenceApi`, `CatalogApi` |
| `AccountApi` | `AccountApi` (`get_me`, `get_my_usage`) |
| `HealthApi`, `StatusApi` | not in 4.0.0 (plain `GET /health`, `/status`) |

## Not in this client

- The realtime stream at `/v2/stream` (WebSocket) —
  [realtime docs](https://data.invinite.com/docs/realtime).
- Webhook signature verification — [webhook docs](https://data.invinite.com/docs/webhooks).
  Managing webhook subscriptions IS in the client (`WebhooksApi`).

## Regeneration

This client is a generated artifact; if a type looks wrong, the fix belongs in the API's
contract, and regenerating re-derives every model. Releases are published on
`data-sdk-v*` tags.

## Links

- [Data API docs](https://data.invinite.com/docs)
- [SDKs](https://data.invinite.com/docs/sdks)
- [Repository](https://github.com/outraday-org/invinite-data-api)

## License

MIT
