Search, then fetch

This is the one thing to understand before writing any code. A search response contains encrypted string IDs and no record data at all. To read the records you send those IDs to the detail route for the same dataset, in batches of up to 100. There is no endpoint that does both.

# 1. Search. The response is IDs, a total, and a next cursor.
ids=$(curl -s -X POST "https://mira-api.metix.ai/v1/companies/query" \
  -H "Authorization: Bearer $METIX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"where": {"all": [{"field": "industry", "match": "biotechnology"}]}, "size": 25}' \
  | jq '.data.company_ids')

# 2. Fetch. The response is records, for the IDs step 1 returned.
jq -n --argjson ids "$ids" '{company_ids: $ids}' |
curl -X POST "https://mira-api.metix.ai/entity/v1/companies/detail-by-id" \
  -H "Authorization: Bearer $METIX_KEY" \
  -H "Content-Type: application/json" \
  -d @-

# {"code":200,"msg":"ok","data":{"total":25,"found":25,"not_found":[],"results":[ ... ]}}

All three search routes take the same where tree: composers all, any, and not around leaves that apply one operator to one field. What changes between datasets is the field list, not the grammar.

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

A leaf carries exactly one operator, so a bounded range is an all of two leaves rather than gte and lte in one node. The field decides which operators it takes: free-text fields take match, fields compared whole (categories, names, codes, yes or no) take eq or in, and numbers and dates take the range operators. GET /contract lists them for every field, and the query spec page covers composition, operators, relative dates, same-record scopes, and cursor paging.

A search takes an optional size and answers with the ids it found, a total, and a next cursor while more remain. The same three rules hold on all three datasets.

// Page 1 response
{"data": {"job_ids": ["Jb71xKcAoP"], "total": 4278, "next": "<opaque cursor>"}}

// Page 2 request: the same where, and next sent back unchanged as after
{"where": {"all": [{"field": "title", "match": "data engineer"}]},
 "size": 100,
 "after": "<the next value from page 1>"}

total is the field to read before paging at all: it tells you whether the filter is narrow enough to be worth walking, and it costs nothing extra to look at.

API Credits are spent per result, not per request, and the rate is the same on every plan. A larger plan buys a larger monthly allowance rather than a different rate.

Nothing is charged for a refused request, a timeout or a 5xx, so a malformed query costs only the round trip. credits carries the settlement rules and the plan allowances.

Every route below the system endpoints takes a bearer key. Create one at https://platform.metix.ai/api-keys; keys begin with metix_, and one issued before that rename begins with mira_ and is still valid.

export METIX_KEY="metix_xxxxxxxxxxxx"

curl -s "https://mira-api.metix.ai/auth/key/status" \
  -H "Authorization: Bearer $METIX_KEY"

GET /auth/key/status reports whether the key is active, its scopes, its rate limit, and the quota it has left, which makes it the cheapest way to tell a bad key apart from an exhausted balance. A 401 carries missing_api_key or invalid_api_key and docs_url to the run. Other public error_code values are on the error-codes page.

Everything above is the same on all three. What differs is the field vocabulary, and each dataset carries its own: a page for searching it, and a page for the record that comes back. They share no field names, so a body written for one is refused by the other two.

The three are joined by identifiers rather than by names. A job carries the hiring company's id and a profile carries each employer's, and both resolve at the companies detail route, so you can walk from a search on one dataset into records on another without matching strings.

/version needs no key and answers two questions. version is the release this build calls itself. contract_hash fingerprints the published contract: it changes when a route, a parameter, a limit or a documented response shape changes, and not otherwise, which makes it the one to pin.

curl -s "https://mira-api.metix.ai/version"

# {"code":200,"msg":"ok","data":{
#   "version":"2.1.2","contract_hash":"08f0406173520512"}}

Pin contract_hash when you integrate. A request that these pages say should work and does not is worth checking against it before anything else: the same value means the contract has not moved and the problem is in the query, and a different one means it has, and the changelog says how.

GET /contract returns that contract as JSON: every route with its parameters and limits, and the queryable field vocabulary for each dataset. It takes your key and costs nothing. These pages are written; that is generated from the API answering you, so it describes what is being served rather than what was true when a page was last edited.

curl -s "https://mira-api.metix.ai/contract" \
  -H "Authorization: Bearer $METIX_KEY" | jq '.data.endpoints[].path'