In any growing application, data retrieval logic starts simple but rarely stays that way. A query to find a user by their email, check an order's status, or pull product inventory is written, then copied, then modified, then scattered across a dozen services and scripts. Before you know it, this critical business logic is a tangled mess—brittle, insecure, and a nightmare to maintain.
What if you could define that logic once and deploy it as a secure, scalable, and reusable API?
This is the core promise of Searches.do. We empower you to embrace Business-as-Code, turning complex data retrieval workflows into intelligent search agents. These agents act as standalone microservices, ready to be called from anywhere, by any application.
In this guide, we'll show you just how easy it is. In the next 10 minutes, you will build and deploy your very first search agent using the Searches.do TypeScript SDK.
Our goal is to create a search agent named find-customer-by-email. This agent will accept an email address as input and securely return the corresponding customer's data. By the end, you'll have a live API endpoint that you can call to perform this lookup, effectively creating a Data Retrieval API without the boilerplate.
To follow along, you'll need:
First, let's create a new project directory and initialize it with Node.js.
# Create and enter the new project directory
mkdir my-first-search-agent
cd my-first-search-agent
# Initialize a Node.js project
npm init -y
# Install the Searches.do SDK
npm install @searches.do/sdk
Next, create a directory to hold your agent definitions. This helps keep your project organized as you add more search agents.
mkdir searches
Your project structure should now look like this:
my-first-search-agent/
├── node_modules/
├── searches/
├── package.json
└── package-lock.json
Now for the fun part. Inside the searches directory, create a new file named find-customer-by-email.ts. This is where you'll define the agent's behavior.
Paste the following code into your new file:
// searches/find-customer-by-email.ts
import { defineSearchAgent } from '@searches.do/sdk';
// For this example, we'll use a simple in-memory array.
// In the real world, this could be a connection to a SQL database,
// a NoSQL document store, or another API.
const mockDatabase = [
{
customerId: 'cust_1A2b3C4d5E6f',
firstName: 'Jane',
lastName: 'Doe',
email: 'jane.doe@example.com',
accountStatus: 'active',
createdAt: '2023-10-26T10:00:00Z',
},
{
customerId: 'cust_9Z8y7X6w5V4u',
firstName: 'John',
lastName: 'Smith',
email: 'john.smith@example.com',
accountStatus: 'inactive',
createdAt: '2022-01-15T09:30:00Z',
},
];
// Define your search agent
export default defineSearchAgent({
// A unique, human-readable ID for your agent
searchId: 'find-customer-by-email',
// Define the input parameters your API will accept.
// The platform uses this for validation and generating documentation.
input: {
email: {
type: 'string',
required: true,
description: 'The email address of the customer to find.',
},
},
// The handler contains the core logic for your data retrieval.
// This is where you connect to your data sources.
async handler({ input }) {
console.log(`Searching for customer with email: ${input.email}`);
const customer = mockDatabase.find(
(c) => c.email.toLowerCase() === input.email.toLowerCase()
);
// If no customer is found, throw an error.
// The platform will automatically format this into a proper API error response.
if (!customer) {
throw new Error('Customer not found with the provided email.');
}
// The object returned here becomes the `result` in the API response.
return customer;
},
});
This simple file encapsulates everything needed for our agentic search:
With the logic defined, deploying it as a service is a single command away. Run the following in your terminal:
# (Assuming you have the searches-cli configured with your API key)
npx searches-cli deploy
The CLI will package your code, upload it to the Searches.do platform, and provision a secure API gateway for it. In seconds, you get a "Deployment successful" message. Your search agent is now live and ready to be used.
Your local TypeScript function is now a globally available, secure API as a Service. Let's test it using cURL.
curl -X POST https://api.searches.do/v1/search \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"searchId": "find-customer-by-email",
"parameters": {
"email": "jane.doe@example.com"
}
}'
You'll receive a standardized JSON response, just like the one you defined:
{
"status": "success",
"query": {
"searchId": "find-customer-by-email",
"parameters": {
"email": "jane.doe@example.com"
}
},
"result": {
"customerId": "cust_1A2b3C4d5E6f",
"firstName": "Jane",
"lastName": "Doe",
"email": "jane.doe@example.com",
"accountStatus": "active",
"createdAt": "2023-10-26T10:00:00Z"
},
"executionTimeMs": 78
}
Congratulations! You just went from a business requirement to a fully-functioning, secure, and scalable API in minutes. This is the power of headless search—the logic is completely decoupled and can be called from any frontend, mobile app, or backend service.
You've just scratched the surface. Imagine the possibilities:
By treating data retrieval as code, you create a more robust, maintainable, and secure architecture.
Ready to stop writing one-off data scripts and start building powerful, reusable services?
Sign up for Searches.do today and turn your queries into APIs.