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

# Quickstart

> Create a key and run your first search.

## 1. Create an API key

Sign in at [app.truscan.co](https://app.truscan.co), open **Settings → API keys**,
and create one. The secret is shown **once**, so store it immediately.

```bash theme={"dark"}
export TRUSCAN_API_KEY="tru_..."
```

<Warning>
  The full secret is returned only in the response that creates it. If you lose
  it, revoke the key and create another.
</Warning>

You can also create one over the API:

```bash theme={"dark"}
curl -X POST https://api.truscan.co/api/auth/keys \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "production"}'
```

## 2. Run a search

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl https://api.truscan.co/api/search/query \
    -H "Authorization: Bearer $TRUSCAN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "how does the TLS 1.3 handshake work",
      "tier": "instant",
      "limit": 10,
      "enrich": true
    }'
  ```

  ```python Python theme={"dark"}
  import os, requests

  r = requests.post(
      "https://api.truscan.co/api/search/query",
      headers={"Authorization": f"Bearer {os.environ['TRUSCAN_API_KEY']}"},
      json={"query": "how does the TLS 1.3 handshake work", "tier": "instant"},
      timeout=60,
  )
  r.raise_for_status()
  for hit in r.json()["result"]["results"]:
      print(hit["rank"], hit["score"], hit["url"])
  ```

  ```typescript TypeScript theme={"dark"}
  const res = await fetch("https://api.truscan.co/api/search/query", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.TRUSCAN_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      query: "how does the TLS 1.3 handshake work",
      tier: "instant",
    }),
  });

  const { result } = await res.json();
  for (const hit of result.results) {
    console.log(hit.rank, hit.score, hit.url);
  }
  ```
</CodeGroup>

## 3. Read the response

Every response is wrapped in the same envelope. The payload lives in `result`:

```json theme={"dark"}
{
  "success": true,
  "message": "ok",
  "result": {
    "id": "srch_...",
    "query": "how does the TLS 1.3 handshake work",
    "tier": "instant",
    "total": 10,
    "format": "json",
    "results": [
      {
        "rank": 1,
        "url": "https://www.cloudflare.com/learning/ssl/what-happens-in-a-tls-handshake/",
        "title": "What happens in a TLS handshake?",
        "snippet": "...",
        "domain": "cloudflare.com",
        "score": 0.91,
        "content": { "text": "...", "markdown": "...", "words": 1420 }
      }
    ],
    "stats": { "took_ms": 1180, "cached": false }
  }
}
```

## Fetch content without searching

If you already have URLs, skip the search and extract directly, up to **8 URLs**
per call:

```bash theme={"dark"}
curl https://api.truscan.co/api/search/contents \
  -H "Authorization: Bearer $TRUSCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://example.com/article"]}'
```

## Next steps

<CardGroup cols={2}>
  <Card title="Pick a tier" icon="layer-group" href="/search/tiers">
    `instant` is the default. `deep` and `deep_reasoning` widen recall.
  </Card>

  <Card title="Check your balance" icon="wallet" href="/billing/credits">
    Every account gets \$10.00 in free credits each month.
  </Card>
</CardGroup>