# How the API Works

Alphanume’s API is designed to be simple, predictable, and composable.\
All endpoints follow the same core request structure: optional authentication, optional filters, and deterministic responses.

Requests are made via standard HTTP `GET` calls with query parameters.

***

### Authentication & Access

API keys are optional.

* **Without an API key**\
  Requests are supported, but results are limited to a small sample per request.
* **With an active API key**\
  Request limits are removed and the full dataset is available.

API keys are issued automatically after creating a subscription and are emailed upon signup.

***

### Core Request Parameters

#### `api_key` (optional)

Your unique API key.

* Enables full dataset access
* Removes per-request record limits
* Required for production usage

If omitted, the API returns a limited subset suitable for exploration.

***

#### `ticker` (optional)

Filter filings by stock ticker.

* Case-insensitive
* Automatically normalized to uppercase
* Matches exact tickers (e.g. `AAPL`, `TSLA`, `NVDA`)

If omitted, relevant data across all tickers are returned.

***

### Date Filtering

The API supports flexible date-based filtering using four parameters.

All dates **must** be provided in the following format:

```
YYYY-MM-DD
```

#### Supported Date Parameters

| Parameter  | Description                   |
| ---------- | ----------------------------- |
| `date_gte` | Greater than or equal to date |
| `date_lte` | Less than or equal to date    |
| `date_gt`  | Strictly greater than date    |
| `date_lt`  | Strictly less than date       |

You may use **any combination**, provided the range is logically valid.

***

#### Valid Date Ranges

The API validates all date logic before executing a query.

Examples of valid usage:

* `date_gte` & `date_lte`
* `date_gt` & `date_lt`
* single-sided filters (e.g. only `date_gte`)

Examples of invalid usage:

* `date_lt` earlier than `date_gte`
* `date_lte` earlier than `date_gt`
* improperly formatted dates

Invalid date ranges or formats return a descriptive `400` error.

***

### Pagination & Limits

#### Record Limits

* Requests **without an API key** return a limited number of records per request.
* Requests **with an API key** return up to 5,000 records.

Results are ordered chronologically by date.

> Note: If you are querying large date ranges with an API key, we recommend filtering by ticker or date windows for optimal performance.

***

### Response Structure

All responses follow a consistent structure:

* `count` — number of records returned
* `data` — list of records

Date and timestamp fields are returned as ISO-formatted strings (`YYYY-MM-DD`) for easy parsing across languages.

***

### Example Request

{% code overflow="wrap" %}

```sh
GET https://api.alphanume.com/v1/dilution
    ?ticker=LGMK
    &date_gte=2024-12-01
    &date_lte=2025-02-01

```

{% endcode %}

{% code overflow="wrap" %}

```json
{
  "count": 1,
  "data": [
    {
      "date": "2025-01-03",
      "filing_timestamp": "2025-01-03T17:41:23-05:00",
      "ticker": "LGMK",
      "company_name": "LogicMark, Inc.",
      "market_cap_at_filing": 3069127.52,
      "dilutive": 1,
      "resale": 0,
      "shares_offered": 2528684.0,
      "became_effective": 1,
      "effective_date": "2025-02-18",
      "days_to_effective": 46.0,
      "offering_withdrawn": 0,
      "withdrawal_date": "",
      "days_to_withdrawal": null,
      "root_file_number": "333-284135",
      "accession_number": "0001213900-25-000848",
      "filing_url": "https://www.sec.gov/Archives/edgar/data/1566826/000121390025000848/0001213900-25-000848-index.htm",
      "last_updated": "2025-12-16 10:36:17.239666-05:00"
    }
  ]
}

```

{% endcode %}

***

### Common Usage Patterns

Typical workflows include:

* Pulling recent filings for a specific ticker
* Scanning dilution events over a date range
* Monitoring lifecycle updates (effective / withdrawn status)
* Ingesting filings into research or trading pipelines

The API is stateless — each request is independent and reproducible.

***

### Error Handling

If a request cannot be fulfilled, the API returns:

* a descriptive error message
* the reason for failure
* a standard HTTP status code

Common error cases include:

* invalid date formats
* logically invalid date ranges
* malformed parameters

***

### Design Philosophy

Alphanume’s API is built to be:

* **predictable** — no hidden behavior
* **transparent** — clear validation and errors
* **composable** — filters stack cleanly
* **production-ready** — no magic defaults

If you can construct one request, you can construct them all.