# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.alphanume.com/documentation/overview/how-the-api-works.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.