Skip to main content

​
Prerequisites

  • API Key: Contact us to get your API key for authentication

​
Your First Query

​
Synchronous Query (Immediate Results)

Submit a query and get results back immediately: 
curl -X POST https://api.hypermodel.ai/api/v1/query \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Find 5 Series A fintech companies",
    "schema": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "domain": { "type": "string" },
          "description": { "type": "string" }
        }
      }
    },
    "async": false
  }'

{
  "success": true,
  "data": {
    "id": "query_1234567890_abc123",
    "raw": "...",
    "data": [
      {
        "name": "Example Fintech Co",
        "domain": "example.com",
        "description": "A fintech company"
      }
    ]
  }
}

​
Asynchronous Query (Background Processing)

Submit a query for background processing with delivery to a destination: 
curl -X POST https://api.hypermodel.ai/api/v1/query \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Find 10 Series A companies that sell to hospitality",
    "schema": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "domain": { "type": "string" },
          "industry": { "type": "string" }
        }
      }
    },
    "destination": {
      "type": "URL",
      "config": {
        "endpoint": "https://webhook.site/your-unique-id"
      }
    },
    "async": true
  }'

{
  "id": "query_1234567890_abc123",
  "status": "pending",
  "destination": {
    "type": "URL"
  },
  "createdAt": "2025-01-01T00:00:00Z",
  "updatedAt": "2025-01-01T00:00:00Z"
}

​
Check Query Status

curl -X GET https://api.hypermodel.ai/api/v1/query/query_1234567890_abc123 \
  -H "X-API-Key: your-api-key"

{
  "id": "query_1234567890_abc123",
  "status": "completed",
  "destination": {
    "type": "URL",
    "url": "https://webhook.site/your-unique-id"
  },
  "error": null,
  "createdAt": "2025-01-01T00:00:00Z",
  "updatedAt": "2025-01-01T00:01:00Z"
}

​
Understanding the Schema Parameter

The schema parameter is required and defines the structure of the response data. It must be a valid JSON Schema. 
{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "domain": { "type": "string" }
  }
}

​
Accuracy Modes

The API supports two accuracy modes:
Uses Hypermodel first, falls back to web search if needed
  • Faster processing
  • Lower cost
  • Good for well-indexed company data
Uses both Hypermodel and web search in parallel for maximum accuracy
  • More comprehensive results
  • Higher accuracy
  • Slower processing and higher cost
{
  "query": "Find top AI companies",
  "schema": { ... },
  "accuracyMode": "high"
}

​
Next Steps

API Reference

Complete API endpoint documentation

Destination Configurations

Learn about URL, Snowflake, Sheets, and Clay destinations
⌘I