Skip to main content
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.

​
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/ and create an API key. Keep it in a secrets manager or password vault. Never embed it in frontend code or public repos.
All examples read your key from the UAPI_API_KEY environment variable. Set it once, use it everywhere.
  • Python
  • TypeScript / Node.js
pip install usdk
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)

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)

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)

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}"
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).

​
4. Understand the response envelope

This is a representative envelope for /v1/extract (values truncated):
(truncated)
{
  "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.
In production, log at least id, success, request.endpoint, request.status_code, and a compact summary of error when present.

​
5. Ask a sourced question with /v1/search

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

​
Python (SDK)

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)

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)

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

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

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/' });
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.

​
7. Common mistakes and fast fixes

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

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