Authentication & limits

The API is currently open and free. There are no keys to manage — you can call any endpoint directly.

Authentication

No authentication is required today. When API keys are introduced they'll be sent as a bearer token, and this is the header the API will read:

header (future)

Authorization: Bearer <your-api-key>

Until then you can ignore it — requests without any credentials are served normally.

Rate limits

Requests are limited to 2 per second per IP address. Every response includes standard rate-limit headers:

RateLimit-Limit — requests allowed per second.
RateLimit-Remaining — requests left in the current window.
Retry-After — seconds to wait, sent only on a 429.

Handling 429s

Exceed the limit and the API responds with 429 Too Many Requests and a JSON body pointing at higher-tier options:

429 response

{
  "error": "rate_limited",
  "message": "Rate limit exceeded: max 2 requests/second per IP.",
  "retryAfterSeconds": 1,
  "pricingUrl": "https://newlyfiled.com/pricing"
}

Respect Retry-After and back off. Need more throughput? See pricing.

Errors

Errors return a JSON body with an error code, human-readable message, and a requestId you can quote in support requests. Status codes follow HTTP conventions: 400 bad request, 404 not found, 429 rate limited, 5xx server errors.

cURL

curl -i "https://api.newlyfiled.com/v1/companies/0"