Skip to main content

​
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. 
curl -i http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "password": "super-secret", "remember": true }'
The response looks like: 
{
  "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: 
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: 
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): 
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: 
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.