Similarix API Documentation

1. Text-based search

Search for assets using text queries.

Endpoint:

GET /api/search/

Parameters:

• query (required): The text query to search for

cURL example:

curl -X GET \
  -H "Authorization: Token your_token_here" \
  "https://similarix.com/api/search/?query=dog"

Python example:

import requests

url = "https://similarix.com/api/search/"
headers = {'Authorization': 'Token your_token_here'}
params = {'query': 'dog'}

response = requests.get(url, headers=headers, params=params)
print(response.json())

Response:

{
    "version": "1.0.2",
    "success": true,
    "info": {
        "files_count": 16,
        "search_type": "text",
        "query": "dog"
    },
    "result": {
        "files": [
            {
                "uuid": "dd09f404-1bd6-4246-a277-b5af21e9da66",
                "file_name": "richard-brutyo-Sg3XwuEpybU-unsplash.jpg",
                "file_size": 702316,
                "md5": "653b6e02f13241e943e0889f0165d627",
                "thumbnail": "https://similarix.com/media/8ff9ef69-fd22-4308-ad1e-22c59500d944/dd09f404-1bd6-4246-a277-b5af21e9da66.jpg",
                "s3_uri": "s3://similarix-test/images/richard-brutyo-Sg3XwuEpybU-unsplash.jpg",
                "download_url": "https://similarix.com/collections/download/dd09f404-1bd6-4246-a277-b5af21e9da66/",
                "distance": 0.79
            },
            // ... more results
        ]
    }
}

Response fields:

• files_count: Total number of files returned
• search_type: Type of search performed (text or image)
• query: The original search query
• uuid: Unique identifier for the file
• file_name: Name of the file
• file_size: Size of the file in bytes
• md5: MD5 hash of the file
• thumbnail: URL to the file's thumbnail
• s3_uri: S3 URI of the file
• download_url: URL to download the file
• distance: Similarity score (lower is more similar)

2. Image-based search

Search for similar assets by uploading an image.

Endpoint:

POST /api/search/

Parameters:

• file (required): The image file to search for similar assets

cURL example:

curl -X POST \
  -H "Authorization: Token your_token_here" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@path/to/your/image.jpg" \
  https://similarix.com/api/search/

Python example:

import requests

url = "https://similarix.com/api/search/"
headers = {'Authorization': 'Token your_token_here'}
files = {'file': open('path/to/your/image.jpg', 'rb')}

response = requests.post(url, headers=headers, files=files)
print(response.json())

Response:

{
    "version": "1.0.2",
    "success": true,
    "info": {
        "files_count": 16,
        "search_type": "image",
        "query": null
    },
    "result": {
        "files": [
            {
                "uuid": "7e5c20b6-c8a6-4fc0-9807-e7a81041b567",
                "file_name": "zoe-reeve-9hSejnboeTY-unsplash.jpg",
                "file_size": 1638695,
                "md5": "46f899a580163352cd361dd2aa7bcc37",
                "thumbnail": "https://similarix.com/media/8ff9ef69-fd22-4308-ad1e-22c59500d944/7e5c20b6-c8a6-4fc0-9807-e7a81041b567.jpg",
                "s3_uri": "s3://similarix-test/images/zoe-reeve-9hSejnboeTY-unsplash.jpg",
                "download_url": "https://similarix.com/collections/download/7e5c20b6-c8a6-4fc0-9807-e7a81041b567/",
                "distance": 0.0
            },
            // ... more results
        ]
    }
}

The response fields are the same as in the text-based search.

3. List collection

Retrieve a list of all collections associated with the authenticated user.

Endpoint:

GET /api/collections/

cURL example:

curl -H "Authorization: Token your_token_here" \
  https://similarix.com/api/collections/

Python example:

import requests

url = "https://similarix.com/api/collections/"
headers = {'Authorization': 'Token your_token_here'}

response = requests.get(url, headers=headers)
print(response.json())

Response:

{
    "version": "1.0.",
    "success": true,
    "info": {},
    "result": {
        "collections": [
            {
                "uuid": "8ff9ef69-fd22-4308-ad1e-22c59500d944",
                "name": "test",
                "bucket": "similarix-test",
                "folder": "/images",
                "type": "s3",
                "region": "eu-central-1",
                "sync_status": "completed",
                "last_sync": "2024-09-08T08:57:17.158088+03:00",
                "auto_sync_interval": "daily",
                "stats": {
                    "total_files": 16,
                    "total_size": 46988023
                }
            },
            // ... more collections
        ]
    }
}

Response fields:

• uuid: Unique identifier for the collection
• name: Name of the collection
• bucket: S3 bucket name
• folder: Folder path within the bucket
• type: Type of collection (e.g., "s3", "managed")
• region: AWS region of the S3 bucket
• sync_status: Current synchronization status
• last_sync: Timestamp of the last successful synchronization
• auto_sync_interval: Frequency of automatic synchronization
• stats: Statistics about the collection's contents

4. Get collection details

Retrieve details for a specific collection.

Endpoint:

GET /api/collections/{uuid}/

Parameters:

• uuid (required): The UUID of the collection

cURL example:

curl -H "Authorization: Token your_token_here" \
  https://similarix.com/api/collections/8ff9ef69-fd22-4308-ad1e-22c59500d944/

Python example:

import requests

url = "https://similarix.com/api/collections/8ff9ef69-fd22-4308-ad1e-22c59500d944/"
headers = {'Authorization': 'Token your_token_here'}

response = requests.get(url, headers=headers)
print(response.json())

Response:

{
    "version": "1.0.2",
    "success": true,
    "info": {},
    "result": {
        "collection": {
            "uuid": "8ff9ef69-fd22-4308-ad1e-22c59500d944",
            "name": "test",
            "bucket": "similarix-test",
            "folder": "/images",
            "type": "s3",
            "region": "eu-central-1",
            "sync_status": "completed",
            "last_sync": "2024-09-08T08:57:17.158088+03:00",
            "auto_sync_interval": "daily",
            "stats": {
                "total_files": 16,
                "total_size": 46988023
            }
        }
    }
}

The response fields are the same as in the List collections endpoint.

5. Trigger collection sync

Initiate a synchronization for a specific collection.

Endpoint:

POST /api/collections/{uuid}/sync/

Parameters:

• uuid (required): The UUID of the collection

cURL example:

curl -X POST \
  -H "Authorization: Token your_token_here" \
  https://similarix.com/api/collections/8ff9ef69-fd22-4308-ad1e-22c59500d944/sync/

Python example:

import requests

url = "https://similarix.com/api/collections/8ff9ef69-fd22-4308-ad1e-22c59500d944/sync/"
headers = {'Authorization': 'Token your_token_here'}

response = requests.post(url, headers=headers)
print(response.json())

Response:

{
    "version": "1.0.2",
    "success": true,
    "info": {},
    "result": {
        "message": "Sync triggered successfully for collection {uuid}."
    }
}

6. Check collection sync status

Check the synchronization status of a specific collection.

Endpoint:

GET /api/collections/{uuid}/sync-status/

Parameters:

• uuid (required): The UUID of the collection

cURL example:

curl -H "Authorization: Token your_token_here" \
  https://similarix.com/api/collections/8ff9ef69-fd22-4308-ad1e-22c59500d944/sync-status/

Python example:

import requests

url = "https://similarix.com/api/collections/8ff9ef69-fd22-4308-ad1e-22c59500d944/sync-status/"
headers = {'Authorization': 'Token your_token_here'}

response = requests.get(url, headers=headers)
print(response.json())

Response:

{
    "version": "1.0.2",
    "success": true,
    "info": {},
    "result": {
        "status": "completed",
        "last_sync": "2024-09-08T06:01:57.728561+00:00",
        "last_auto_sync": "2024-09-07T07:42:04.361672+00:00"
    }
}

Response fields:

• status: Current status of the sync (e.g., "completed", "in_progress")
• last_sync: Timestamp of the last manual sync
• last_auto_sync: Timestamp of the last automatic sync

7. Similarix Cloud (Managed Storage)

Similarix Cloud provides a managed storage solution where users can easily upload and manage their files without setting up their own S3 bucket.

Features:

• Managed by Similarix team for ease of use
• Automatic setup and configuration
• Secure and scalable storage
• Seamless integration with Similarix search capabilities

Usage:

To use Similarix Cloud, create a managed collection through the dashboard or API. You can then upload files directly to this collection.

Endpoint:

POST /api/collections/{uuid}/upload/

Parameters:

• uuid (required): The UUID of the managed collection
• file (required): The file to be uploaded (multipart/form-data)

cURL example:

curl -X POST \
  -H "Authorization: Token your_token_here" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@path/to/your/image.jpg" \
  https://similarix.com/api/collections/8ff9ef69-fd22-4308-ad1e-22c59500d944/upload/

Python example:

import requests
url = "https://similarix.com/api/collections/8ff9ef69-fd22-4308-ad1e-22c59500d944/upload/"
headers = {'Authorization': 'Token your_token_here'}
files = {'file': open('path/to/your/image.jpg', 'rb')}
response = requests.post(url, headers=headers, files=files)
print(response.json())

Response:

{
    "version": "1.0.2",
    "success": true,
    "info": {},
    "result": {
        "message": "Image uploaded successfully",
        "collection": "8ff9ef69-fd22-4308-ad1e-22c59500d944",
        "file": "example_image.jpg",
        "mime_type": "image/jpeg"
    }
}

Notes:

• The maximum file size for upload is 20 MB.
• Only image files are currently supported.
• Uploaded files are automatically processed and made available for search.
• The number of uploads is limited by your plan's allowance.

Auto-sync vs Manual sync vs Similarix Cloud

Similarix offers three ways to manage your collections: Auto-Sync, Manual Sync, and Similarix Cloud.

Similarix Cloud

Similarix Cloud is a managed storage solution that provides instant indexing and searching capabilities.

• Ease of Use: No need to set up or manage your own S3 bucket.
• Instant Processing: Files are processed and indexed immediately upon upload.
• Scalability: Automatically scales based on your storage needs.
• Integration: Seamlessly works with all Similarix features.
• Availability: Available on all paid plans, with storage limits based on the plan.

Key differences

Feature	Auto-sync	Manual sync	Similarix Cloud
Setup	Requires S3 configuration	Requires S3 configuration	No setup required
Sync Timing	Scheduled (daily, weekly, monthly)	On-demand	Instant (on upload)
User Intervention	Not required	Required	Minimal (only for uploads)
Best For	Regular updates, consistency	Immediate updates, after major changes	Quick start, ease of use, immediate indexing

Choose the method that best fits your workflow and data management needs. For optimal results, you can use a combination of these methods across different collections.

Error handling

When an error occurs, the API will return an appropriate HTTP status code along with a detailed error message. Here are some common status codes and their meanings:

• 200 OK: Successful GET, PUT, or DELETE request
• 201 Created: Successful POST request resulting in resource creation
• 202 Accepted: Request accepted for processing (e.g., sync triggered)
• 400 Bad Request: Invalid request parameters
• 403 Forbidden: Authentication failed or user lacks necessary permissions
• 404 Not Found: Requested resource not found
• 409 Conflict: Request conflicts with current state (e.g., sync already in progress)
• 500 Internal Server Error: Unexpected server error