API Documentation

Everything you need to query structured datasets from your AI agent.

Quick Start

Step 1 — Get an API Key

Generate a free key. No account required.

POST /api/v1/keys

Step 2 — Query Data

Send filters, get structured JSON back instantly.

POST /api/v1/query

Authentication

All query endpoints require an API key. Pass it via header:

Request headers
X-API-Key: df_live_your_key_here

# Or use Authorization header:
Authorization: Bearer df_live_your_key_here

Keys have a df_ prefix. Each key has a daily rate limit (default: 1,000 queries/day). Generate one for free:

Generate API Key

curl -X POST https://datafuel.polsia.app/api/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "My Agent"}'

POST /api/v1/query

The core endpoint. Send filters, get structured company data back.

Request Body

Field	Type	Default	Description
`dataset`	string	`"companies"`	Dataset to query
`filter`	object	`{}`	Filter criteria (see below)
`fields`	string[]	all	Which fields to return
`sort`	object	`{"field":"name","direction":"asc"}`	Sort order
`limit`	integer	`25`	Results per page (max 100)
`offset`	integer	`0`	Pagination offset

Available Filters

Filter	Type	Example
`sector`	string \| string[]	`"saas"` or `["saas", "ai"]`
`sub_sector`	string	`"fintech"`
`revenue_min`	integer	`1000000`
`revenue_max`	integer	`5000000000`
`employees_min`	integer	`100`
`employees_max`	integer	`10000`
`country`	string \| string[]	`"United States"`
`city`	string	`"San Francisco"`
`funding_stage`	string \| string[]	`"series_b"`
`is_public`	boolean	`true`
`founded_after`	integer	`2020`
`founded_before`	integer	`2015`
`search`	string	`"payment"`
`tags`	string[]	`["ai", "llm"]`

Example: Find SaaS Companies with $100M+ Revenue

curl
curl -X POST https://datafuel.polsia.app/api/v1/query \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dataset": "companies",
    "filter": {
      "sector": "saas",
      "revenue_min": 100000000
    },
    "sort": {"field": "revenue_usd", "direction": "desc"},
    "limit": 10
  }'

Response

200 OK
{
  "dataset": "companies",
  "query": {
    "filters_applied": 2,
    "fields": ["name", "domain", "sector", ...],
    "sort": { "field": "revenue_usd", "direction": "desc" },
    "limit": 10,
    "offset": 0
  },
  "results": {
    "count": 8,
    "total": 8,
    "has_more": false,
    "data": [
      {
        "name": "Canva",
        "domain": "canva.com",
        "sector": "saas",
        "revenue_usd": 2300000000,
        "employee_count": 5000,
        ...
      }
    ]
  },
  "meta": {
    "response_ms": 12,
    "api_version": "v1"
  }
}

Example: Search AI Companies Founded After 2020

Python
import requests

response = requests.post(
    "https://datafuel.polsia.app/api/v1/query",
    headers={"X-API-Key": "YOUR_KEY"},
    json={
        "dataset": "companies",
        "filter": {
            "sector": "ai",
            "founded_after": 2020
        },
        "fields": ["name", "revenue_usd", "funding_total_usd"]
    }
)

companies = response.json()["results"]["data"]

GET /api/v1/datasets

List all available datasets with their schemas and record counts.

curl

curl https://datafuel.polsia.app/api/v1/datasets \
  -H "X-API-Key: YOUR_KEY"

GET /api/v1/datasets/:slug

Get detailed info about a specific dataset, including schema definition and sample records.

curl

curl https://datafuel.polsia.app/api/v1/datasets/companies \
  -H "X-API-Key: YOUR_KEY"

POST /api/v1/keys

Generate a new API key. No authentication required. Keys expire after 30 days.

curl

curl -X POST https://datafuel.polsia.app/api/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "My AI Agent"}'

Response

201 Created
{
  "api_key": "df_live_a1b2c3d4e5f6...",
  "prefix": "df_live_a1b2",
  "name": "My AI Agent",
  "rate_limit": 1000,
  "expires_in": "30 days",
  "warning": "Save this key now. It cannot be retrieved later."
}

Error Codes

Code	Error	Meaning
`401`	`missing_api_key`	No API key provided
`401`	`invalid_api_key`	Key not found or deactivated
`401`	`expired_api_key`	Key has expired
`404`	`dataset_not_found`	Requested dataset doesn't exist
`429`	`rate_limit_exceeded`	Daily query limit reached
`500`	`query_failed`	Internal server error

Rate Limits

Each API key has a daily query limit that resets at midnight UTC:

Free keys: 1,000 queries/day
Rate limit info is included in 429 responses
Counter increments per /api/v1/query call
Dataset listing and key generation don't count toward limits

Available Datasets

companies

Curated dataset of 50+ technology companies with revenue, funding, employee count, sector classification, and details. Updated quarterly.

Sectors: saas, ai, fintech, ecommerce, cybersecurity, healthtech, infrastructure, hr, climate, logistics, edtech, proptech, gaming, legaltech

Funding stages: seed, series_a through series_g, late, ipo, acquired