POST v1/Search

POST

https://api.subworkflow.ai/v1/search

Perform context similarity searches over datasets within a workspace

Summary

• Your search query should be contextual rather than full-text. eg. phrasing your query as a question gives the best results.
• You can also search using an image by providing an image url or base64 image string.
• If you do not specify one or more datasets, the search will include all datasets in the workspace.
• The results are dataset items which match your query - we do not provide an LLM to generate an "answer" as with other RAG services.
• Paginate through the list using the offet and limit query parameters.

Parameters

name	type	location	required	description
query	string or object	body	required	Your search query. Can be either a simple string or text and image. Images can be a url or base64 string.
datasetIds	string[]	body	optional	The datasets to scope the search to. If not specified, all datasets are included.
limit	number	body	optional	Limits the number of results. Results are sorted by highest relevancy score and this limit always includes the highest scoring results.

Text only

Query with text only

{
    "query": "What policies are required by the request-for-proposal?"
}

Text and image

Query with text and image url

{
    "query": {
        "text": "Can you find this symbol in the document?",
        "image_url": "https://www.food.gov.uk/sites/default/files/styles/promo_large/public/media/image/food-hygiene-Rating%205_a_preview.jpeg"
    }
}

Query with text and image base64

{
    "query": {
        "text": "Can you find this symbol in the document?",
        "image_url": "data:image/jpeg;base64,..."
    }
}

Query with image only (url or base64)

{
    "query": {
        "image_url": "https://www.food.gov.uk/sites/default/files/styles/promo_large/public/media/image/food-hygiene-Rating%205_a_preview.jpeg"
    }
}

Response

Success

{
    "type": "object",
    "properties": {
        "success": { "type": "boolean" },
        "total": { "type": "number" },
        "data": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string"
                    },
                    "col": {
                        "type": "number"
                    },
                    "row": {
                        "type": "string"
                    },
                    "createdAt": {
                        "type": "number"
                    },
                    "score": {
                        "type": "number"
                    },
                    "share": {
                        "type": "object",
                        "propeties": {
                            "url": { "type": "string" },
                            "token": { "type": "string" },
                            "expiresAt": { "type": "number", "nullable": true }
                        }
                    }
                }
            }
        }
    }
}

400 Error

{
    "success": { "type": "boolean" },
    "error": { "type": "string" }
}

404 Error

{
    "success": { "type": "boolean" },
    "error": { "type": "string" }
}

Example

Curl

curl -X POST 'https://api.subworkflow.ai/v1/search' \
    --header 'x-api-key: <YOUR-API-KEY>'
    --data '{
        "query": {
            "text": "Can you find this symbol in the document?",
            "image_url": "https://www.food.gov.uk/sites/default/files/styles/promo_large/public/media/image/food-hygiene-Rating%205_a_preview.jpeg"
        },
        "datasetIds": ["ds_ar7e4PtGX7fGGnSt"],
        "limit": 5
    }'

JS/TS

const req = await fetch("https://api.subworkflow.ai/v1/search", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "x-api-key": "<YOUR-API-KEY>"
    },
    body: JSON.stringify({
        "query": {
            "text": "Can you find this symbol in the document?",
            "image_url": "https://www.food.gov.uk/sites/default/files/styles/promo_large/public/media/image/food-hygiene-Rating%205_a_preview.jpeg"
        },
        "datasetIds": ["ds_ar7e4PtGX7fGGnSt"],
        "limit": 5
    })
});

{
    "sort": ["-createdAt"],
    "offset": 0,
    "limit": 10,
    "total": 6,
    "data": [
        {
            "id": "dsx_1J5Iq9Ra2OqJQwCZ",
            "col": 5,
            "row": "pdf",
            "createdAt": 1761933154885,
            "score": 0.22778621,
            "share": {
                "url": "https://api.subworkflow.ai/v1/share/dsx_1J5Iq9Ra2OqJQwCZ?token=Tue9PO",
                "token": "Tue9PO",
                "expiresAt": 1762013710312
            }
        },
        // ... shortened for brevity
    ]
}