# Metix AI

> Profile, company, and job data for search, analysis, and agents. The entire public API is 9 routes and all of them are listed in this file.

Metix AI serves 3 datasets: people, jobs, companies. One grammar, the Query Spec, searches all three. Every search returns encrypted string IDs and no record data at all; a second call turns up to 100 of those IDs into records. No endpoint does both. Code written as though one does will read an empty payload and conclude the dataset is empty, which is the single most common integration mistake against this API.

## Authentication

Base URL: https://mira-api.metix.ai
Header: Authorization: Bearer $METIX_KEY

Keys begin with metix_ and are created on the API Keys page at https://platform.metix.ai/api-keys. GET /auth/key/status reports whether a key is active, its scopes, its rate limit and its remaining quota. It costs nothing, which makes it the cheapest way to tell a rejected key apart from an exhausted balance.

## Every endpoint

Nothing is left out below. This is the whole callable surface.

### People

- POST /v1/people/query : Query Spec search. MCP tool: metix_query_people.
- POST /v1/people-search : Natural-language search. MCP tool: metix_search_people.
- POST /entity/v1/profiles/detail-by-id : Fetch profile records. MCP tool: metix_get_profiles.

### Jobs

- POST /v1/jobs/query : Query Spec search. MCP tool: metix_query_jobs.
- POST /entity/v1/jobs/detail-by-id : Fetch job records. MCP tool: metix_get_jobs.

### Companies

- POST /v1/companies/query : Query Spec search. MCP tool: metix_query_companies.
- POST /entity/v1/companies/detail-by-id : Fetch company records. MCP tool: metix_get_companies.

### System

- GET /version : Read the deployed version and contract fingerprint. MCP tool: metix_get_version.
- GET /auth/key/status : Inspect authenticated key status, scopes, rate limit, and quota projection. MCP tool: metix_get_key_status.

## Search, then fetch

Search never returns profile records. It returns encrypted string IDs, and you pass up to 100 of them to the detail route to read the records. There is no one-shot endpoint, so plan for two calls.

```bash
# 1. Search. Returns encrypted IDs, never records.
curl -X POST "https://mira-api.metix.ai/v1/people/query" \
  -H "Authorization: Bearer $METIX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "where": {"all": [
      {"field": "city", "eq": "San Francisco"},
      {"has_experience": {"all": [
        {"field": "company_name", "match": "Google"},
        {"field": "level", "eq": "Director"},
        {"field": "is_current", "eq": true}
      ]}}
    ]},
    "size": 25
  }'

# 2. Read the records, up to 100 IDs per call.
curl -X POST "https://mira-api.metix.ai/entity/v1/profiles/detail-by-id" \
  -H "Authorization: Bearer $METIX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_ids": ["kR3nQv8xTm", "9tQmLd2wYb"],
    "_source": ["profile_id", "full_name", "active_experience_title", "skills"]
  }'
```

## Query Spec

```json
{"where": {"all": [{"field": "<name>", "<operator>": <value>}]}, "size": 25}
```

Composers: all, any, not. They nest.
Operators: eq, in, match, gte, lte, exists.
One operator per leaf. A bounded range is an all of two leaves, never gte and lte in one node.
size is 1 to 10000 and caps one page of IDs, defaulting to 100 when omitted. Detail calls take at most 100 IDs.
Paging: pass the previous response's next value back as after. Pages are not consistent with each other, so a set that must be exact should be collected in one pass.
Dates take YYYY-MM-DD or a relative offset such as now-30d.

Same-record scopes, people only: has_education, has_experience, has_language. Every condition inside one scope has to match the same sub-record, which is the difference between a director at a company and someone who was a director somewhere and worked at that company at another time.

## Query fields

These are the only names a leaf may put in field. A name outside the list is refused. What a response may contain is a wider list: a field can be returnable without being queryable.

### People (47)

active_department, active_title, awards, certifications, city, company_employees_count, company_name, company_size_range, company_type, country, country_iso2, country_iso3, courses, degree_level, duration_months, ended_at, experience_months, first_name, full_name, graduation_year, headline, industry, institution_name, institution_ranking, is_current, is_decision_maker, is_studying, is_working, languages, language_proficiency, last_name, level, linkedin_url, major, management_level, patents, publications, regions, role, skills, started_at, state, study_start_year, title, workplace_city, workplace_country, workplace_state

### Jobs (22)

applicants_count, application_active, city, company_name, country, country_iso_2, created_at, description, employment_type, functions, industries, location, posted, regions, required_months_of_experience, salary_currency, salary_max, salary_min, seniority, state, title, updated_at

### Companies (23)

categories_and_keywords, employees_count, employees_count_change_yearly_percentage, followers_count, founded_year, hq_city, hq_country, hq_country_iso2, hq_full_address, hq_regions, hq_state, industry, is_b2b, last_funding_round_amount_raised, last_funding_round_date, last_updated_at, linkedin_url, name, size_range, stock_exchange, stock_ticker, type, website

## Limits

- One operator per leaf. A bounded range is an all of two leaves, not gte and lte in one node. This is the first mistake almost every caller makes.
- A field name that is not in this dataset's list is refused, so a typo is visible rather than returning a record without it. The three datasets do not share one vocabulary.
- Search returns at most 10,000 IDs per page and 100 when size is omitted; detail accepts at most 100 IDs per request.

People:
- Scope nodes exist for people only. Jobs and companies are one document each, so there is nothing to group.
- Every Query Spec search reports total: an exact integer below 100000, and the string "100000+" at or above it. It counts what matched, not what was returned. Read it as a union, not as an integer.
- Profile data is a periodically refreshed snapshot and can lag real-world changes.
- The default record is a subset. Naming fields in _source reaches the full published set: the subject's own links and prose, their employer as a company, and their institution.
- Prose fields carry no email addresses or phone numbers. Contact data is a separate surface with its own pricing.

Jobs:
- Jobs declare no scope nodes. One document is one posting, so there is nothing to group.
- The response carries IDs and a cursor, not a match count. Page until next is absent if you need the size of a set.
- The index holds daily active postings. A posting closed since your search can come back in not_found.

Companies:
- Companies declare no scope nodes. One document is one company, so there is nothing to group.
- The response carries IDs and a cursor, not a match count. Page until next is absent if you need the size of a set.
- Company data is a periodically refreshed snapshot and can lag real-world changes.

## Credits

- People: Query Spec search costs ceil(returned IDs / 25) Credits, and 0 when it returns nothing. Natural-language search costs 5 + ceil(returned IDs / 25) Credits, and keeps the 5 Credit base on any successful response. Profile detail costs ceil(found records / 5) Credits, and not_found rows are free.
- Jobs: Job search costs ceil(returned IDs / 25) Credits, and 0 when it returns nothing. Job detail costs ceil(found records / 5) Credits, and not_found rows are free.
- Companies: Company search costs ceil(returned IDs / 25) Credits, and 0 when it returns nothing. Company detail costs ceil(found records / 5) Credits, and not_found rows are free.

A query is translated before anything is charged, so a request refused for an unknown field or a malformed tree costs nothing.

## MCP

An agent that speaks MCP should use it rather than curl. The MCP surface is the REST surface and nothing more, under the same key, the same limits and the same Credit rules, and the two-step flow does not go away: a search tool still returns IDs, so an agent that stops there is holding strings and no facts.

Streamable HTTP: https://mira-api.metix.ai/mcp (MCP 2025-03-26)
SSE, legacy: https://mira-api.metix.ai/sse (MCP 2024-11-05)

Tools, one per route:
- metix_query_people : POST /v1/people/query
- metix_search_people : POST /v1/people-search
- metix_get_profiles : POST /entity/v1/profiles/detail-by-id
- metix_query_jobs : POST /v1/jobs/query
- metix_get_jobs : POST /entity/v1/jobs/detail-by-id
- metix_query_companies : POST /v1/companies/query
- metix_get_companies : POST /entity/v1/companies/detail-by-id
- metix_get_version : GET /version
- metix_get_key_status : GET /auth/key/status

The server checks this list against its own schema when it starts and refuses to boot if they disagree, so a renamed tool is a deployment failure rather than a wrong name in this file. tools/list on the endpoint above remains the authority for a given deployment.

## Not callable

Announced, with no endpoint, request shape or price to integrate against. Do not attempt these.

- Contact (Coming soon): https://platform.metix.ai/docs/api/contact

## Resources

- Every documentation page in one file: https://platform.metix.ai/llms-full.txt
- The same bundle under its docs path: https://platform.metix.ai/docs/all.md
- Browsable documentation: https://platform.metix.ai/docs
- Any documentation page in markdown: add .md to its path, for example https://platform.metix.ai/docs/api/people.md
- Metix AI agent skills: https://platform.metix.ai/docs/skills

## Documentation pages

Start:
- Overview: https://platform.metix.ai/docs.md
- Quickstart: https://platform.metix.ai/docs/quickstart.md
- Pricing: https://platform.metix.ai/docs/credits.md
How it works:
- Search, then fetch: https://platform.metix.ai/docs/api.md
- Query Spec: https://platform.metix.ai/docs/api/query-spec.md
- Errors: https://platform.metix.ai/docs/reference/errors.md
People:
- Search people: https://platform.metix.ai/docs/api/people.md
- Profile record: https://platform.metix.ai/docs/api/people/record.md
- Contact: https://platform.metix.ai/docs/api/contact.md
Jobs:
- Search jobs: https://platform.metix.ai/docs/api/jobs.md
- Job record: https://platform.metix.ai/docs/api/jobs/record.md
Companies:
- Search companies: https://platform.metix.ai/docs/api/companies.md
- Company record: https://platform.metix.ai/docs/api/companies/record.md
Agent access:
- Metix AI skills: https://platform.metix.ai/docs/skills.md
- MCP setup: https://platform.metix.ai/docs/mcp.md
Reference:
- Changelog: https://platform.metix.ai/docs/reference/changelog.md