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

# Quickstart

> From zero to first successful response in minutes, with production-ready patterns

<Note>
  Read time: 1–3 minutes. This guide works for complete beginners and gives experienced teams copy-pasteable patterns that are safe to take to production.
</Note>

## What you’ll build

You will:

1. Create an API key.
2. Install the official SDKs.
3. Call `/v1/extract` to get normalized structured JSON from a real page.
4. Call `/v1/search` to get an answer with sources.
5. Understand the response envelope so you can log, monitor, and handle errors correctly.

All examples use:

* Authentication via `X-API-Key`.
* The new endpoints: `/v1/extract`, `/v1/search`, and `/v1/perform` (preview).
* The current envelope shape and field ordering.

## 1. Create an API key

Open [https://uapi.nl/api/](https://uapi.nl/api/) and create an API key.

Keep it in a secrets manager or password vault. Never embed it in frontend code or public repos.

<Tip>
  All examples read your key from the `UAPI_API_KEY` environment variable. Set it once, use it everywhere.
</Tip>

## 2. Install the official SDKs (recommended)

<Tabs>
  <Tab title="Python">
    ```bash theme={null}
    pip install usdk
    ```
  </Tab>

  <Tab title="TypeScript / Node.js">
    ```bash theme={null}
    npm install usdk-js
    # or
    yarn add usdk-js
    # or
    pnpm add usdk-js
    ```
  </Tab>
</Tabs>

You can always call the HTTP API directly; the SDKs wrap best practices for retries, timeouts, errors, and typing.

## 3. First extraction with `/v1/extract`

The `/v1/extract` endpoint turns a public URL into normalized, schema-aligned JSON.

### Python (SDK)

```python theme={null}
import os
import uapi  # provided by the usdk package
from uapi import uAPI

client = uAPI(
    api_key=os.environ.get("UAPI_API_KEY"),  # or omit to use env automatically
)

response = client.extract(
    url="https://finance.yahoo.com/quote/NVDA/",
    # x_cache_ttl=300,  # optional: cache this result (0-3600 seconds)
)

print(response.to_dict())
```

### Node.js / TypeScript (SDK)

```typescript theme={null}
import uAPI from 'usdk-js';

const client = new uAPI({
  apiKey: process.env['UAPI_API_KEY'], // or rely on default env-based loading
});

const response = await client.extract({
  url: 'https://finance.yahoo.com/quote/NVDA/',
  // xCacheTtl: 300, // optional: cache hint in seconds (0-3600)
});

console.log(response);
```

### Raw HTTPS (cURL)

```bash theme={null}
curl -s "https://api.uapi.nl/v1/extract?url=https%3A%2F%2Ffinance.yahoo.com%2Fquote%2FNVDA%2F" \
  -H "X-API-Key: ${UAPI_API_KEY}"
```

<Check>
  If everything is wired correctly, you receive HTTP 200, `"success": true`, and a `data` object with normalized fields (for example, `price`, `percent_change`, `currency`, `timestamp`).
</Check>

## 4. Understand the response envelope

This is a representative envelope for `/v1/extract` (values truncated):

```json (truncated) theme={null}
{
  "id": "1f7015c8-b10c-45a3-ad39-3cd3e296688a",
  "success": true,
  "data": {
    "name": "NVIDIA Corporation",
    "symbol": "NVDA",
    "price": 180.28,
    "percent_change": -0.49,
    "currency": "USD",
    "timestamp": "2025-10-23T09:05:35Z"
  },
  "error": null,
  "uapi_version": "1.2.5",
  "schema_version": "v1",
  "request": {
    "endpoint": "/v1/extract",
    "method": "GET",
    "params": {
      "url": "https://finance.yahoo.com/quote/NVDA/"
    },
    "payload": {},
    "status_code": 200,
    "requested_at": "2025-10-23T09:05:18.802Z",
    "served_at": "2025-10-23T09:05:35.299Z",
    "elapsed_ms": 16497,
    "cache_info": {
      "is_cached": false,
      "cached_at": null,
      "expires_at": null
    }
  },
  "deprecation_warnings": []
}
```

Key points:

* `id` is stable per request: log this for debugging and billing checks.
* `success` tells you if usable structured data is present.
* `data` is the normalized object; its shape depends on the page’s schema.
* `error` is null on success, or an object with stable `code` and `message`.
* `request` contains everything you need for observability.
* `uapi_version` and `schema_version` let you pin behavior over time.

<Tip>
  In production, log at least `id`, `success`, `request.endpoint`, `request.status_code`, and a compact summary of `error` when present.
</Tip>

## 5. Ask a sourced question with `/v1/search`

Use `/v1/search` when you want a direct answer plus sources.

### Python (SDK)

```python theme={null}
import os
from uapi import uAPI

client = uAPI(api_key=os.environ.get("UAPI_API_KEY"))

resp = client.search(
    query="Which Stripe Checkout field should I use to persist my own user ID?",
)

print(resp.data.answer_text)
for src in resp.data.sources:
    print(src.title, src.url)
```

### Node.js / TypeScript (SDK)

```typescript theme={null}
import uAPI from 'usdk-js';

const client = new uAPI({
  apiKey: process.env['UAPI_API_KEY'],
});

const { data } = await client.search({
  query: 'Which Stripe Checkout field should I use to persist my own user ID?',
});

console.log(data.answer_text);
console.log(data.sources);
```

### Raw HTTPS (cURL)

```bash theme={null}
curl -s "https://api.uapi.nl/v1/search?query=Which%20Stripe%20Checkout%20field%20should%20I%20use%20to%20persist%20my%20own%20user%20ID%3F" \
  -H "X-API-Key: ${UAPI_API_KEY}"
```

A typical `/v1/search` response includes:

* `data.answer_text`: concise, direct answer.
* `data.sources`: array of `{ url, title }` entries you can inspect or display.

## 6. Production-grade tweaks in 5 seconds

Use retries and timeouts from the SDKs instead of reinventing them.

### Python

```python theme={null}
from uapi import uAPI

client = uAPI(
    max_retries=2,     # default
    timeout=60.0,      # seconds
)

quote = client.extract(url="https://finance.yahoo.com/quote/NVDA/")
```

### Node.js

```typescript theme={null}
import uAPI from 'usdk-js';

const client = new uAPI({
  apiKey: process.env['UAPI_API_KEY'],
  maxRetries: 2,
  timeout: 60_000,
});

const quote = await client.extract({ url: 'https://finance.yahoo.com/quote/NVDA/' });
```

<Tip>
  If you need to call uAPI from a latency-sensitive API, offload extraction to a background job and rely on the stable `id` plus your own correlation keys.
</Tip>

## 7. Common mistakes and fast fixes

<AccordionGroup>
  <Accordion title="401: Missing or invalid API key">
    Ensure `X-API-Key` is set and matches a live key. In local development, echo `$UAPI_API_KEY` (or `$Env:UAPI_API_KEY` on Windows) to confirm. The envelope includes an `INVALID_API` style error code you can branch on.
  </Accordion>

  <Accordion title="Parameter not URL-encoded">
    Always URL-encode `url` and `query` values. If you see unexpected truncation or errors on certain URLs, verify encoding with your language’s standard library.
  </Accordion>

  <Accordion title="No structured data in data">
    If `success` is false with `NO_CONTENT`, the target may be unsupported, behind auth, or not reliably extractable. Try another URL or adjust your target.
  </Accordion>

  <Accordion title="Slow or flaky responses">
    Large or defensive sites can take longer. Keep a 60s timeout on first runs, use the SDK retry defaults, and move heavy calls off your hot request path.
  </Accordion>
</AccordionGroup>

## 8. Next steps

* Read the `/v1/extract`, `/v1/search`, and `/v1/perform` endpoint docs for exact parameters and examples.
* Review the Responses and Types pages to rely on field names and normalization guarantees.
* Use the Caching page to control `x-cache-ttl` (0–3600 seconds) for your own key-scoped cache.
* See the Pledge and Support pages to understand how we handle stability, fairness, and incident response.

<Check>
  If you have run one successful `/v1/extract` call and one `/v1/search` call with the SDKs or raw HTTP, you are ready to integrate uAPI into real workflows.
</Check>