Authentication

API Keys

All API requests require authentication using an API key. Include your key in the X-API-Key header:

curl "https://api.debtstack.ai/v1/companies" \
  -H "X-API-Key: ds_xxxxx"

Keep your API key secure. Never expose it in client-side code or public repositories.

Getting Your API Key

Sign up at debtstack.ai
Go to your Dashboard
Copy your API key from the API Keys section

Key Format

API keys follow the format ds_ followed by 32 hexadecimal characters:

ds_a1b2c3d4e5f6789012345678abcdef12

Rate Limits

Rate limits are applied per API key based on your tier:

Tier	Rate Limit	Queries
Pay-as-You-Go	60/min	Pay per call
Pro	100/min	Unlimited
Business	500/min	Unlimited

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1706140800

Handling Rate Limits

When you exceed the rate limit, you’ll receive a 429 Too Many Requests response:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 30 seconds.",
    "details": {
      "retry_after": 30
    }
  }
}

Check the Retry-After header for when you can retry.

Credit System (Pay-as-You-Go)

Pay-as-You-Go users pay per API call based on endpoint complexity:

Endpoint Type	Cost	Endpoints
Simple	$0.05	`/v1/companies`, `/v1/bonds`, `/v1/bonds/resolve`, `/v1/financials`, `/v1/collateral`, `/v1/covenants`
Complex	$0.10	`/v1/companies/{ticker}/changes`
Advanced	$0.15	`/v1/entities/traverse`, `/v1/documents/search`, `/v1/batch`

Credit Packages

Pre-purchase credits for predictable budgeting:

Package	Approximate Queries
$10	~200 simple queries
$25	~500 simple queries
$50	~1,000 simple queries
$100	~2,000 simple queries

Credits never expire and remain in your account until used.

Checking Credit Balance

curl "https://api.debtstack.ai/v1/auth/me" \
  -H "X-API-Key: ds_xxxxx"

Response:

{
  "email": "user@example.com",
  "tier": "pay_as_you_go",
  "credits": {
    "remaining": 4500,
    "resets_at": null
  }
}

Pricing Tiers

Pay-as-You-Go

$0/month + usage

Pay per API call ( $0.05-$ 0.15)
60 requests/minute
211 companies
All basic endpoints
No monthly commitment

Pro

$199/month

Unlimited API queries
100 requests/minute
211 companies
All basic endpoints
Email support (48hr)

Business

$499/month

Everything in Pro, plus:
500 requests/minute
5 team seats
Covenant comparison
Historical bond pricing
Bulk data export
Usage analytics
Priority support (24hr)
99.9% uptime SLA

Business-Only Endpoints

These advanced endpoints are exclusively available on the Business tier:

Endpoint	Description
`/v1/covenants/compare`	Compare covenants across multiple companies
`/v1/bonds/{cusip}/pricing/history`	Historical bond pricing (up to 2 years)
`/v1/export`	Bulk data export (up to 50,000 records)
`/v1/usage/analytics`	Detailed usage analytics and trends

For Business tier inquiries, contact us.

Security Best Practices

Use environment variables

Store your API key in environment variables, not in code:

import os
API_KEY = os.environ.get("DEBTSTACK_API_KEY")

Rotate keys periodically

You can regenerate your API key from the dashboard. The old key will be immediately invalidated.

Monitor usage

Check your usage regularly in the dashboard to detect any unauthorized access.

Get Started

Core Concepts

Guides

API Keys

Getting Your API Key

Key Format

Rate Limits

Rate Limit Headers

Handling Rate Limits

Credit System (Pay-as-You-Go)

Credit Packages

Checking Credit Balance

Pricing Tiers

Pay-as-You-Go

Pro

Business

Business-Only Endpoints

Security Best Practices

​API Keys

​Getting Your API Key

​Key Format

​Rate Limits

​Rate Limit Headers

​Handling Rate Limits

​Credit System (Pay-as-You-Go)

​Credit Packages

​Checking Credit Balance

​Pricing Tiers

Pay-as-You-Go

Pro

Business

​Business-Only Endpoints

​Security Best Practices

API Keys

Getting Your API Key

Key Format

Rate Limits

Rate Limit Headers

Handling Rate Limits

Credit System (Pay-as-You-Go)

Credit Packages

Checking Credit Balance

Pricing Tiers

Business-Only Endpoints

Security Best Practices