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

# Quickstart

> Make your first authenticated request against the Browsary API and provision a project-ready browser session.

## Prerequisites

* A deployed Browsary instance (local `npm run dev` works while you explore).
* SMTP, database, Redis, browser server, and OpenAI credentials configured as described in the `browser-ai` repository README.
* `curl` or an HTTP client of your choice.

> URLs below assume `http://localhost:3000`; swap in your production hostname when ready.

## 1. Create or sign in to an account

Use the registration or login endpoints to obtain a session cookie. The response always includes the JWT for native clients.

```bash theme={null}
curl -i http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "dev@example.com", "password": "super-secret", "remember": true }'
```

The response looks like:

```json theme={null}
{
  "status": "ok",
  "token": "eyJhbGciOiJIUzI1NiIs..."
}
```

Browsary sets an `HttpOnly` `token` cookie when `remember` is `true`. Keep either the cookie jar or `token` string for subsequent calls.

## 2. Issue an API key

API keys are safer for automation than long-lived session cookies. Create one scoped to your development projects:

```bash theme={null}
curl http://localhost:3000/api/api-keys \
  -X PUT \
  -H "Content-Type: application/json" \
  -H "Cookie: token=<SESSION_TOKEN>" \
  -d '{
    "name": "local-cli",
    "accessType": "projects",
    "projectIds": ["sandbox"]
  }'
```

The API returns a `secret` once—store it securely. Use either the `secret` or its `keyPrefix` with the `x-api-key` header:

```bash theme={null}
curl http://localhost:3000/api \
  -H "x-api-key: brw_live_123..."`
```

## 3. Create a project and bootstrap a browser session

Create a fresh project (requires an email-verified session or API key):

```bash theme={null}
curl http://localhost:3000/api/projects \
  -X PUT \
  -H "Content-Type: application/json" \
  -H "Cookie: token=<SESSION_TOKEN>" \
  -d '{
    "name": "Marketing Research",
    "description": "Agents that summarise competitor landing pages",
    "public": false,
    "slug": "marketing-research"
  }'
```

The response body contains the new project ID. Use that slug to hit project-scoped endpoints, such as creating a persistent browser session:

```bash theme={null}
curl http://localhost:3000/marketing-research/api/sessions \
  -X PUT \
  -H "Content-Type: application/json" \
  -H "x-api-key: brw_live_123..." \
  -d '{
    "name": "Chrome bot",
    "description": "Keeps a Chrome window up for scraping",
    "screen": { "width": 1440, "height": 900 },
    "args": "",
    "image": "google-chrome",
    "cookies": []
  }'
```

The call returns a session identifier you can later start via `POST /marketing-research/api/sessions/{sessionId}/start`.

## 4. Verify access

* `GET /api` → confirms the API version and echoes the authenticated subject.
* `GET /marketing-research/api` → returns project metadata when the slug is correct and you have permission.
* `GET /marketing-research/api/pipelines` → should return an empty array on a brand-new project, proving project scoping is set up correctly.

Once these checks succeed you can move on to the detailed reference sections for pipelines, functions, MCP servers, or billing—no extra setup is required.