Posts

We recently released a Search API for Find AI, and announced its integration with Clay.com.

APIs allow developers to interact with a product using code. There are many different ways to build an API, and many tools to make it easier for customers to adopt. In this post, I’ll take you behind the scenes of how we built the Find AI API, from its technical foundations to the tools we used to simplify developer adoption.

I'll start with the end customer experience, then work our way back to the internal architecture.

Explainer video

Here's a video I created to explain how to use the Find AI API:

I recorded the video using a DJI Pocket 3 with their lavalier mic and edited it in Descript. I recorded almost an hour of footage - so I spent a lot of time editing the video to be as short and clear as possible. Descript's text-based editing tool, originally designed for podcasts, made it easy to scan through retakes and figure out which was best.

Video tutorials help people understand the end-to-end integration process of an API before diving into detailed documentation. Every customer who has integrated with our API started by watching this video, so it was a good use of time.

Generated client libraries

In the video, calling the API looks straightforward because you can install a Find AI client library and call import FindAI from "find-ai" to make requests. Client libraries save developers time by abstracting away boilerplate code and reducing the need to read extensive documentation.

We provide official client libraries in Python, Node, Ruby, and Go, making integration accessible across multiple programming languages.

Companies like Stripe and OpenAI have set a high standard, making libraries a key part of their developer ecosystems. So, developers now expect client libraries in multiple languages whenever integrating with a new API. Writing and maintaining these libraries manually, however, would be both time-consuming and error-prone.

This is where Stainless comes in. Stainless reads our OpenAPI specification and automatically generates client libraries in multiple languages. The tool was created by Alex, who built similar systems at Stripe, and it now powers libraries for OpenAI, Anthropic, and Cloudflare.

For the Find AI API, every single user I’ve spoken to relies on one of our Stainless-generated client libraries. If you’re building an API, providing robust client libraries isn’t just a nice-to-have—it’s the new standard.

Interactive docs

Clear documentation is the foundation of a great developer experience. It helps users understand how to interact with your API and what data they can send or retrieve.

Initially, we used Swagger to generate our API documentation. Swagger reads an OpenAPI spec and creates interactive docs, allowing users to input their API key and test endpoints directly. This interactivity is a fantastic way for developers to use an API before writing any code. It’s also what I use in the explainer video. Our Swagger docs are still available at usefind.ai/api/docs.

However, Swagger had limitations. Its design felt dated, and it wasn’t easy to add additional text or media to guide users through setup or multi-step calls.

To address this, we switched to Mintlify for our primary documentation. Mintlify offers the same interactive features as Swagger but provides more flexibility for customization. For example, we embedded the explainer video and added step-by-step guides to explain each function in detail.

Mintlify’s docs are now our main resource, available at usefind.ai/docs. They’re clean, easy to navigate, and SEO-friendly, thanks to an installation via Cloudflare Workers.

OpenAPI at the core

When designing the Find AI API, we opted for a RESTful architecture. While newer paradigms like GraphQL and gRPC are gaining popularity, we chose REST because the ecosystem has largely standardized around OpenAPI for documenting APIs.

The OpenAPI specification serves as the backbone of our API ecosystem. It’s a machine-readable file that defines what the API can do. When we update the spec, tools like Stainless automatically regenerate client libraries in multiple languages, and our documentation on Mintlify and Swaggerupdates automatically.

This unified workflow ensures that our API is consistent and always up-to-date for developers.

Usage-based billing

One of the key architectural decisions we made was to adopt usage-based billing. We wanted our pricing model to reflect the value provided to users. For example, if a query requests 100 matches but only 50 exist, the user is billed for 50. This ensures fairness and aligns costs with usage.

To implement this model, we used Stripe’s usage-based billing. Setting up usage tracking and integrating with Stripe was surprisingly straightforward. Customers simply add a credit card to begin using the API, and Stripe charges their credit card weekly based on their usage.

This approach has worked well for our customers and ensures a seamless payment experience while scaling with their needs.

Demo mode

Another important decision was to include a demo environment in the API. Since using the full API requires adding a credit card, we wanted to provide a way for developers to experiment with the product risk-free.

To achieve this, we allow developers to issue a demo-mode API key. This key returns placeholder data (e.g., results like example.com) without incurring any costs. It’s particularly useful for mimicking the API’s functionality in development environments.

Looking at our analytics, however, demo mode hasn’t been widely used. Most developers were comfortable testing with the production API and seemed hesitant to rely on test-mode data. If I were to rebuild the API, I’d likely skip the demo mode entirely.

Try it out

If you want to incorporate search of people and companies into your application, check out the Find AI API.

Recent events have reminded me of a phrase I’ve long used in the startup world: “Having a TJ.”

Before Staffjoy became a company, it was just a side project. Our first user was TJ, whose biggest challenge was scheduling his workforce. Every week, TJ would meet with us to explain his problems. We’d show him what we were working on, and he’d provide invaluable feedback. TJ became the lifeblood of our startup—a real person with a real problem, collaborating with us to find a solution. Over time, “TJ” evolved into a metaphorical persona representing our customer base: “What would TJ want?”

Our minimum viable product at Staffjoy involved just emailing spreadsheets of schedules back and forth with TJ. Despite its simplicity—and perhaps clunkiness—he was happy to use it because we were addressing his core workforce management issues. TJ wasn’t distracted by unnecessary features; he cared about solving his problem.

With TJ’s help, we built an app, got into the Y Combinator Fellowship, raised a seed round, and helped more customers. TJ’s feedback and enthusiasm were instrumental in guiding Staffjoy from an idea into a venture we worked on for two years.

Many startups fail to secure even a single customer or create something that one person genuinely wants. Having a “TJ” keeps a company focused on solving real problems for real people. Individuals like TJ validate assumptions, offer honest feedback to prioritize work, answer spontaneous questions, and become references for future customers. They confirm that the company is tackling a genuine need. Once you’ve built something that satisfies TJ, you can seek out more customers like them.

In other companies I’ve been involved with, there’s always been that “TJ”—the first customer who has a problem, collaborates on the solution, and then champions your product. If you’re building a startup and don’t yet have a passionate user, I recommend focusing on finding that early adopter who can provide feedback. If you can’t find such a user, perhaps you’re addressing the wrong problem.

Later, as the industry shifted amid consolidations and shutdowns, TJ was laid off. Responding to the market dynamics, we pivoted, but we struggled to find another TJ and ultimately shut down. Losing a “TJ” can be a canary in the coal mine for a startup.

A passionate early customer keeps a startup team motivated and working on the right thing. Most startups focus on growth too early and fail to make something that a single customer wants. The TJ lesson is that a successful product starts with one customer, and that one customer’s love of the product is rooted in a problem they desperately want your help solving.

It's better to have 100 users love you than 1 million kinda like you. The true seed of scale is love, and you can't buy it, hack it, or game it. A product that is deeply loved is one that can scale. 
- Sam Altman

Earlier this year, I attended a talk in NYC by Vinay Hiremath, co-founder of Loom. He explained a mental model that's stuck with me.

Here’s the model: When a startup competes with an incumbent, it has an innovative product but seeks distribution. The incumbent has distribution—all its customers—but seeks innovation. So, they race: the startup tries to capture the incumbent’s customers before the incumbent can develop a better product.

Sometimes, the innovator wins, such as when Google surpassed Yahoo or the iPhone overtook BlackBerry.

Other times, the incumbent prevails. In the case of Slack vs. Microsoft Teams, Microsoft Teams now reports about ten times as many daily active users as Slack. Salesforce has also stood the test of time against many innovators.

Some ongoing races include Linear vs. Jira and ChatGPT vs. Google.

To win with innovation, small companies need to be hard to copy (like Figma), have strong network effects (like Facebook), or be ignored by incumbents (such as Lyft eschewing taxi laws).

Big tech companies should not be underestimated. They have become skilled at building products and often let startups do the hard work of validating new markets before they compete. They sometimes engage in tactics that are unethical and potentially illegal, such as cloning features to stifle emerging competitors—a strategy Instagram notoriously employed against Snapchat and later TikTok. These actions often go unchecked because if the incumbent dominates the market, the startup may not have the resources or time to pursue legal action.

I often think about this model because it applies well to many markets. As a startup, you should always ask, “Can somebody just copy this?” As an incumbent, you should ask, “Are we nimble enough to keep our product competitive?” Either way, the first step to winning a race is recognizing that you’re in one.

This week, I presented at the Mindstone AI meetup in NYC about internal tools we built at Find AI. We use OpenAI extensively to build a search engine for people and companies - making millions of daily LLM requests.

In this presentation, I covered two internal tools we built to improve our understanding and usage of OpenAI. The first is a semantic search engine we built on top of OpenAI Embeddings to understand the performance and accuracy of vector-based semantic search. The second is a qualitative model evaluation tool we built to compare the performance of different AI models for our use cases. These tools are internal research products that have never been shown publicly.

I recorded the presentation, which you can watch on Youtube.