Snyf API Reference

Welcome to the Snyf API. Upload your product catalog using the Upload API, and query it using natural language with the Search API.

Authentication

You can generate your API Key on your Dashboard (login required). Include this key in the header of every request.

x-api-key: sk-snyf-xxxxxxxxxxxxxxxxxxxx

POST

Upload Product

Asynchronous Processing: This endpoint initiates an asynchronous upload process. Your product will be processed, indexed, and available for search within approximately 5 minutes.

https://ag42w9a4xj.execute-api.us-east-1.amazonaws.com/prod

Body Parameters

Field	Type	Description
company_id	string	ReqThe company identifier used when registering your account.
product_id	string	ReqUnique product ID.
category	string	ReqProduct category (e.g. tshirt, dress, shorts).
title	string	ReqName of the product.
image_urls	array	ReqList of public image URLs.
description	string	OptDetailed product description.

curl -X POST https://ag42w9a4xj.execute-api.us-east-1.amazonaws.com/prod \
  -H "x-api-key: sk-snyf-*****************" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "registered-company-id",
    "product_id": "productid",
    "category": "apparel",
    "title": "blue shirt",
    "description": "button down blue shirt",
    "image_urls": ["image_url_1", "image_url_2"]
  }'

import requests
import json

API_URL = "https://ag42w9a4xj.execute-api.us-east-1.amazonaws.com/prod"
API_KEY = "sk-snyf-*****************"

payload = {
    "company_id": "registered-company-id",
    "product_id": "productid",
    "category": "apparel",
    "title": "blue shirt",
    "description" : "button down blue shirt",
    "image_urls": [
        "image_url_1", "image_url_2"
    ]
}

headers = {
    "Content-Type": "application/json",
    "x-api-key": API_KEY
}

try:
    print(f"Sending request to: {API_URL}...")
    
    response = requests.post(API_URL, json=payload, headers=headers)

    if response.status_code != 202:
        raise Exception(f"Status: {response.status_code}, Details: {response.text}")

    print(f"\n Request Succeeded: {response.status_code}")
    print(f"Response: {response.text}")

except Exception as e:
    print(f"\n FAILED: {e}")

const API_URL = "https://ag42w9a4xj.execute-api.us-east-1.amazonaws.com/prod";
const API_KEY = "sk-snyf-*****************";

const payload = {
    company_id: "registered-company-id",
    product_id: "productid",
    category: "apparel",
    title: "blue shirt",
    description: "button down blue shirt",
    image_urls: ["image_url_1", "image_url_2"]
};

async function uploadProduct() {
    try {
        console.log(`Sending request to: ${API_URL}...`);
        
        const response = await fetch(API_URL, {
            method: "POST",
            headers: {
                "Content-Type": "application/json",
                "x-api-key": API_KEY
            },
            body: JSON.stringify(payload)
        });

        const text = await response.text();

        if (response.status !== 202) {
            throw new Error(`Status: ${response.status}, Details: ${text}`);
        }

        console.log(`\n Request Succeeded: ${response.status}`);
        console.log(`Response: ${text}`);

    } catch (e) {
        console.log(`\n FAILED: ${e.message}`);
    }
}

uploadProduct();

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) {
        String apiUrl = "https://ag42w9a4xj.execute-api.us-east-1.amazonaws.com/prod";
        String apiKey = "sk-snyf-*****************";

        String json = "{"
            + "\"company_id\":\"registered-company-id\","
            + "\"product_id\":\"productid\","
            + "\"category\":\"apparel\","
            + "\"title\":\"blue shirt\","
            + "\"description\":\"button down blue shirt\","
            + "\"image_urls\":[\"image_url_1\",\"image_url_2\"]"
            + "}";

        try {
            System.out.println("Sending request to: " + apiUrl + "...");
            
            HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(apiUrl))
                .header("Content-Type", "application/json")
                .header("x-api-key", apiKey)
                .POST(HttpRequest.BodyPublishers.ofString(json))
                .build();

            HttpResponse response = HttpClient.newHttpClient()
                .send(request, HttpResponse.BodyHandlers.ofString());

            if (response.statusCode() != 202) {
                throw new RuntimeException("Status: " + response.statusCode() + ", Details: " + response.body());
            }

            System.out.println("\n Request Succeeded: " + response.statusCode());
            System.out.println("Response: " + response.body());

        } catch (Exception e) {
            System.out.println("\n FAILED: " + e.getMessage());
        }
    }
}

Response

202 Accepted This status code indicates that the request was sent successfully. The product will be processed and indexed in the background.

GET

Search Catalog

https://3o14x7mgq5.execute-api.us-east-1.amazonaws.com/prod/search

Query Parameters

Param	Type	Description
query	string	ReqSearch text (e.g., "red dress").
company_id	string	ReqMust match the company identifier used when registering.
page	int	OptPage number (Default: 1).
page_size	int	OptItems per page (Default: 8).

curl -G "https://3o14x7mgq5.execute-api.us-east-1.amazonaws.com/prod/search" \
  -d "query=red dress" \
  -d "company_id=registered-company-id" \
  -d "page=1" \
  -d "page_size=8" \
  -H "x-api-key: sk-snyf-*****************"

import requests

API_URL = "https://3o14x7mgq5.execute-api.us-east-1.amazonaws.com/prod/search"
API_KEY = "sk-snyf-*****************"
params = {
    "query": "red dress", 
    "company_id": "registered-company-id",
    "page": 1,
    "page_size": 8
}

headers = {"x-api-key": API_KEY}

try:
    print(f"Searching: {API_URL}...")
    response = requests.get(API_URL, params=params, headers=headers)

    if response.status_code != 200:
        raise Exception(f"Status: {response.status_code}, Details: {response.text}")

    print(f"\n Search Succeeded: {response.status_code}")
    print(f"Results: {response.json()}")

except Exception as e:
    print(f"\n FAILED: {e}")

const API_URL = "https://3o14x7mgq5.execute-api.us-east-1.amazonaws.com/prod/search";
const API_KEY = "sk-snyf-*****************";

async function searchProduct() {
    const url = new URL(API_URL);
    
    // Automatically adds parameters to URL (e.g. ?query=dress...)
    url.search = new URLSearchParams({ 
        query: "red dress", 
        company_id: "registered-company-id",
        page: "1",
        page_size: "8"
    });

    try {
        console.log(`Searching...`);
        const response = await fetch(url, { headers: { "x-api-key": API_KEY } });
        
        if (!response.ok) {
            const text = await response.text();
            throw new Error(`Status: ${response.status}, Details: ${text}`);
        }

        const data = await response.json();
        console.log(`\n Search Succeeded: ${response.status}`);
        console.log("Results:", data);

    } catch (e) {
        console.log(`\n FAILED: ${e.message}`);
    }
}

searchProduct();

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) {
        String baseUrl = "https://3o14x7mgq5.execute-api.us-east-1.amazonaws.com/prod/search";
        String query = "red%20dress"; // Manual encoding for Java string
        String companyId = "registered-company-id";
        String apiKey = "sk-snyf-*****************";

        // Manually constructing query params
        String fullUrl = baseUrl + "?query=" + query + "&company_id=" + companyId + "&page=1&page_size=8";

        try {
            System.out.println("Searching...");
            
            HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(fullUrl))
                .header("x-api-key", apiKey)
                .GET()
                .build();

            HttpResponse response = HttpClient.newHttpClient()
                .send(request, HttpResponse.BodyHandlers.ofString());

            if (response.statusCode() != 200) {
                throw new RuntimeException("Status: " + response.statusCode() + ", Details: " + response.body());
            }

            System.out.println("\n Search Succeeded: " + response.statusCode());
            System.out.println("Results: " + response.body());

        } catch (Exception e) {
            System.out.println("\n FAILED: " + e.getMessage());
        }
    }
}

Response Structure

Field	Type	Description
results	array	List of products matching the search query.
results[].productId	string	Unique identifier for the product.
results[].title	string	Product title.
results[].image_url	string	Presigned URL granting temporary access (1 hour) to the image.
results[].score	float	Relevance score (0.0 - 1.0). Higher is better.
totalItems	int	Total number of results found.

Example Response

{
  "results": [
    {
      "productId": "prod_123456",
      "title": "Red Floral Summer Dress",
      "image_url": "https://snyf-catalog-images.s3.amazonaws.com/images/...[SignedToken]...",
      "score": 0.85505205
    },
    {
      "productId": "prod_789012",
      "title": "Evening Gown",
      "image_url": "https://snyf-catalog-images.s3.amazonaws.com/images/...[SignedToken]...",
      "score": 0.85437917
    }
  ],
  "currentPage": 1,
  "totalPages": 5,
  "totalItems": 40
}

Need help?

snyf.ai.search@gmail.com