Skip to main content
POST
/
v1
/
builder
Universe Builder
curl --request POST \
  --url https://api.chicago.global/v1/builder \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "Find me top 50 electric vehicle companies in Asia"
}
'
{
  "job_id": "e2035316-0042-437a-9353-4b224f304d5a",
  "status": "pending",
  "query": "Top 20 electric vehicle companies in Asia",
  "check_url": "/v1/jobs/e2035316-0042-437a-9353-4b224f304d5a",
  "estimated_duration_seconds": 30,
  "message": "Building stock universe for 'Top 20 electric vehicle companies in Asia'."
}
Build a thematic stock universe from a natural language query. An AI agent interprets your query, searches ~65,000 company descriptions, and returns relevant stocks ranked by relevance score.

​
How It Works

This endpoint uses async job processing:
  1. Submit Request: POST with a natural language query
  2. Receive Job ID: Get a job ID and polling URL immediately
  3. Poll for Status: Check /v1/jobs/{job_id} until status is completed
  4. Get Results: The completed job contains a ranked list of matching companies
Typically takes 15-40 seconds. The agent may run multiple search iterations to refine results.

​
Request Body

FieldTypeRequiredDescription
querystringYesNatural language query describing the investment theme and any filters (2-500 characters)
{
  "query": "Find me top 50 electric vehicle companies in Asia"
}

​
Response (202 Accepted)

{
  "job_id": "e2035316-0042-437a-9353-4b224f304d5a",
  "status": "pending",
  "query": "Top 20 electric vehicle companies in Asia",
  "check_url": "/v1/jobs/e2035316-0042-437a-9353-4b224f304d5a",
  "estimated_duration_seconds": 30,
  "message": "Building stock universe for 'Top 20 electric vehicle companies in Asia'."
}

​
Completed Response

When the job completes, GET /v1/jobs/{job_id} returns the matched companies: 
{
  "job_id": "e2035316-0042-437a-9353-4b224f304d5a",
  "status": "completed",
  "result": {
    "total_matches": 546,
    "results_returned": 20,
    "category_breakdown": {
      "core": 18,
      "peripheral": 2
    },
    "companies": [
      {
        "ric": "3677.HK",
        "name": "Jiangsu Zenergy Battery Technologies Group Co Ltd",
        "sector": "Industrials",
        "market": "China",
        "exchange": "Hong Kong",
        "activity": "Active",
        "market_cap": 12624996781.5,
        "category": "core",
        "composite_score": 249.43
      },
      {
        "ric": "005380.KS",
        "name": "Hyundai Motor Co",
        "sector": "Consumer Cyclicals",
        "market": "South Korea",
        "exchange": "Korea",
        "activity": "Active",
        "market_cap": 91219584753000.0,
        "category": "core",
        "composite_score": 141.13
      },
      {
        "ric": "0175.HK",
        "name": "Geely Automobile Holdings Ltd",
        "sector": "Consumer Cyclicals",
        "market": "Hong Kong",
        "exchange": "Hong Kong",
        "activity": "Active",
        "market_cap": 225892816535.3,
        "category": "core",
        "composite_score": 108.08
      }
    ]
  }
}

​
Company Fields

FieldDescription
ricReuters Instrument Code (unique stock identifier)
nameCompany name
sectorBusiness sector classification
marketCountry/market where the company is listed
exchangeStock exchange name
activityCompany status (e.g., Active)
market_capMarket capitalization (in local currency)
categoryMatch category: core (strongest match), peripheral, or satellite
composite_scoreRelevance score — higher means stronger thematic match

​
Query Tips

The agent works best with specific, descriptive queries:
Good QueriesWhy
”Top 50 electric vehicle battery manufacturers in Asia”Specific theme + region + count
”Gene therapy and CRISPR companies with market cap over $1B”Specific technology + size filter
”Semiconductor lithography and chip fabrication equipment”Narrow technical theme
Weak QueriesWhy
”Technology stocks”Too broad — thousands of matches
”Good companies”No investable theme
”Stocks”Not actionable

​
Supported Regions

When your query mentions a geography, the agent can filter by:
  • Regions: Europe, Asia, Americas, Middle East, Oceania
  • Countries: United States, United Kingdom, Japan, South Korea, China, Hong Kong, Taiwan, Singapore, India, Germany, France, Canada, Brazil, Australia, Saudi Arabia, UAE, Thailand, Malaysia, Indonesia, and 20+ more

​
Example

curl -X POST "https://api.chicago.global/v1/builder" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Top 30 AI infrastructure and data center companies"}'

const response = await fetch('https://api.chicago.global/v1/builder', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'Top 30 AI infrastructure and data center companies'
  })
});

const { job_id, check_url } = await response.json();

// Poll for results
const interval = setInterval(async () => {
  const status = await fetch(
    `https://api.chicago.global${check_url}`,
    { headers: { 'Authorization': `Bearer ${API_KEY}` } }
  ).then(r => r.json());

  if (status.status === 'completed') {
    clearInterval(interval);
    const { companies, total_matches } = status.result;
    console.log(`Found ${total_matches} matches, returned ${companies.length}`);
    companies.forEach(c => {
      console.log(`${c.name} (${c.ric}) — ${c.market}, score: ${c.composite_score}`);
    });
  } else if (status.status === 'failed') {
    clearInterval(interval);
    console.error('Failed:', status.error);
  }
}, 5000);

Authorizations

​
Authorization
string
header
required

API key passed as Bearer token

Body

application/json
​
query
string
required

Natural language query describing the investment theme and any filters

Required string length: 2 - 500
Example:

"Find me top 50 electric vehicle companies in Asia"

Response

Job created successfully. Poll the check_url for results.

​
job_id
string

Unique job identifier

​
status
enum<string>

Initial job status

Available options:
pending
​
query
string

The search query submitted

​
check_url
string

URL to poll for job status

​
estimated_duration_seconds
integer

Estimated processing time in seconds

​
message
string

Human-readable status message