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

# Quickstart

> Start building with NeuronSearchLab in just a few minutes

## Set up your access

NeuronSearchLab is a hosted API service that provides real-time personalized recommendations through an API, SDK, and a web console. You do not need to deploy or install anything - just sign up and generate your API credentials.

<Steps>
  <Step title="Register or log in">
    Go to [console.neuronsearchlab.com/signup](https://console.neuronsearchlab.com/signup) or [login](https://console.neuronsearchlab.com/login) to create an account. You can invite teammates later from the **User Management** page in Settings.
  </Step>

  <Step title="Generate client credentials">
    Once logged in, open **SDK Credentials** in Settings and create a new client. Copy the **Client ID** and **Client Secret**. They are required to authenticate your backend services.

    <Warning>
      **Never expose the Client Secret in browser code or mobile apps.** Store it in your server-side environment variables or a secrets manager.
    </Warning>
  </Step>

  <Step title="Add your first dataset">
    Navigate to **Items** in the Explore section and use the upload flow to add a handful of representative items. Include metadata such as category, price, tags, and thumbnails to improve downstream recommendations.
  </Step>
</Steps>

***

## Authenticate securely

Create a backend route that exchanges your client credentials for an access token. The token scopes enforce what each service can do.

```bash theme={null}
curl -X POST https://auth.neuronsearchlab.com/oauth2/token \
  -H "Authorization: Basic <base64(client_id:client_secret)>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials"
```

<Steps>
  <Step title="Call the token endpoint">
    Call the auth token endpoint from a trusted server environment.
  </Step>

  <Step title="Cache the access token">
    Cache the resulting access token until it expires. Tokens default to 60 minutes.
  </Step>

  <Step title="Forward the token securely">
    Forward the token to your frontend or edge workers via secure headers.
  </Step>
</Steps>

<Tip>
  Rotate credentials regularly and prefer one client per application so you can revoke access without downtime.
</Tip>

***

## Make your first API call

With an access token you can request recommendations immediately. The following example retrieves homepage content for a known user using context ID `101`:

```bash theme={null}
curl -X GET "https://api.neuronsearchlab.com/v1/recommendations?user_id=user-123&context_id=101&limit=10" \
  -H "Authorization: Bearer <your_access_token>"
```

Send optional query parameters such as `limit`, `filter`, or `scope` to tailor the response. Responses include ranked items with associated metadata so you can render UI components quickly.

For query-driven product search, call the Core API search endpoint from the same backend boundary:

```bash theme={null}
curl -X POST "https://api.neuronsearchlab.com/v1/search" \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -d '{"query":"waterproof trail shoes","user_id":"user-123","context_id":"101","limit":"10"}'
```

If you prefer higher level abstractions, use one of the official SDKs from your backend:

* JavaScript/TypeScript: [`@neuronsearchlab/sdk` on npm](https://www.npmjs.com/package/@neuronsearchlab/sdk)
* PHP/Laravel: [`neuronsearchlab/sdk-php` on Packagist](https://packagist.org/packages/neuronsearchlab/sdk-php)
* Technical background: [recommendation systems reading path](https://www.neuronsearchlab.com/blog/recommendation-systems)
* Explore use cases: [recommendation experiences by industry](https://www.neuronsearchlab.com/use-cases)
* Platform overview: [features](https://www.neuronsearchlab.com/features)

***

## Explore the console

In addition to the API and SDK, you can manage your data and monitor performance through the [NeuronSearchLab Console](https://console.neuronsearchlab.com). Key areas include:

* **Dashboard** — Usage overview, credit tracking, and setup checklist.
* **Context** — Define contexts for each recommendation surface with retrieval settings and pre-query filters.
* **Rules Engine** — Create business rules to boost, bury, pin, filter, cap, diversify, dedupe, randomize, reorder, group, or topic-weight results.
* **Pipeline Config** — Control the multi-stage recommendation pipeline.
* **Explainability** — Debug why a specific item was recommended to a specific user.
* **Analytics** — Track recommendation volume, engagement events, and performance over time.
* **Items & Users** — Browse your catalog and user embeddings.
* **A/B Testing** — Split traffic between strategies and measure impact.
* **NeuronSearchLab AI** — Conversational assistant for managing recommendations through natural language.

### Recommended training workflow

When you are ready to train your first recommendation version:

<Steps>
  <Step title="Define event signals">
    Define event signals and save a template in **Events**.
  </Step>

  <Step title="Start a training run">
    Start a training run from that template.
  </Step>

  <Step title="Review the trained version">
    Review the resulting trained version in **Models**.
  </Step>

  <Step title="Add team context">
    Add an optional label and description for your team.
  </Step>

  <Step title="Approve the version">
    Approve the trained version when it is ready.
  </Step>

  <Step title="Promote to serving">
    Promote it to a serving target when you are ready to make it live.
  </Step>
</Steps>

This keeps training inputs, version review, and live rollout decisions clearly separated.

***

## Extend your integration

NeuronSearchLab supports rich documentation and examples to help you integrate quickly and effectively.

<CardGroup>
  <Card title="PHP SDK" icon="code" href="/sdk/php">
    Install the official PHP SDK with Composer for Laravel or any PHP service.
  </Card>

  <Card title="JavaScript SDK" icon="js" href="/sdk/introduction">
    Use the official npm package from Node.js or TypeScript services.
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Serve Recommendations" icon="sparkles" href="/guides/how-to-serve-recommendations">
    Ship real-time personalized recommendations with context-aware request patterns.
  </Card>

  <Card title="Connect Catalog + Events" icon="database" href="/guides/how-to-connect-catalog-and-events">
    Keep item metadata and engagement signals flowing for recommendation quality.
  </Card>

  <Card title="Launch New Contexts" icon="compass" href="/guides/how-to-launch-a-new-context">
    Roll out a new recommendation surface with measurable business outcomes.
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Track Events" icon="activity" href="/api-reference/endpoint/submit-events">
    Log impressions, clicks, and conversions to power near real-time learning.
  </Card>

  <Card title="Submit Items" icon="database" href="/api-reference/endpoint/submit-items">
    Send product or content metadata to build and refresh your catalog.
  </Card>

  <Card title="Get Recommendations" icon="sparkles" href="/api-reference/endpoint/get-recommendations">
    Retrieve personalized results that respect context filters and ranking rules.
  </Card>

  <Card title="Search" icon="magnifying-glass" href="/generate-search-results">
    Run query-driven retrieval through the Core API search endpoint.
  </Card>
</CardGroup>