Conventions

This page lists the conventions the API follows everywhere, so the reference for individual endpoints can stay focused on what's specific to that endpoint.

Content type


Request bodies	JSON (`Content-Type: application/json`)
Response bodies	JSON (`Content-Type: application/json; charset=utf-8`)
Max request body size	1 MB

No XML, no form-encoded uploads on JSON endpoints.

Response envelope

Every JSON response wraps its payload in a consistent envelope. Look at success first.

Success

{
  "success": true,
  "data": { "...": "endpoint-specific fields" }
}

The exact shape next to success: true depends on the endpoint — see the API reference for each route's schema.

Error

{
  "success": false,
  "error": "Human-readable message",
  "code": "MACHINE_READABLE_CODE"
}

Some errors carry additional fields (issues for validation, request_id for unhandled errors). The full taxonomy is on the Errors page.

HTTP status codes

Range	Meaning
`2xx`	Success. The envelope's `success` is `true`.
`4xx`	Client problem. Fix the request before retrying.
`5xx`	Server problem on our side.
`502` / `503` / `504`	Specifically signal a backing-service issue — see Errors.

The API never returns 2xx with success: false. Status code and envelope agree.

Common headers

Header	Direction	Purpose
`X-API-Key`	Request	API key — see Authentication.
`Content-Type`	Both	`application/json` for JSON endpoints.
`X-Request-Id`	Response	End-to-end tracing — see Request ID.
`X-Credit-Cost`	Response	Credits charged for the request.
`X-Remaining-Balance`	Response	Credits left on your account after the request.
`X-RateLimit-Limit` / `-Remaining` / `-Reset`	Response	Standard rate-limit metadata.

Versioning

The current API version is v0.1.0.

Endpoints follow a flat path layout (/api/companies/..., /api/persons/..., /api/stocks/...).

Breaking changes to a resource will land under a versioned path (/api/v2/...) while the old version stays available during a deprecation window.

Adding new fields to a response is not a breaking change. Clients should ignore unknown fields.

Removing or renaming a field, or changing a field's type, is a breaking change and only happens with a new version.

Pagination

List endpoints that support pagination accept limit and offset query (or body) parameters and return:

{
  "success": true,
  "data": {
    "total": 1234,
    "items": [ /* ... */ ]
  }
}

Where pagination is not yet supported the endpoint returns its full result set.

Date and time

All timestamps in responses are UTC, formatted as ISO 8601 with millisecond precision (e.g. 2026-04-30T13:42:55.123Z). Don't assume local time anywhere.

Field naming

JSON field names are snake_case (request_id, uptime_seconds). HTTP header names follow the conventional Capitalized-Hyphenated form (X-Request-Id).

Idempotency

GET and HEAD are safe and idempotent. POST search endpoints are read-only and idempotent in practice. Mutating endpoints will support idempotency keys via a header in a future version.

Security headers

Every response carries standard security headers. You don't need to act on them, but expect to see things like Strict-Transport-Security, X-Content-Type-Options: nosniff, and a tight Content-Security-Policy.

Content type#

Response envelope#

Success#

Error#

HTTP status codes#

Common headers#

Versioning#

Pagination#

Date and time#

Field naming#

Idempotency#

Security headers#