Quissly

Search Documents

## Base URL

`https://api.quissly.com/v1/gepha`

## Search Endpoint

`GET /search`

### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | `str` | Yes | The search term or keyword to query from the catalog. The query cannot be empty, and its maximum length is 300 characters. |
| `user_id` | `str` | Yes | The ID of the user requesting the search. This enhances personalization. If not authenticated, this can be a guest ID. Note: The `user_id` does not need to match internal identifiers as long as consistent mapping is maintained for the service. |

### Authentication

All API endpoints require authentication using Bearer tokens. Include the token in the Authorization header of your requests.

### Example cURL Request with Authorization Header

``` bash
curl -X GET "https://api.quissly.com/v1/gepha/search?query=hand cream&user_id=123" -H "Authorization: Bearer YOUR_BEARER_TOKEN"

 ```

### Response Format

- **200 OK**:  
    Returns a JSON array of search results. Each result includes the `product_id` and `score` (between 0 and 1). The results are sorted by similarity score, with the first item being the best match for the given query.
    

Example:

``` json
[
  {
    "product_id": 12345,
    "score": 0.821
  },
  {
    "product_id": 678,
    "score": 0.818
  }
]

 ```

- **200 OK with No Results**:  
    If no matches are found, an empty array is returned.
    

Example:

``` json
[]

 ```

### Common Errors

- **401 Unauthorized**: If the authentication token is missing, invalid, or expired, the response will be:
    

``` json
{
  "detail": "Not authenticated"
}

 ```

- **422 Unprocessable Entity**: If required parameters are missing, the response will detail the missing fields. For example, missing the `query` parameter:
    

``` json
{
  "detail": [
    {
      "type": "missing",
      "loc": ["query", "query"],
      "msg": "Field required",
      "input": null
    }
  ]
}

 ```

- **404 Not Found**: If the endpoint is incorrect or unavailable, the response will be:
    

``` json
{
  "detail": "Not Found"
}

 ```

## Catalog Sync Options

### Option 1: External API Integration

Provide your catalog API endpoint and credentials. We will periodically fetch updates from your API and sync the catalog. The update frequency is subject to agreement with the customer for each contract.

### Option 2: Direct API Updates

Use our API endpoints to manage your catalog directly. The following methods are available:

### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `product_id` | `str` | Yes | A unique identifier for the product. |
| `SKU` | `str` | Yes | The stock-keeping unit for the product. |
| `product_name` | `str` | Yes | The name of the product. |
| `price` | `float` | Yes | The price of the product. |
| `category` | `str` | Yes | The category to which the product belongs. |
| `images` | `array` | Yes | A list of image references. Supports public URLs, private URLs, Base64, or cloud storage paths. |
| `description` | `str` | Yes | A brief description of the product. |
| `metadata` | `object` | No | Additional optional metadata such as `manufacturing_country`, `side_effects`, `date_of_issue`, or `other_category_hierarchy`. |

### Endpoints:

- Add a New Product:
    
    ``` http
      POST /add
    
     ```
    
- Add New Products (Batch):
    
    ``` http
      POST /add_batch
    
     ```
    
- Delete a Product:
    
    ``` http
      DELETE /delete
    
     ```
    
- Delete Products (Batch):
    
    ``` http
      DELETE /delete_batch
    
     ```
    
- Update Product Metadata:
    
    ``` http
      PUT /update
    
     ```
    

#### Schema for Update Metadata:

``` json
{
  "product_id": "string",
  "metadata": {
    "key1": "value1",
    "key2": "value2"
  }
}

 ```

## Token Management

Tokens must be manually refreshed. Ensure proper storage and renewal to avoid authentication errors.

General API Information

Services

QSearch

events

QChat

Quick

Catalog Management

Operations

Status Check

Add Products

Update Products

Delete Products

Quissly Chat Middleware

documents

Upload Document

Get Document

Update Document

Delete Document

Get Download Url

Get Project Documents

Browse Storage

Rename Document

Replace Document File

Update Document Permissions

Delete Folder

This module handles the upload, retrieval, modification, and deletion of documents within the system storage. [cite: 1]

Documents API Specification [cite: 1]

Documents

Retrieves a paginated list of all accessible documents. [cite: 14] (No specific path or body parameters required based on current rules). [cite: 15]

6. Get Documents [cite: 14]

Returns a hierarchical view of documents and folders in the storage directory. [cite: 16] (No specific path or body parameters required based on current rules). [cite: 17]

7. Browse Storage [cite: 16]

Removes an entire folder and its contents from the storage hierarchy. [cite: 28]

12. Delete Folder [cite: 28]

Searches for documents based on query strings or content matches. [cite: 18]

8. Search Documents [cite: 18]

Uploads a new document to the system using either a base64 encoded string or a JSON object. [cite: 4]

1. Upload Document [cite: 4]

{external_id}

New Section

New tab 1

Default

Quissly v1 beta

Production

All Environments

Sandbox

<div class="slate-div"><p class="slate-p " >This API Documentation covers two main functionalities: </p><ol class="slate-ol " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">QSearch request</strong>​ - for retrieving products based on user query in production.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">QChat request</strong>​ - for retrieving products or getting an AI response based on user message in production.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Catalog management</strong>​ - for adding, updating, or deleting items to the catalog. The ​<code class="slate-code">add</code>​ method can also be used for initial catalog creation. </div></li></ol><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Supports batch operations </strong>​for efficient data management.</div></li></ul><div class="slate-hr"><hr contenteditable="false" class="slate-HrElement-hr"/></div><h1 class="slate-h1 " >Authorization &amp; Security</h1><p class="slate-p " >For enhanced security, all API requests must include ​<strong class="slate-bold">two mandatory authentication components</strong>​:</p><ol class="slate-ol " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Bearer Token</strong>​ – Sent in the ​<code class="slate-code">Authorization</code>​ header.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Encrypted Signature</strong>​ – Sent in the ​<code class="slate-code">X-Signature</code>​ header.</div></li></ol><h2 class="slate-h2 " >How the Signature Works</h2><ol class="slate-ol " ><li class="slate-li " ><div style="position:relative">The client ​<strong class="slate-bold">generates an RSA key pair (2048-bit) at the start of the service</strong>​ (can be redone anytime while the service is active with proper notice)</div></li><li class="slate-li " ><div style="position:relative">The client ​<strong class="slate-bold">signs the query and current timestamp (ISO 8601 format with timezone)</strong>​ separated by “.” using its ​<strong class="slate-bold">private key</strong>​.</div></li><li class="slate-li " ><div style="position:relative">The encrypted signature is sent in the ​<code class="slate-code">X-Signature</code>​ header.</div></li><li class="slate-li " ><div style="position:relative">The server performs the following validations:</div></li><li class="slate-li " ><div style="position:relative">Quissly uses the same timestamp shared in the body to ​<strong class="slate-bold">Validate the timestamp</strong>​:</div><ol class="slate-ol " ><li class="slate-li " ><div style="position:relative">Ensures the timestamp is in ​<strong class="slate-bold">ISO 8601 format</strong>​.</div></li><li class="slate-li " ><div style="position:relative">Checks if the timestamp is ​<strong class="slate-bold">within &lt;1 minute</strong>​ of the server time.</div></li></ol></li><li class="slate-li " ><div style="position:relative">Quissly uses the client&apos;s ​<strong class="slate-bold">public key</strong>​ (previously shared with Quissly) to ​<strong class="slate-bold">Verify the signature</strong>​ to prevent tampering.</div></li></ol><p class="slate-p " >If any of these validations fail, the request is ​<strong class="slate-bold">rejected</strong>​.</p><h2 class="slate-h2 " ><strong class="slate-bold">E</strong>​ncryption Standards</h2><div class="published-table"><div class="table-container" style="padding-left: 0px;"><div class="published-table-header" style="width:100%;min-width:100%;"><div >Parameter</div><div >Requirement</div></div><table class="slate-table" style="min-width:100%;"><colgroup ><col style="width:initial"><col style="width:initial"></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">Encryption Algorithm</strong></p></td><td class="slate-td"><p class="slate-p " >RSA</p></td></tr><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">Key Size</strong></p></td><td class="slate-td"><p class="slate-p " >2048-bit</p></td></tr><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">Signature Hashing Algorithm</strong></p></td><td class="slate-td"><p class="slate-p " >SHA-256</p></td></tr><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">Timestamp Format</strong></p></td><td class="slate-td"><p class="slate-p " >ISO 8601 with timezone (​<code class="slate-code">YYYY-MM-DDTHH:MM:SS±HH:MM</code>​)</p></td></tr><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">Allowed Time Drift</strong></p></td><td class="slate-td"><p class="slate-p " >&lt;1 minute</p></td></tr><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">Public Key Storage</strong></p></td><td class="slate-td"><p class="slate-p " >Must be shared with Quissly in advance</p></td></tr></tbody></table></div></div><h2 class="slate-h2 " >Error Handling</h2><p class="slate-p " >If the security protocol is ​<strong class="slate-bold">not followed</strong>​, the server will respond with:</p><div class="published-table"><div class="table-container" style="padding-left: 0px;"><div class="published-table-header" style="width:100%;min-width:100%;"><div >Error Code</div><div >Description</div></div><table class="slate-table" style="min-width:100%;"><colgroup ><col style="width:initial"><col style="width:initial"></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " ><code class="slate-code">400 Bad Request</code></p></td><td class="slate-td"><p class="slate-p " >Timestamp missing or expired.</p></td></tr><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " ><code class="slate-code">401 Unauthorized</code></p></td><td class="slate-td"><p class="slate-p " >Invalid or missing Bearer Token and/or Signature.</p></td></tr><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " ><code class="slate-code">402 Payment Required</code></p></td><td class="slate-td"><p class="slate-p " >The service payment is past due.</p></td></tr><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " ><code class="slate-code">403 Forbidden</code></p></td><td class="slate-td"><p class="slate-p " >API KEY is valid, but signature verification failed for the account or a specific service is not available for the account.</p></td></tr></tbody></table></div></div><p class="slate-p " >This security mechanism ​<strong class="slate-bold">ensures:</strong></p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">✅ Protection against ​<strong class="slate-bold">unauthorized access</strong></div></li><li class="slate-li " ><div style="position:relative">✅ Prevention of ​<strong class="slate-bold">request tampering</strong></div></li><li class="slate-li " ><div style="position:relative">✅ Mitigation of ​<strong class="slate-bold">replay attacks</strong></div></li></ul><p class="slate-p " ><h2 class="slate-h2 " >Token Management</h2><p class="slate-p " >Tokens must be manually refreshed. Ensure proper storage and renewal to avoid authentication errors.</p></p><p class="slate-p " ></p></div><p class="slate-p " ></p>

<p class="slate-p " >Search products based on user queries. Queries are matched with the catalog and returned in a list format listed from most relevant to least relevant. </p><p class="slate-p " ><span style="background-color:#FE0000;">v1beta version is no longer supported for QSearch. Check v2 version</span></p>

Search products based on user queries. Queries are matched with the catalog and returned in a list format listed from most relevant to least relevant. 

v1beta version is no longer supported for QSearch. Check v2 version

User input into the search box. Max 150 characters.

query

ID for the user, which doesn't have to match the internal user id on client side, but should be mappable.

user_id

timestamp

page_number

page_size

default=0, which is quissly's relevance score. Can be any other value other by which the response results should be scored per agreement during integration

sort_by

default=2. ENUM(1, 2). 1 for Ascending, 2 for Descending.

sort_type

filters

parameters needed for any custom logic that needs to be applied on the output.

custom

channel

device

operation system from which request was sent

IPv4Address or IPv6Address address of the end user's browser or app. Not the IP of the server calling this API

ip_address

Authorization

Encrypted '{query}.{timestamp}'. The query and timestamp in the ISO 8601 Format, should be separated by "." (ex. "2025-01-09 08:44:14.318804+00:00.slim fit jeans with white spots") and signed by the private key.

X-Signature

one of the environments that is set up and activated for your account

X-Environment

integer value of current timestamp in milliseconds

X-Timestamp

X-Nonce

num_total_results

200 OK:
Returns a JSON with total number of matches found and documents array of search results for the given page*. Each result includes the product identifier (id) and score (between 0 and 1). The results are sorted by similarity score, with the first item being the best match for the given query. If no matches are found for a given page, an array will be empty.

*pagination is optional, and client can configure the service so that at each request the full set of matches are returned.

status

Your account will have a limit on the number of items that can be included in the single operation request associated to your account.

details

detail

401 Unauthorized.  Multiple possible messages

402 PAYMENT REQUIRED. Will occur if the payment for the account is due.

404 Not Found: If the endpoint is incorrect or unavailable.

422 Unprocessable Entity: 
If required parameters are missing, the response will detail the missing fields. For example, missing the query parameter.

API KEY is valid, but signature verification failed for the account or specific service is not available for the account.

<p class="slate-p " >Search products based on user queries. Queries are matched with the catalog and returned in a list format listed from most relevant to least relevant.</p><p class="slate-p " ></p>

Search products based on user queries. Queries are matched with the catalog and returned in a list format listed from most relevant to least relevant.

message

ID for the session, which doesn't have to match the internal session id on client side, but should be mappable. Needed to keep track of the conversation throughout the sessions.

session_id

The language in which the conversation should commence. Default = "Georgian"

detected_language

audio

images

'TEXT' or 'AUDIO' is provided. It is defaulted on 'TEXT'.

response_modality

Optional. channel from which request is sent

Encrypted '{message}.{timestamp}'. The query and timestamp in the ISO 8601 Format, should be separated by "." (ex. "2025-01-09 08:44:14.318804+00:00.slim fit jeans with white spots") and signed by the private key.

ENUM to indicate the type of streaming output received, one of ['text', 'docs', 'orders', 'step'].

type

content

200 OK:
Returns a stream of responses (events) in JSON format that includes the `type` of response and the `content` of the response.
`text` events may appear multiple times for a single API request. All other types of events will appear at most once for each API request.
`docs` and `orders` event types have structured objects in the `content` field of the response, while all the other event types have single strings as the value for the field `content`.



<p class="slate-p " >Get quick suggestions from Quissly to get fuzzy matches without additional cost, these requests will not count towards monthly quotas and will not incur additional charges.</p><p class="slate-p " >Please, be advised that abuse of the service is prohibited and the service is free of charge as a token of appreciation towards our customers in all plans, but we expect honest usage in return as well.</p>

Get quick suggestions from Quissly to get fuzzy matches without additional cost, these requests will not count towards monthly quotas and will not incur additional charges.

Please, be advised that abuse of the service is prohibited and the service is free of charge as a token of appreciation towards our customers in all plans, but we expect honest usage in return as well.

200 OK:
Returns a JSON array of length N, where N is defined at the service setup by agreement with the customer. The individual items in the array correspond to the quick matches found based on the user query. Each item includes `id`, `score`, and optionally, `metadata` which is also defined during the service setup.

<p class="slate-p " >The sync frequency and method is subject to agreement with the customer.</p><h3 class="slate-h3 " >Catalog Management API Endpoint Provided by Quissly</h3><p class="slate-p " >
This is our preferred way to manage catalog, and it gives you full control over your catalog. The following catalog operations are available:</p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">POST : add products </div></li><li class="slate-li " ><div style="position:relative">PUT : update products</div></li><li class="slate-li " ><div style="position:relative">DELETE : delete products</div></li><li class="slate-li " ><div style="position:relative">GET : status check
</div></li></ul><p class="slate-p " >Our system will handle all the requests, and you can always check the status of the request with GET /status method.</p><h3 class="slate-h3 " >Pricing</h3><p class="slate-p " >
Operations for Add and Update for the first 20000 items are free each month for the Basic plan, after which the cost is $0.015/item.</p><div style="width:100%;
	min-width:100%;" class="callout-widget" data-type=info ><div class="callout-icon"><svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10.0628 14.1676C10.2434 14.1676 10.3927 14.1086 10.5107 13.9905C10.6288 13.8725 10.6878 13.7232 10.6878 13.5426V9.77177C10.6878 9.6051 10.6253 9.46274 10.5003 9.34469C10.3753 9.22663 10.2295 9.1676 10.0628 9.1676C9.88227 9.1676 9.73296 9.22663 9.61491 9.34469C9.49685 9.46274 9.43783 9.61205 9.43783 9.7926V13.5634C9.43783 13.7301 9.50033 13.8725 9.62533 13.9905C9.75033 14.1086 9.89616 14.1676 10.0628 14.1676ZM10.0003 7.62594C10.1948 7.62594 10.358 7.56344 10.4899 7.43844C10.6219 7.31344 10.6878 7.15371 10.6878 6.95927C10.6878 6.76482 10.6219 6.59816 10.4899 6.45927C10.358 6.32038 10.1948 6.25094 10.0003 6.25094C9.80588 6.25094 9.64269 6.32038 9.51074 6.45927C9.3788 6.59816 9.31283 6.76482 9.31283 6.95927C9.31283 7.15371 9.3788 7.31344 9.51074 7.43844C9.64269 7.56344 9.80588 7.62594 10.0003 7.62594ZM10.0003 18.3343C8.81977 18.3343 7.72255 18.1225 6.70866 17.6989C5.69477 17.2752 4.81283 16.6884 4.06283 15.9384C3.31283 15.1884 2.72602 14.3065 2.30241 13.2926C1.8788 12.2787 1.66699 11.1815 1.66699 10.0009C1.66699 8.83427 1.8788 7.74399 2.30241 6.7301C2.72602 5.71621 3.31283 4.83427 4.06283 4.08427C4.81283 3.33427 5.69477 2.74399 6.70866 2.31344C7.72255 1.88288 8.81977 1.6676 10.0003 1.6676C11.167 1.6676 12.2573 1.88288 13.2712 2.31344C14.285 2.74399 15.167 3.33427 15.917 4.08427C16.667 4.83427 17.2573 5.71621 17.6878 6.7301C18.1184 7.74399 18.3337 8.83427 18.3337 10.0009C18.3337 11.1815 18.1184 12.2787 17.6878 13.2926C17.2573 14.3065 16.667 15.1884 15.917 15.9384C15.167 16.6884 14.285 17.2752 13.2712 17.6989C12.2573 18.1225 11.167 18.3343 10.0003 18.3343ZM10.0003 17.0843C11.9448 17.0843 13.6114 16.3898 15.0003 15.0009C16.3892 13.612 17.0837 11.9454 17.0837 10.0009C17.0837 8.05649 16.3892 6.38982 15.0003 5.00094C13.6114 3.61205 11.9448 2.9176 10.0003 2.9176C8.05588 2.9176 6.38921 3.61205 5.00033 5.00094C3.61144 6.38982 2.91699 8.05649 2.91699 10.0009C2.91699 11.9454 3.61144 13.612 5.00033 15.0009C6.38921 16.3898 8.05588 17.0843 10.0003 17.0843Z" fill="#3960B4"></path></svg></div><div ><p class="slate-p " ><strong class="slate-bold">Exception</strong>: for <code class="slate-code">Update</code> operation, only text description and image updates are considered, changes in the metadata are not counted.</p></div></div><p class="slate-p " >Delete Operation is free for all authorized accounts.</p><p class="slate-p " >To avoid server abuse, there are further restrictions on the operations:</p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">A maximum of 1000 items can be requested to be added or updated as part of an individual operation request.</div></li><li class="slate-li " ><div style="position:relative">No more than 20 operations can be active at any given point in time.
</div></li></ul><h3 class="slate-h3 " >Processing Time</h3><p class="slate-p " >
It takes ~ 1hr / 50,000 items to be processed for Add and Update operations.</p><p class="slate-p " >Alternative Approach: Catalog Sync API Endpoint Provided by Client</p><div style="width:100%;
	min-width:100%;" class="callout-widget" data-type=info ><div class="callout-icon"><svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10.0628 14.1676C10.2434 14.1676 10.3927 14.1086 10.5107 13.9905C10.6288 13.8725 10.6878 13.7232 10.6878 13.5426V9.77177C10.6878 9.6051 10.6253 9.46274 10.5003 9.34469C10.3753 9.22663 10.2295 9.1676 10.0628 9.1676C9.88227 9.1676 9.73296 9.22663 9.61491 9.34469C9.49685 9.46274 9.43783 9.61205 9.43783 9.7926V13.5634C9.43783 13.7301 9.50033 13.8725 9.62533 13.9905C9.75033 14.1086 9.89616 14.1676 10.0628 14.1676ZM10.0003 7.62594C10.1948 7.62594 10.358 7.56344 10.4899 7.43844C10.6219 7.31344 10.6878 7.15371 10.6878 6.95927C10.6878 6.76482 10.6219 6.59816 10.4899 6.45927C10.358 6.32038 10.1948 6.25094 10.0003 6.25094C9.80588 6.25094 9.64269 6.32038 9.51074 6.45927C9.3788 6.59816 9.31283 6.76482 9.31283 6.95927C9.31283 7.15371 9.3788 7.31344 9.51074 7.43844C9.64269 7.56344 9.80588 7.62594 10.0003 7.62594ZM10.0003 18.3343C8.81977 18.3343 7.72255 18.1225 6.70866 17.6989C5.69477 17.2752 4.81283 16.6884 4.06283 15.9384C3.31283 15.1884 2.72602 14.3065 2.30241 13.2926C1.8788 12.2787 1.66699 11.1815 1.66699 10.0009C1.66699 8.83427 1.8788 7.74399 2.30241 6.7301C2.72602 5.71621 3.31283 4.83427 4.06283 4.08427C4.81283 3.33427 5.69477 2.74399 6.70866 2.31344C7.72255 1.88288 8.81977 1.6676 10.0003 1.6676C11.167 1.6676 12.2573 1.88288 13.2712 2.31344C14.285 2.74399 15.167 3.33427 15.917 4.08427C16.667 4.83427 17.2573 5.71621 17.6878 6.7301C18.1184 7.74399 18.3337 8.83427 18.3337 10.0009C18.3337 11.1815 18.1184 12.2787 17.6878 13.2926C17.2573 14.3065 16.667 15.1884 15.917 15.9384C15.167 16.6884 14.285 17.2752 13.2712 17.6989C12.2573 18.1225 11.167 18.3343 10.0003 18.3343ZM10.0003 17.0843C11.9448 17.0843 13.6114 16.3898 15.0003 15.0009C16.3892 13.612 17.0837 11.9454 17.0837 10.0009C17.0837 8.05649 16.3892 6.38982 15.0003 5.00094C13.6114 3.61205 11.9448 2.9176 10.0003 2.9176C8.05588 2.9176 6.38921 3.61205 5.00033 5.00094C3.61144 6.38982 2.91699 8.05649 2.91699 10.0009C2.91699 11.9454 3.61144 13.612 5.00033 15.0009C6.38921 16.3898 8.05588 17.0843 10.0003 17.0843Z" fill="#3960B4"></path></svg></div><div ><p class="slate-p " ><strong class="slate-bold">This approach is not recommended</strong> and requires a custom agreement between you and Quissly.</p></div></div><p class="slate-p " >Provide your catalog API endpoint and credentials. We will periodically fetch updates from your API and sync the catalog.</p><p class="slate-p " ></p><p class="slate-p " ></p>

The sync frequency and method is subject to agreement with the customer.

Catalog Management API Endpoint Provided by Quissly


This is our preferred way to manage catalog, and it gives you full control over your catalog. The following catalog operations are available:

Our system will handle all the requests, and you can always check the status of the request with GET /status method.


Operations for Add and Update for the first 20000 items are free each month for the Basic plan, after which the cost is $0.015/item.

Delete Operation is free for all authorized accounts.

To avoid server abuse, there are further restrictions on the operations:


It takes ~ 1hr / 50,000 items to be processed for Add and Update operations.

Alternative Approach: Catalog Sync API Endpoint Provided by Client

Provide your catalog API endpoint and credentials. We will periodically fetch updates from your API and sync the catalog.

<p class="slate-p " >Add new items to the search catalog. Input format should be the list of dictionaries.</p>

Add new items to the search catalog. Input format should be the list of dictionaries.

Encrypted '{operation_id}.{timestamp}'. The operation_id and timestamp in the ISO 8601 Format, should be separated by "." (ex. "0a576d93-a0cc-4b43-bea1-3fdf537fc5ca.2025-01-09 08:44:14.318804+00:00") and signed by the private key.

operation_id

The status of the operation: "Completed" or "Pending"

Type of the operation requested: "Add", "Update", or "Delete"

The time in ISO 8601 format at which the operation was created

created_at

The time in ISO 8601 format at which the operation was compelted.

finished_at

The HTTP 202 Accepted successful response status code indicates that an operation request has been accepted for processing, but processing has not been completed or may not have started. The actual processing of the request is not guaranteed; the operation may still partially or fully fail when a server tries to process it, at which point the response to similar request will be 207 and details can be viewed in the `details`.

`summary` will only be in the response if the X-Signature was properly provided in the Header as part of the request.

summary

`data` will only be in the response if the X-Signature was properly provided in the Header as part of the request.

data

If the request of the status check is successful, but the part of or full operation failed, you will receive Response 207 with details.

Provided api key, signature, or both are incorrect.

422 Unprocessable Entity: 
The operation_id provided doesn't exist

service

Encrypted '{first_product_id}.{timestamp}'. The first product id and timestamp in the ISO 8601 Format, should be separated by "." (ex. "1a2b3c4d.2025-01-09 08:44:14.318804+00:00") and signed by the private key.

operation_id is the operation request identifier that can be used to check the status of the operation. If lost, you'd have to contact us to check the status.

Product upload request received successfully.

422 Unprocessable Entity: 
If required parameters are missing, the response will detail the missing fields. For example, missing the timestamp parameter.

reason

<p class="slate-p " >Update existing products. At least one field other than sku should be provided.</p>

Update existing products. At least one field other than sku should be provided.

Product update request received successfully.

<p class="slate-p " >Delete redundant products.</p><p class="slate-p " ></p>

Product deletion request received successfully.

Successful operation

The relative path of the folder to delete. [cite: 29]

folder_path

The unique external identifier for the document. [cite: 5]

external_id

An optional external URL associated with the document. [cite: 6]

Sections