API Reference

Base URL

https://api.hypermodel.ai/api/v1

Authentication

All endpoints require authentication via the X-API-Key header:

X-API-Key: your-api-key

Create Query

POST /api/v1/query

endpoint

Submit a new query for processing. Supports both synchronous and asynchronous modes.

Request

X-API-Key

string

required

Your API key for authentication

Content-Type

string

default:"application/json"

Content type header

Body Parameters

query

string

required

Natural language query describing the data you want

schema

object

required

JSON Schema defining the structure of the response data

destination

object

Required when async is true. Defines where to send results

Show Destination Properties

type

string

required

Destination type: URL, Snowflake, Sheets, or Clay

config

object

required

Destination-specific configuration

columns

array

Optional list of specific columns to include

async

boolean

default:"false"

If true, process asynchronously and send to destination

accuracyMode

string

default:"low"

Accuracy mode: low or high

Synchronous Mode Example

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 with CEO information",
    "schema": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "company_name": { "type": "string" },
          "domain": { "type": "string" },
          "ceo_name": { "type": "string" },
          "ceo_linkedin": { "type": "string" }
        }
      }
    },
    "async": false,
    "accuracyMode": "high"
  }'

{
  "success": true,
  "data": {
    "id": "query_1234567890_abc123",
    "raw": "Raw unformatted response from Claude...",
    "data": [
      {
        "company_name": "Example Fintech",
        "domain": "example.com",
        "ceo_name": "John Doe",
        "ceo_linkedin": "https://linkedin.com/in/johndoe"
      }
    ]
  }
}

Asynchronous Mode Example

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 the hospitality industry",
    "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",
        "headers": {
          "X-Custom-Header": "value"
        }
      }
    },
    "async": true
  }'

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

Error Responses

{
  "error": "Invalid request",
  "details": [
    {
      "code": "invalid_type",
      "path": ["schema"],
      "message": "Required"
    }
  ]
}

Get Query Status

GET /api/v1/query/:id

endpoint

Retrieve the status and results of a specific query (for async queries)

Request

X-API-Key

string

required

Your API key for authentication

string

required

The query ID returned from the create query endpoint

Response

string

The unique query identifier

status

string

Current status: pending, processing, completed, or failed

destination

object

Destination configuration for the query

error

string | null

Error message if status is failed, otherwise null

createdAt

string

ISO 8601 timestamp when query was created

updatedAt

string

ISO 8601 timestamp when query was last updated

{
  "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"
}

List Queries

GET /api/v1/queries

endpoint

List all queries with their current status

Request

X-API-Key

string

required

Your API key for authentication

Response

{
  "queries": [
    {
      "id": "query_1234567890_abc123",
      "status": "completed",
      "destination": {
        "type": "URL"
      },
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-01T00:01:00Z"
    },
    {
      "id": "query_0987654321_xyz789",
      "status": "processing",
      "destination": {
        "type": "Snowflake"
      },
      "createdAt": "2025-01-01T00:02:00Z",
      "updatedAt": "2025-01-01T00:02:30Z"
    }
  ],
  "total": 2
}

Queries are sorted by creation date (newest first)

Destination Configurations

URL Destination

Send data to any HTTP endpoint via POST request.

{
  "type": "URL",
  "config": {
    "endpoint": "https://webhook.site/unique-id",
    "headers": {
      "X-API-Key": "your-api-key",
      "X-Custom-Header": "custom-value"
    }
  }
}

Payload sent to endpoint:

{
  "id": "query_1234567890_abc123",
  "raw": "Raw response...",
  "data": [ /* Formatted data matching your schema */ ]
}

Snowflake Destination

Insert data into a Snowflake table.

{
  "type": "Snowflake",
  "config": {
    "account": "your-account",
    "database": "your-database",
    "schema": "your-schema",
    "table": "your-table",
    "warehouse": "your-warehouse",
    "username": "your-username",
    "password": "your-password"
  }
}

Google Sheets Destination

Append data to a Google Sheet.

{
  "type": "Sheets",
  "config": {
    "spreadsheetId": "your-spreadsheet-id",
    "sheetName": "Sheet1",
    "accessToken": "google-oauth-access-token"
  }
}

Clay Destination

Send data to a Clay table via webhook.

{
  "type": "Clay",
  "config": {
    "webhookUrl": "https://clay.com/webhook/your-webhook-url"
  }
}

Clay webhook expects flat data structures. Nested objects are automatically flattened with underscore-separated keys (e.g., address_city), and arrays are either joined as comma-separated strings (for primitives) or stringified as JSON (for objects).

PDF Extraction

POST /api/v1/pdf/extract

endpoint

Extract structured data from PDF documents using AI

This endpoint does not require authentication

Request

pdfUrl

string

required

URL of the PDF document to extract data from

schema

object

required

JSON Schema defining the structure of data to extract

prompt

string

Optional custom prompt to guide extraction

Example

curl -X POST https://api.hypermodel.ai/api/v1/pdf/extract \
  -H "Content-Type: application/json" \
  -d '{
    "pdfUrl": "https://example.com/document.pdf",
    "schema": {
      "type": "object",
      "properties": {
        "company_name": { "type": "string" },
        "revenue": { "type": "string" },
        "employees": { "type": "number" },
        "founded_year": { "type": "number" }
      }
    },
    "prompt": "Extract company financial information"
  }'

{
  "success": true,
  "data": {
    "company_name": "Example Corp",
    "revenue": "$10M",
    "employees": 50,
    "founded_year": 2020
  }
}

Accuracy Modes

Low Accuracy (Default)
High Accuracy

Uses Hypermodel search first, falls back to web search only if data is not found.Characteristics:

Faster processing
Lower cost
Good for well-indexed company data

{
  "accuracyMode": "low"
}

JSON Schema Examples

Simple Array of Companies

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "name": { "type": "string" },
      "domain": { "type": "string" },
      "description": { "type": "string" }
    }
  }
}

Companies with Contact Information

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "company_name": { "type": "string" },
      "domain": { "type": "string" },
      "ceo_name": { "type": "string" },
      "ceo_email": { "type": "string", "format": "email" },
      "ceo_linkedin": { "type": "string", "format": "uri" },
      "ceo_phone": { "type": "string" },
      "employees": { "type": "number" },
      "revenue": { "type": "string" }
    },
    "required": ["company_name", "domain"]
  }
}

Single Company Object

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "domain": { "type": "string" },
    "founded_year": { "type": "number" },
    "headquarters": { "type": "string" },
    "industry": { "type": "string" }
  }
}

Error Handling

All errors follow a consistent format:

{
  "error": "Error type",
  "message": "Human-readable error message",
  "details": [ /* Optional array of detailed error information */ ]
}

Common HTTP Status Codes

Code	Description
`200`	Synchronous query completed successfully
`202`	Async query accepted for processing
`400`	Invalid request parameters
`401`	Missing API key
`403`	Invalid API key
`404`	Query ID not found
`500`	Server-side error during processing

Getting Started

Guides

API Reference

Base URL

Authentication

Create Query

Request

Body Parameters

Synchronous Mode Example

Asynchronous Mode Example

Error Responses

Get Query Status

Request

Response

List Queries

Request

Response

Destination Configurations

URL Destination

Snowflake Destination

Google Sheets Destination

Clay Destination

PDF Extraction

Request

Example

Accuracy Modes

JSON Schema Examples

Error Handling

Common HTTP Status Codes

Getting Started

API Reference

Guides

​Base URL

​Authentication

​Create Query

​Request

​Body Parameters

​Synchronous Mode Example

​Asynchronous Mode Example

​Error Responses

​Get Query Status

​Request

​Response

​List Queries

​Request

​Response

​Destination Configurations

​URL Destination

​Snowflake Destination

​Google Sheets Destination

​Clay Destination

​PDF Extraction

​Request

​Example

​Accuracy Modes

​JSON Schema Examples

​Error Handling

​Common HTTP Status Codes

Base URL

Authentication

Create Query

Request

Body Parameters

Synchronous Mode Example

Asynchronous Mode Example

Error Responses

Get Query Status

Request

Response

List Queries

Request

Response

Destination Configurations

URL Destination

Snowflake Destination

Google Sheets Destination

Clay Destination

PDF Extraction

Request

Example

Accuracy Modes

JSON Schema Examples

Error Handling

Common HTTP Status Codes