← SearchX

API Reference

Applications API

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

ParameterTypeLocationRequiredDescription
app_idstringpathYesApplication 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",
  "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

StatusError CodeDescription
4014011Missing API Key or Bearer Token
4014012Invalid API Key
4034031API key does not belong to this application
4044041Resource 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, and website.

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"
}

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"
  }'

Parameters

ParameterTypeRequiredDefaultDescription
namestringNo-Application name (max 255 chars)
feed_urlstringNo-XML product feed URL (max 2048 chars)
feed_typestringNo-Feed format: google, facebook, or skroutz
descriptionstringNo-Application description (max 1000 chars)
websitestringNo-Application website URL (max 2048 chars)

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",
    "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

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

Previous
Authentication
Next
Search API