SearchX Documentation — AI-Powered E-Commerce Search

Learn how to authenticate with the SearchX API using Bearer tokens and app-scoped API keys.

Overview

The SearchX API uses Bearer token authentication with app-scoped API keys. Each API key is bound to a specific application and can only access that application's data.

Base URL: https://admin.searchxengine.ai/api/v2

Interactive API Documentation

Try the API live with our Swagger UI: Open Interactive API Docs →

Getting Your Credentials

Log in to the SearchX Dashboard
Navigate to Applications and select your application
Go to the API Keys section
Copy your Application ID (10-character alphanumeric)
Copy your API Key (starts with key_)

Keep Your API Key Secret

API keys have full access to their application's data. Never commit them to source control or expose them in client-side code. Use environment variables to store keys securely.

Authentication Methods

The SearchX API supports three authentication methods. You can authenticate using:

Bearer Token (Recommended) — Pass API key in Authorization header
Query Parameter — Pass API key as api_key query parameter
Request Body — Pass API key in request body (POST/PUT only)

Method 1: Bearer Token (Recommended)

GET /api/v2/applications/YOUR_APP_ID HTTP/1.1
Host: admin.searchxengine.ai
Authorization: Bearer YOUR_API_KEY

cURL Example:

curl -X GET "https://admin.searchxengine.ai/api/v2/applications/YOUR_APP_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Header Format:

Authorization: Bearer YOUR_API_KEY

Important:

Include the word Bearer followed by a space
Then your API key
Header name is Authorization (note the 'z' in American spelling)

Method 2: Query Parameter

Alternatively, pass the API key as a query parameter:

GET /api/v2/applications/YOUR_APP_ID?api_key=YOUR_API_KEY HTTP/1.1
Host: admin.searchxengine.ai

cURL Example:

curl -X GET "https://admin.searchxengine.ai/api/v2/applications/YOUR_APP_ID?api_key=YOUR_API_KEY"

When to Use Query Parameters

Query parameter authentication is useful for:

Quick testing in a browser
Tools that don't support custom headers
Webhooks or callbacks with limited configuration

For production applications, use the Bearer token method for better security practices.

Method 3: Request Body

For POST and PUT requests, you can include the API key in the request body:

POST /api/v2/applications/YOUR_APP_ID/search HTTP/1.1
Host: admin.searchxengine.ai
Content-Type: application/json

{
  "api_key": "YOUR_API_KEY",
  "q": "shoes",
  "limit": 20
}

cURL Example:

curl -X POST "https://admin.searchxengine.ai/api/v2/applications/YOUR_APP_ID/search" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "q": "shoes",
    "limit": 20
  }'

Update Application Example:

PUT /api/v2/applications/YOUR_APP_ID HTTP/1.1
Host: admin.searchxengine.ai
Content-Type: application/json

{
  "api_key": "YOUR_API_KEY",
  "name": "Updated Store Name",
  "feed_url": "https://mystore.com/products.xml"
}

Body Authentication Scope

Request body authentication only works for POST and PUT endpoints. GET requests must use either Bearer token or query parameter authentication.

App-Scoped Security

The API enforces app-scoped authentication for enhanced security:

✅ Allowed:  /api/v2/applications/a1b2c3d4e5/search
            with API key for a1b2c3d4e5

❌ Forbidden: /api/v2/applications/a1b2c3d4e5/search
             with API key for x9y8z7w6v5
             → 403 Forbidden

How It Works

API Key Creation: Each API key is bound to a specific application
Request Validation: Middleware validates {app_id} in URL matches the API key
Cross-App Protection: Cannot access other applications, even in same organization

Enhanced Security

This app-scoped model prevents accidental data leaks between applications and provides better audit trails. Each application's data is isolated even within the same organization.

Using API Keys

Server-Side (REST API)

Use the Authorization header for all requests:

const response = await fetch(
  'https://admin.searchxengine.ai/api/v2/applications/YOUR_APP_ID/search',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.SEARCHX_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ q: 'shoes', limit: 20 }),
  },
);

Client-Side (SDK)

For client-side integration, use the SDK via CDN:

<!-- Add to your HTML -->
<script src="https://sdk.searchxengine.ai/searchx-sdk.umd.js"></script>

<script>
  window.addEventListener('load', function () {
    if (window.SearchXSDK) {
      SearchXSDK.init({
        app_id: 'YOUR_APP_ID',
        api_key: 'YOUR_API_KEY',
        // ...
      });
    }
  });
</script>

See HTML Integration for complete setup guide.

Client-Side Keys

The API keys used in client-side SDK integrations are public keys designed for search operations only. They cannot be used to modify application settings or access the REST API's administrative endpoints. Never expose your REST API key in client-side code.

Common Authentication Errors

401 Unauthorized

Error: Missing or invalid API key

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "errorCode": 4011,
  "message": "Missing API Key or Bearer Token."
}

Solutions:

Check Authorization header is present
Verify Bearer prefix is included
Confirm API key is correct

403 Forbidden

Error: API key doesn't belong to application

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "errorCode": 4031,
  "message": "API key does not belong to this application."
}

Solutions:

Verify {app_id} in URL matches your API key
Check you're using the correct API key for this application
Confirm app_id is correct (check dashboard)

404 Not Found

Error: Application doesn't exist

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "errorCode": 4041,
  "message": "Resource not found."
}

Solutions:

Verify application ID is correct
Check application exists in dashboard
Ensure using production vs staging environment

See API Errors for complete error reference.