Skip to main content
All LENS API requests require an API key passed via the x-api-key header. For a general overview of authentication flows (querystring, header, OTP + JWT) that apply to both APIs, see Authentication. This page focuses on the LENS-specific key management, feature gating, and error model.

​
Example

curl -H "x-api-key: YOUR_API_KEY" \
  "https://lens-api.tic.io/search-public/companies?q=Volvo&query_by=names.nameOrIdentifier"

​
Managing API keys

API keys are managed through the TIC Lens web application under Settings → API Keys. Each key is tied to a team and inherits the team’s subscription plan and features.

​
Key properties

PropertyDescription
ScopesComma-separated access scopes controlling which operations the key can perform
Valid untilOptional expiry date after which the key stops working
Blocked untilTemporary block set by an administrator
Monthly limitMaximum requests per calendar month
Per-minute limitMaximum requests per sliding 60-second window
IP limitMaximum number of distinct IP addresses that can use the key per month

​
Subscription and features

Your API key is linked to a team subscription. Endpoints are gated by plan features (e.g. pro, max, enterprise). If your plan does not include the required feature, the endpoint returns 403 with the missing feature name: 
{
  "status": 403,
  "title": "Feature Not Available",
  "detail": "Your subscription does not include the 'enterprise' feature.",
  "code": "feature_required",
  "features": ["enterprise"]
}
If the team’s subscription has expired, all endpoints return 403: 
{
  "status": 403,
  "title": "Subscription Expired",
  "detail": "Your team's subscription has expired. Please renew to continue.",
  "code": "subscription_expired"
}

​
Brute-force protection

After 10 failed attempts within a 15-minute window, the IP is blocked for 15 minutes. All requests from that IP will return 401 until the block expires. The API tracks failed authentication attempts per IP address. During a block: 
{
  "status": 401,
  "title": "Unauthorized",
  "detail": "Too many failed authentication attempts. Please try again later.",
  "code": "ip_blocked"
}

​
Endpoint access

API keys can only access endpoints marked as public API endpoints. Attempting to call an internal endpoint returns 403: 
{
  "status": 403,
  "title": "Endpoint Not Available",
  "detail": "This endpoint is not available for API key authentication.",
  "code": "endpoint_not_available"
}

​
Request validation

Requests containing SQL injection, XSS, or path traversal patterns are blocked with 400 Bad Request. All requests are inspected for malicious patterns before reaching the application.

​
Error reference

All error responses use the RFC 7807 Problem Details format with an additional code field.
StatusCodeCause
400—Request blocked by input validation (SQL injection, XSS, path traversal)
401missing_tokenNo x-api-key header provided
401invalid_api_keyAPI key not found
401ip_blockedToo many failed attempts from this IP (15-minute cooldown)
403api_key_blockedKey has been temporarily blocked by an administrator
403api_key_expiredKey has passed its ValidUntil date
403subscription_requiredTeam has no active subscription
403subscription_expiredTeam subscription has expired
403feature_requiredEndpoint requires a plan feature the team doesn’t have
403endpoint_not_availableEndpoint is not available for API key access
429rate_limit_exceededRate limit exceeded (see Rate limits)