API Reference

JSON REST API. All responses use a standard envelope. Rate limited per tier.

Base URL: https://saaspricingarchive.com/v1

Authentication

Get your API key at /signup. Include it in every request as a Bearer token.

curl https://saaspricingarchive.com/v1/account \
  -H "Authorization: Bearer spa_YOUR_API_KEY_HERE"

Your key is shown once at signup and sent to your email. To rotate it, call POST /v1/account/keys. The old key is immediately invalidated.

Response format

Every response wraps data in a standard envelope.

Success (2xx)

{
  "data": {'{ ... }'},
  "meta": {
    "request_id": "req_7x2k9m",
    "timestamp": "2026-03-28T09:14:23Z"
  }
}

Error (4xx / 5xx)

{
  "error": {
    "code": "not_found",
    "message": "Company not found.",
    "status": 404
  }
}

Rate limit headers

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers so you can track your monthly usage.

Tiers

Access to companies and historical data depends on your tier.

Tier	Price	Companies	History	API Calls/Month
Free	$0	Top 100	Current only	1,000
Starter	$99/mo	500	1 year	10,000
Pro	$299/mo	2,500	Full (5+ years)	50,000
Enterprise	$799/mo	All 5,000+	Full	Unlimited

Endpoints

GET /v1/stats

Returns global statistics about the archive.

Auth: Not required Tier: All

Curl example

curl https://saaspricingarchive.com/v1/stats

Sample response

{
  "data": {
    "total_companies": 523,
    "total_records": 4891,
    "last_crawl": "2026-04-05T02:00:00Z"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-04-05T10:00:00Z"
  }
}

GET /v1/companies

Search and list companies in the archive.

Auth: Required Tier: All

Parameters

Name	Type	Required	Description
q	string	No	Search query. Matches company name or domain.
category	string	No	Filter by category slug (e.g., "productivity").
page	number	No	Page number. Default: 1.
per_page	number	No	Results per page. Default: 50. Max: 100.

Curl example

curl "https://saaspricingarchive.com/v1/companies?q=notion&per_page=10" \
  -H "Authorization: Bearer spa_YOUR_API_KEY_HERE"

Sample response

{
  "data": [
    {
      "id": "uuid",
      "name": "Notion",
      "domain": "notion.so",
      "category": "Productivity",
      "pricing_url": "https://notion.so/pricing",
      "is_top_100": true,
      "tier_access_rank": 1
    }
  ],
  "meta": {
    "request_id": "req_abc",
    "timestamp": "..."
  },
  "pagination": {
    "total": 523,
    "page": 1,
    "per_page": 50
  }
}

GET /v1/companies/:id

Get a single company by UUID or domain (e.g., notion.so).

Auth: Required Tier: All

Curl example

curl https://saaspricingarchive.com/v1/companies/notion.so \
  -H "Authorization: Bearer spa_YOUR_API_KEY_HERE"

GET /v1/categories

List all categories with their company counts.

Auth: Required Tier: All

Curl example

curl https://saaspricingarchive.com/v1/categories \
  -H "Authorization: Bearer spa_YOUR_API_KEY_HERE"

Sample response

{
  "data": [
    {
      "name": "Productivity",
      "slug": "productivity",
      "company_count": 47
    }
  ],
  "meta": { ... }
}

GET /v1/categories/:slug/companies

List all companies in a given category.

Auth: Required Tier: All

Parameters

Name	Type	Required	Description
page	number	No	Page number. Default: 1.
per_page	number	No	Results per page. Default: 50. Max: 100.

Curl example

curl "https://saaspricingarchive.com/v1/categories/productivity/companies" \
  -H "Authorization: Bearer spa_YOUR_API_KEY_HERE"

GET /v1/companies/:id/pricing

Latest pricing data for a company. This is the core endpoint. Access is tier-gated based on the company's tier_access_rank.

Auth: Required Tier: Free (top 100), Starter+ (500), Pro+ (2,500), Enterprise (all)

Curl example

curl https://saaspricingarchive.com/v1/companies/notion.so/pricing \
  -H "Authorization: Bearer spa_YOUR_API_KEY_HERE"

Sample response

{
  "data": {
    "company": {
      "name": "Notion",
      "domain": "notion.so",
      "category": "Productivity",
      "total_snapshots": 18,
      "pricing_changes_detected": 4,
      "first_captured": "2021-03-01",
      "last_captured": "2026-03-28"
    },
    "captured_at": "2026-03-28T09:14:22Z",
    "source_type": "live_crawl",
    "currency": "USD",
    "free_tier_exists": true,
    "enterprise_plan_exists": true,
    "extraction_confidence": 0.94,
    "plans": [
      {
        "name": "Free",
        "price_monthly": 0,
        "price_annual_per_month": 0,
        "price_unit": null,
        "is_highlighted": false,
        "features": [
          "Unlimited pages & blocks",
          "Share with up to 10 guests",
          "7-day page history"
        ]
      },
      {
        "name": "Plus",
        "price_monthly": 12,
        "price_annual_per_month": 8,
        "price_unit": "user",
        "is_highlighted": true,
        "features": [
          "Unlimited guests",
          "30-day page history",
          "Unlimited file uploads"
        ]
      }
    ]
  },
  "meta": {
    "request_id": "req_7x2k9m",
    "timestamp": "2026-03-28T09:14:23Z"
  }
}

GET /v1/companies/:id/pricing/history

All historical pricing records for a company, ordered newest first. Starter tier is capped to 1 year back. Pro and Enterprise have full history.

Auth: Required Tier: Starter+

Parameters

Name	Type	Required	Description
from	string (ISO date)	No	Start date filter. E.g., `2024-01-01`.
to	string (ISO date)	No	End date filter. E.g., `2025-01-01`.
cursor	string (ISO date)	No	Pagination cursor. Pass `next_cursor` from previous response.
limit	number	No	Number of records. Default: 20. Max: 100.

Curl example

curl "https://saaspricingarchive.com/v1/companies/notion.so/pricing/history?limit=5" \
  -H "Authorization: Bearer spa_YOUR_API_KEY_HERE"

Pagination

Responses include a pagination object with limit, next_cursor, and has_more. Pass next_cursor as the cursor param to fetch the next page.

GET /v1/companies/:id/pricing/changes

Only records where pricing changed. Useful for building change-detection pipelines. Same parameters as /history.

Auth: Required Tier: Starter+

Curl example

curl "https://saaspricingarchive.com/v1/companies/notion.so/pricing/changes" \
  -H "Authorization: Bearer spa_YOUR_API_KEY_HERE"

GET /v1/account

Returns current account info with usage statistics.

Auth: Required Tier: All

Curl example

curl https://saaspricingarchive.com/v1/account \
  -H "Authorization: Bearer spa_YOUR_API_KEY_HERE"

Sample response

{
  "data": {
    "id": "uuid",
    "email": "you@example.com",
    "tier": "free",
    "api_key_prefix": "spa_abcd1234...",
    "usage": {
      "monthly_calls": 142,
      "monthly_limit": 1000,
      "calls_reset_at": "2026-05-01T00:00:00Z",
      "remaining": 858
    }
  },
  "meta": { ... }
}

POST /v1/account/keys

Rotate your API key. The old key is immediately invalidated. The new key is shown once in the response.

Auth: Required Tier: All

Curl example

curl -X POST https://saaspricingarchive.com/v1/account/keys \
  -H "Authorization: Bearer spa_YOUR_API_KEY_HERE"

Sample response

{
  "data": {
    "api_key": "spa_new_key_here...",
    "prefix": "spa_abcd1234...",
    "message": "New API key generated."
  }
}

POST /v1/upgrade

Upgrade to a paid tier. Returns a Stripe checkout URL. Open it in a browser to complete payment. Your tier updates automatically after payment.

Auth: Required Tier: All

Parameters (JSON body)

Name	Type	Required	Description
tier	string	Yes	Target tier: `"starter"`, `"pro"`, or `"enterprise"`.
success_url	string	No	Redirect URL after successful payment.
cancel_url	string	No	Redirect URL if the user cancels checkout.

Curl example

curl -X POST https://saaspricingarchive.com/v1/upgrade \
  -H "Authorization: Bearer spa_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"tier": "starter"}'

Sample response

{
  "data": {
    "checkout_url": "https://checkout.stripe.com/c/pay/cs_...",
    "tier": "starter"
  }
}

POST /v1/account/billing-portal

Get a link to the Stripe billing portal. Use it to update your card, cancel, or view invoices. Requires a prior upgrade. Returns 400 if you haven't upgraded yet.

Auth: Required Tier: Starter+

Curl example

curl -X POST https://saaspricingarchive.com/v1/account/billing-portal \
  -H "Authorization: Bearer spa_YOUR_API_KEY_HERE"

Sample response

{
  "data": {
    "portal_url": "https://billing.stripe.com/..."
  }
}

Error codes

All errors return a JSON body with code, message, and status.

Code	Status	Description
missing_api_key	401	No Authorization header was included in the request.
invalid_api_key	401	Key not found or incorrect.
invalid_api_key_format	401	Key doesn't match the expected `spa_` prefix format.
account_inactive	403	Your account has been deactivated.
tier_required	403	This endpoint requires a higher tier. Upgrade at /signup.
rate_limit_exceeded	429	Monthly call limit reached. Resets at the start of your next billing cycle.
validation_error	400	One or more request parameters are invalid. Check the `message` field for details.
not_found	404	The requested resource was not found.
email_already_registered	409	Signup attempted with an email that already has an account.
invalid_upgrade	400	You are already on this tier or higher.
no_subscription	400	The billing portal requires a prior upgrade.
checkout_error	500	Stripe checkout session creation failed. Try again or contact support.
internal_server_error	500	Unexpected server error. If this persists, contact support.