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

# Quickstart

> List products, create a session, read proxy.full_url, report telemetry, check health, and clean up.

# Quickstart

This guide walks through the minimum NexaLayer flow:

```text theme={null}
API Key -> products -> create session -> proxy.full_url -> report result -> read health -> terminate session
```

## 1. Request an API key by email

```bash theme={null}
BASE_URL="https://api.nexalayer.net/v1"

curl -X POST "$BASE_URL/account/request-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@example.com"
  }'
```

The response does not include the API key. NexaLayer sends it to the mailbox. The first claim for an email address receives \$1 trial credit:

```json theme={null}
{
  "data": {
    "status": "email_sent",
    "claim_status": "granted",
    "trial_balance": 1,
    "backend_ready": true,
    "message": "If the email address is valid, the API key has been sent."
  }
}
```

If the same email requests again, NexaLayer resends the existing API key and does not grant trial credit again. Trial credit is enough for a small dynamic session; production use can top up with USDT, with a \$10 minimum.

```bash theme={null}
export NEXALAYER_API_KEY="ak_xxx"
```

## 2. List products

```bash theme={null}
curl "$BASE_URL/products?type=dynamic" \
  -H "X-API-Key: $NEXALAYER_API_KEY"
```

Use the returned `product_no` when creating a session. Dynamic products work well for short-lived and rotation-friendly automation. Static products are better for stable identity, account login, and fixed-region tasks.

## 3. Create a dynamic session

```bash theme={null}
PRODUCT_NO="dynamic_ipweb"

curl -X POST "$BASE_URL/sessions" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NEXALAYER_API_KEY" \
  -H "Idempotency-Key: create-dynamic-001" \
  -d "{
    \"session_type\": \"dynamic\",
    \"product_no\": \"$PRODUCT_NO\",
    \"quantity\": 0.25,
    \"protocol\": \"socks5\",
    \"rotation_mode\": \"on_demand\"
  }"
```

Dynamic sessions are billed at $4 / GB, so `quantity=0.25` reserves $1. Static sessions start at \$10 / month. Session lifecycle management is free for now.

Session creation is asynchronous. A successful accepted response usually starts with `status=creating`.

## 4. Poll until active

```bash theme={null}
SID="sess_xxx"

curl "$BASE_URL/sessions/$SID" \
  -H "X-API-Key: $NEXALAYER_API_KEY"
```

When the session becomes `active`, the response includes proxy details:

```json theme={null}
{
  "data": {
    "session_id": "sess_xxx",
    "status": "active",
    "proxy": {
      "host": "proxy.example.net",
      "port": 6666,
      "username": "user",
      "password": "pass",
      "protocol": "socks5",
      "full_url": "<redacted-proxy-url>"
    }
  }
}
```

`proxy.full_url` can be used by tools that accept proxy URLs. Playwright usually needs `server`, `username`, and `password` separately.

## 5. Report execution telemetry

```bash theme={null}
curl -X POST "$BASE_URL/sessions/$SID/report-event" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NEXALAYER_API_KEY" \
  -d '{
    "event_type": "success",
    "status_code": 200,
    "target_host": "example.com",
    "latency_ms": 1200
  }'
```

Telemetry affects health score and rotation recommendations.

## 6. Read health

```bash theme={null}
curl "$BASE_URL/sessions/$SID/health" \
  -H "X-API-Key: $NEXALAYER_API_KEY"
```

Example:

```json theme={null}
{
  "data": {
    "health_score": 100,
    "risk_level": "low",
    "success_rate": 1,
    "consecutive_failures": 0,
    "recommendation": "ok"
  }
}
```

## 7. Terminate the session

```bash theme={null}
curl -X DELETE "$BASE_URL/sessions/$SID" \
  -H "X-API-Key: $NEXALAYER_API_KEY"
```

Automation scripts should clean up sessions in a `finally` block or shutdown hook.