> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apilens.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Building an SDK

> Authoritative guidance for the official API Lens Python SDK and what is supported today.

## SDK Goal

Your SDK should make ingest trivial:

* capture request lifecycle data
* normalize payloads
* batch and flush safely
* retry on transient failures

## Official Python SDK

API Lens ships an official Python SDK in `sdks/python`, published as `apilenss`.

Supported today:

* FastAPI (`apilens.fastapi` middleware)
* Flask (`apilens.flask` wrapper)
* Django / Django Ninja (`apilens.django` middleware)

Planned / not supported yet (do not wire these): Starlette, Litestar, BlackSheep. We’ll add them when they reach parity; track in the SDK repo issues.

Get the exact install and middleware snippets in `sdk/python-setup.mdx`. Use extras for the framework you need:

```bash theme={null}
pip install "apilenss[fastapi]"
pip install "apilenss[flask]"
pip install "apilenss[django]"
```

Minimal FastAPI example (supported):

```python theme={null}
from fastapi import FastAPI
from apilens.fastapi import ApiLensMiddleware

app = FastAPI()
app.add_middleware(
    ApiLensMiddleware,
    api_key="your_app_api_key",
    base_url="https://api.apilens.ai/api/v1",
    env="production",
    enable_request_logging=True,
    log_request_headers=True,
    log_request_body=True,
    log_response_body=True,
)
```

## Recommended Pipeline

1. Intercept request start/end timestamps
2. Build normalized request item
3. Add to in-memory queue
4. Flush queue on interval or size threshold
5. POST to `/ingest/requests` with API key

## Required Headers

* `Content-Type: application/json`
* `X-API-Key: <app_api_key>`

## Suggested Defaults

* Batch size: 100-500
* Flush interval: 2-5 seconds
* Max retries: 3
* Backoff: exponential with jitter

## Normalization Rules

* Uppercase HTTP method
* Remove query string from route path
* Convert response time to milliseconds
* Include environment (`production`/`staging`)

## Minimal Node Example

```ts theme={null}
const payload = {
  requests: [
    {
      timestamp: new Date().toISOString(),
      environment: process.env.NODE_ENV === "production" ? "production" : "development",
      method: "GET",
      path: "/v1/orders",
      status_code: 200,
      response_time_ms: 96,
      request_size: 240,
      response_size: 1200,
      ip_address: "",
      user_agent: "my-sdk/0.1.0"
    }
  ]
};

await fetch("https://api.apilens.ai/api/v1/ingest/requests", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.APILENS_API_KEY as string
  },
  body: JSON.stringify(payload)
});
```

## Endpoint Checklist

When generating SDK clients for dashboard APIs, include:

* Auth endpoints (`/auth/*`)
* App CRUD (`/apps/*`)
* Endpoint stats + options (`/apps/{slug}/endpoint-stats`, `/endpoint-options`)
* Analytics endpoints (`/apps/{slug}/analytics/*`)
* Ingest endpoint (`/ingest/requests`)

## Versioning Advice

* Keep schema adapters per API version
* Hide wire schema behind typed SDK interfaces
* Add integration test against a running APILens local env