Response Format

All API responses follow a consistent JSON envelope structure.

Success response (list)

{
  "success": true,
  "data": [
    { "id": 12345, "owner": "John Smith", "current_amount": 15432.50, "..." : "..." }
  ],
  "pagination": {
    "total": 8423,
    "limit": 20,
    "offset": 0,
    "has_more": true
  },
  "meta": {
    "request_id": "req_a1b2c3d4",
    "tier": "pro",
    "rate_limit_remaining": 4823
  }
}

Success response (single item)

{
  "success": true,
  "data": {
    "id": 12345,
    "owner": "John Smith",
    "current_amount": 15432.50
  },
  "meta": {
    "request_id": "req_a1b2c3d4",
    "tier": "pro",
    "rate_limit_remaining": 4822
  }
}

Error response

{
  "success": false,
  "error": {
    "code": "invalid_parameter",
    "message": "Parameter 'limit' must be between 1 and 100"
  },
  "meta": {
    "request_id": "req_a1b2c3d4"
  }
}

Envelope fields

Field	Type	Description
success	boolean	true if the request succeeded
data	object or array	The response payload. Array for list endpoints, object for single-item endpoints.
pagination	object	Present on list endpoints. Contains total, limit, offset, has_more.
pagination.total	integer	Total number of records matching the filters
pagination.limit	integer	Number of records returned in this response
pagination.offset	integer	Number of records skipped
pagination.has_more	boolean	true if more records exist beyond current page
meta	object	Request metadata
meta.request_id	string	Unique identifier for this request (useful for support)
meta.tier	string	Your current API tier (free, pro, or enterprise)
meta.rate_limit_remaining	integer	Requests remaining in your daily quota
error	object	Present only on error responses
error.code	string	Machine-readable error code
error.message	string	Human-readable error description

HTTP status codes

Code	Meaning
200	Success
400	Bad request — invalid parameters
401	Unauthorized — missing or invalid API key
404	Not found — resource doesn't exist
429	Rate limited — daily quota exceeded
500	Server error — try again or contact support

Rate limit headers

Every response includes these headers:

Header	Description
X-RateLimit-Limit	Your daily request quota
X-RateLimit-Remaining	Requests remaining today
X-RateLimit-Reset	Unix timestamp when the limit resets (midnight UTC)
Retry-After	Seconds until reset (only on 429 responses)

Pagination

Use limit and offset query parameters to paginate through results:

# Page 1 (first 20 results)
GET /v1/filings?limit=20&offset=0

# Page 2
GET /v1/filings?limit=20&offset=20

# Page 3
GET /v1/filings?limit=20&offset=40

Maximum limit is 100. Default is 20.