SearchX Documentation — AI-Powered E-Commerce Search

Manage your SearchX applications programmatically through the REST API.

Overview

The Applications API allows you to retrieve application details, update configuration, and trigger product imports.

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

Try It Live

Open in Swagger UI → to test these endpoints interactively.

All endpoints require Bearer token authentication. See API Authentication for details.

Get Application

Retrieve detailed information about your application.

GET /api/v2/applications/{app_id}

Request

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"

Parameters

Parameter	Type	Location	Required	Description
`app_id`	string	path	Yes	Application unique identifier (10-character alphanumeric)

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "YOUR_APP_ID",
  "name": "My Store Search",
  "status": "active",
  "description": "Production store search",
  "website": "https://mystore.com",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-03-20T14:22:00Z",
  "showcase": {
    "enabled": false,
    "products": []
  },
  "top_searches": {
    "enabled": false,
    "terms": []
  },
  "suggested_links": {
    "enabled": false,
    "links": []
  },
  "organization": {
    "id": "985c92b8-7079-4ee4-af35-5729f0ff4392",
    "name": "Acme Corp"
  }
}

Status Values

active — Application is operational
inactive — Application is paused
suspended — Application is suspended (billing issue)

Errors

Status	Error Code	Description
401	4011	Missing API Key or Bearer Token
401	4012	Invalid API Key
403	4031	API key does not belong to this application
404	4041	Resource not found
429	—	Rate limit exceeded (120 req/min)

See API Errors for complete error reference.

Update Application

Update application configuration including name, feed URL, feed type, description, website, and suggested links.

PUT /api/v2/applications/{app_id}

Request

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

{
  "name": "Updated Store Name",
  "feed_url": "https://mystore.com/products.xml",
  "feed_type": "google",
  "description": "Production store search engine",
  "website": "https://mystore.com",
  "suggested_links_enabled": true,
  "suggested_links": [
    {
      "url": "https://mystore.com/collections/summer-sale",
      "title": {
        "en": "Summer Sale",
        "el": "Καλοκαιρινές προσφορές"
      }
    },
    {
      "url": "https://mystore.com/collections/new",
      "title": { "en": "New Arrivals" }
    }
  ]
}

All fields are optional. Only include fields you want to update.

cURL Example:

curl -X PUT "https://admin.searchxengine.ai/api/v2/applications/YOUR_APP_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Store Name",
    "feed_url": "https://mystore.com/products.xml",
    "feed_type": "google",
    "description": "Production store search engine",
    "website": "https://mystore.com",
    "suggested_links_enabled": true,
    "suggested_links": [
      {
        "url": "https://mystore.com/collections/summer-sale",
        "title": { "en": "Summer Sale", "el": "Καλοκαιρινές προσφορές" }
      },
      {
        "url": "https://mystore.com/collections/new",
        "title": { "en": "New Arrivals" }
      }
    ]
  }'

Parameters

Parameter	Type	Required	Default	Description
`name`	string	No	-	Application name (max 255 chars, must be unique within organization)
`feed_url`	string	No	-	XML product feed URL (max 2048 chars)
`feed_type`	string	No	-	Feed format: `google`, `facebook`, or `skroutz`
`description`	string	No	-	Application description (max 1000 chars)
`website`	string	No	-	Application website URL (max 2048 chars)
`showcase_enabled`	boolean	No	`false`	Enable/disable product showcase feature
`showcase`	array	No	`[]`	Featured products (max 4). Each item requires `product_id` (string)
`top_searches_enabled`	boolean	No	`false`	Enable/disable suggested search terms feature
`top_searches`	array	No	`[]`	Suggested search terms (max 5 strings)
`suggested_links_enabled`	boolean	No	`false`	Enable/disable suggested links feature
`suggested_links`	array	No	`[]`	Promotional links (max 4). Each link requires `url` (string starting with `https://`) and `title` (object keyed by locale, e.g. `{ "en": "Summer Sale", "el": "Καλοκαιρινές προσφορές" }`). `title.en` is required as the canonical fallback when a visitor's locale has no translation.

Response format

When retrieving application details via GET, suggested_links is returned as a nested object:

{
  "suggested_links": {
    "enabled": true,
    "links": [
      {
        "url": "https://mystore.com/collections/summer-sale",
        "title": {
          "en": "Summer Sale",
          "el": "Καλοκαιρινές προσφορές"
        }
      }
    ]
  }
}

When updating via PUT, use the flat array format shown in the request examples above (no enabled wrapper).

Example: Update Search UI Features

Configure showcase, top searches, and suggested links in a single request:

cURL Example:

curl -X PUT "https://admin.searchxengine.ai/api/v2/applications/YOUR_APP_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "showcase_enabled": true,
    "showcase": [
      {"product_id": "prod_123"},
      {"product_id": "prod_456"},
      {"product_id": "prod_789"},
      {"product_id": "prod_012"}
    ],
    "top_searches_enabled": true,
    "top_searches": [
      "outdoor furniture",
      "bedroom sets",
      "kids sunscreen"
    ],
    "suggested_links_enabled": true,
    "suggested_links": [
      {
        "url": "https://mystore.com/collections/summer-sale",
        "title": { "en": "Summer Sale", "el": "Καλοκαιρινές προσφορές" }
      },
      {
        "url": "https://mystore.com/collections/new",
        "title": { "en": "New Arrivals" }
      }
    ]
  }'

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "message": "Application updated successfully.",
  "application": {
    "id": "YOUR_APP_ID",
    "name": "Updated Store Name",
    "feed_url": "https://mystore.com/products.xml",
    "feed_type": "google",
    "description": "Production store search engine",
    "website": "https://mystore.com",
    "showcase": {
      "enabled": false,
      "products": []
    },
    "top_searches": {
      "enabled": false,
      "terms": []
    },
    "suggested_links": {
      "enabled": true,
      "links": [
        {
          "url": "https://mystore.com/collections/summer-sale",
          "title": {
            "en": "Summer Sale",
            "el": "Καλοκαιρινές προσφορές"
          }
        },
        {
          "url": "https://mystore.com/collections/new",
          "title": { "en": "New Arrivals" }
        }
      ]
    },
    "updated_at": "2024-03-27T15:30:00Z"
  }
}

Validation Errors

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "message": "The feed_url field must be a valid URL.",
  "errors": {
    "feed_url": ["The feed_url field must be a valid URL."]
  }
}

Common validation errors:

Invalid URL format for feed_url or website
Invalid feed_type (must be google, facebook, or skroutz)
Field length exceeds maximum
Duplicate name within the same organization
showcase array exceeds 4 items or references non-existent product_id
top_searches array exceeds 5 items or contains empty strings
suggested_links array exceeds 4 items
suggested_links URL does not start with https://
Missing required fields in suggested_links items (url and title.en are both required)

Import Products

Trigger an asynchronous product import from your configured feed.

POST /api/v2/applications/{app_id}/import

Prerequisites

Application must have a valid feed_url configured
Feed must be accessible and return valid XML

Request

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

{}

cURL Example:

curl -X POST "https://admin.searchxengine.ai/api/v2/applications/YOUR_APP_ID/import" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "message": "Product import started successfully.",
  "job_id": "550e8400-e29b-41d4-a716-446655440000"
}

The import runs asynchronously. Use the job_id to track progress (job status endpoint coming soon).

Errors

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "message": "Application does not have a feed URL configured."
}

This error occurs when:

feed_url is not set for the application
You need to set feed_url using the Update Application endpoint first

Rate Limiting

All endpoints are rate-limited to:

120 requests per minute per IP address
Applies across all API endpoints
Independent from older API rate limit

Rate Limit Response: 429 Too Many Requests

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
Retry-After: 60
Content-Type: application/json

{
  "message": "Rate limit exceeded. You can make 120 requests per minute. Please retry after 60 seconds."
}

Handling Rate Limits

Implement exponential backoff when you receive a 429 response:

async function apiRequest(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      const delay = Math.min(retryAfter * 1000 * Math.pow(2, i), 60000);
      await new Promise((resolve) => setTimeout(resolve, delay));
      continue;
    }

    return response;
  }
}

See API Errors for advanced rate limiting strategies.

Next Steps

Search API — Execute product searches
API Authentication — Learn about API key management
API Errors — Complete error code reference