New to the API? See the plans and how records are counted, or get your API key in about a minute.

etailinsights API v1

Read-only access to the etailinsights database of eCommerce companies, websites and contacts. Base URL: https://mcp.etailinsights.com. Every path below is relative to it. Reference revision 2026-11 (records metering).

Authentication

Send your API key in the X-ETI-API-Key header on every request except GET /v1/health. Keys look like eti_ followed by 32 lowercase hex characters. A missing, malformed, unknown or revoked key returns 401 unauthorized; the body never says which. The MCP endpoint, POST /mcp, takes the same key as Authorization: Bearer instead — and only there: a REST route ignores an Authorization header (see MCP and connectors).

curl -H "X-ETI-API-Key: eti_0123456789abcdef0123456789abcdef" \
     "https://mcp.etailinsights.com/v1/companies/by-domain?domain=glossier.com"

Response envelope

Every response — success or error — has the same shape. Exactly one of data and error is non-null.

{
  "data":  { ... },                       // the record(s), or null on error
  "error": null,                          // or {"code": "...", "message": "..."}
  "meta":  {
    "request_id": "6f1c0e2a-…",           // server-generated; quote it when reporting an issue
    "latency_ms": 41,                     // server-side processing time
    "records_returned": 1                 // records this response counted against your allotment (0 on errors)
  }
}

error.code is stable and machine-readable; error.message is for people and may change. Timestamps are UTC ISO-8601 with a Z suffix.

Endpoints

GET /v1/health

No authentication. Returns 200 with {"status": "ok", "checks": {"mysql": "ok", "dynamodb": "ok"}, "version": "…"}, or 503 with "status": "degraded" when a dependency check fails. Not wrapped in the envelope.

GET /robots.txt

No authentication. Plain text that asks crawlers to stay off this host, apart from the paths MCP clients call before signing in. Not wrapped in the envelope, not counted.

GET /v1/companies/by-domain

Look up one company by its web domain. Returns a CompanyRecord. One record.

Errors: 400 invalid_request (missing or malformed domain), 404 not_found.

GET /v1/companies/{company_id}

Look up one company by its public ID. Returns a CompanyRecord. One record.

Errors: 400 invalid_request, 404 not_found.

GET /v1/companies/{company_id}/contacts

The company's published contacts, C-suite first, paged. Each contact returned counts as one record (see Records and limits).

{
  "data": {
    "company_id": "eti_co_abc12345-1111-2222-3333-444455556666",
    "contacts": [ { ...ContactRecord... }, ... ],
    "total": 14,            // contacts matching the filter
    "offset": 0,
    "limit": 10,            // the page size served
    "returned": 10,         // len(contacts) — the records this response counted
    "has_more": true,
    "next_offset": 10       // present only when has_more
  },
  "error": null,
  "meta": { "request_id": "…", "latency_ms": 63, "records_returned": 10 }
}

Errors: 400 invalid_request, 403 regulatory_restriction (the company is in a GDPR/CASL-restricted country; contacts are withheld, the company itself is still readable), 404 not_found. A company with no matching contacts is 200 with an empty list, not 404.

GET /v1/contacts/by-email

Look up one contact by email address. Returns the ContactRecord plus a CompanySummary of their company. One record (the summary is part of it).

{ "data": { "contact": { ...ContactRecord... }, "company": { ...CompanySummary... } }, "error": null, "meta": { ... } }

Errors: 400 invalid_request, 403 regulatory_restriction, 404 not_found.

GET /v1/website-info/by-domain

Website metadata and the technology platforms detected on it. Returns a WebsiteInfoRecord. One record (the platforms list is part of it).

Errors: 400 invalid_request, 404 not_found.

Application surface — POST /v1/search/websites, POST /v1/search/companies, POST /v1/search/executives

Criteria search is reserved for the etailinsights application. These paths are not part of the customer API: a key without the search:advanced scope receives 404 not_found, exactly as for a path that does not exist. Search results are not records and never count against an allotment.

Data models

All fields are present in every response; a value that is unknown is null (or an empty list for list fields). No field is hidden by plan — one call returns the full record.

CompanyRecord

CompanySummary

The four identity fields of a CompanyRecord — id, name, domain, business_type — embedded in /v1/contacts/by-email responses. Fetch the full record with /v1/companies/{company_id}.

ContactRecord

WebsiteInfoRecord

Records and limits

Your plan buys records per month. A record is one company, one website, or one contact returned in a successful (2xx) response. Errors return no records and count nothing. Calls are separately rate-limited per minute (and, on some keys, per day) so one runaway loop cannot flood the service.

Records per endpoint

meta.records_returned on every response is exactly this number.

Plans

The month is the UTC calendar month; your count resets at 00:00 UTC on the 1st. Need more this month, or a bigger plan? Contact support@etailinsights.com.

Limit headers

Every authenticated response carries the state of each limit including that response, so you can pace a client without a separate call.

Reaching the limit

A request that would take you past your monthly allotment is refused with 429 and error.code = "record_limit_exceeded". There is no overage: the key simply stops until the month resets, a grant is added, or the plan changes.

HTTP/1.1 429 Too Many Requests
Retry-After: 864000
X-Records-Limit: 10000
X-Records-Used: 10000
X-Records-Remaining: 0
X-Records-Reset: 1796083200

{
  "data": null,
  "error": {
    "code": "record_limit_exceeded",
    "message": "You've hit your limit for the month; it resets 2026-12-01T00:00:00Z. Contact support@etailinsights.com to increase your limit."
  },
  "meta": { "request_id": "…", "latency_ms": 3, "records_returned": 0 }
}

• Retry-After on this error is the time to the month's start and can be millions of seconds. That is correct; do not treat it as a parsing error.
• Contacts near the limit. A contacts page that would cross the allotment is served short: you get the contacts that still fit, limit is the size served, has_more and next_offset work as usual, and X-Records-Remaining is 0. The next request is the 429.
• A key with an allotment of 0 is blocked outright: every lookup is 429 with X-Records-Limit: 0. When a request is refused before it can be counted, X-Records-Used reports the allotment (or 0 for a blocked key) because no count was read.
• The three 429 codes are distinct: rate_limited (per minute; wait Retry-After seconds), daily_limit_exceeded (per day; resets at midnight UTC) and record_limit_exceeded (per month). Each carries its own header family. Because the daily cap equals the monthly records limit, a key that spends a whole month's records in one day is told record_limit_exceeded — the month is the reason, not the day — while a key that made its daily number of calls with records to spare gets daily_limit_exceeded and can continue at midnight UTC.
• A refused request is still a call for the per-minute limit, but returns no records and never counts against your allotment.

MCP and connectors

The same records are available to AI assistants through the Model Context Protocol (MCP), at one endpoint.

POST /mcp

Streamable HTTP, answered with one JSON response per POST: no event streams and no sessions. Protocol revisions 2025-06-18, 2025-11-25 and 2026-07-28 are served. GET and DELETE on /mcp return 405.

• Authentication: Authorization: Bearer <your API key>. Clients that can set arbitrary headers may send X-ETI-API-Key instead — never both. Assistants that sign in instead send an OAuth access token as Authorization: Bearer (Connecting by sign-in). A missing, malformed, unknown or revoked key or token returns 401 with the error envelope above and a WWW-Authenticate: Bearer challenge, whatever the method. When a credential was sent and refused, the challenge also carries error="invalid_token" (RFC 6750); a malformed one, error="invalid_request".
• Origin: a request carrying an Origin header that is not on the allowed list is refused with 403 before the key is checked. Server-side clients send none.
• Limits: discovery and listing the tools cost nothing. Each tool call counts as one call against the per-minute limit and the daily call cap, and its records count against the same monthly allotment as REST — one allotment and one daily cap per key, across REST and MCP.
• Data: field values are data about third parties, never instructions to an assistant.

Each tool takes the parameters of the REST endpoint it matches, with the same bounds, and returns that endpoint's data object unchanged, with the limit values beside it.

• A result carries structuredContent = {"data": …, "meta": …}: data exactly as the REST endpoint returns it, and meta with request_id, latency_ms, records_returned and the values of the X-Records-*, X-RateLimit-* and X-Daily-* headers as records, rate_limit and daily. Its text is a short summary built from ids, counts and figures, followed by the record itself as JSON in a labelled fence, for clients that give the model the text only.
• A failure is a tool result with isError: true, not an HTTP or JSON-RPC error: its text is the REST error.code and message (Errors) and what to do next, and the same code, message and limit values are in _meta["com.etailinsights/error"]. An unknown tool name is a JSON-RPC -32602 error and costs nothing.
• Usage reports list MCP calls on their own lines, as mcp: followed by the endpoint's path (for example mcp:/v1/companies/by-domain); the totals cover both.

Connecting by sign-in (OAuth)

Assistants that cannot send a key header — claude.ai, Claude Desktop and ChatGPT — connect through OAuth 2.1. The assistant finds the server from the 401 challenge, registers itself, and opens a consent page where you paste your API key once. The page shows which key it is — its label, plan and prefix — and nothing connects until you choose Connect. The assistant then calls /mcp with an access token that stands for that key: the same limits, the same allotment and the same records as the key itself.

• Access tokens last one hour and refresh tokens 30 days. Each refresh replaces the refresh token; presenting a replaced one again ends the connection.
• Revoking or replacing a key disconnects every assistant connected with it, at its next call. The first call that finds the key gone deletes every token issued for it that still works, so each assistant's next refresh is invalid_grant and it asks you to sign in again. A single revoked token stops working within a minute.
• These tokens are for /mcp only. REST takes X-ETI-API-Key and nothing else.

Errors