AI Law Tracker Webhooks API

openapi: 3.2.0
info:
  title: AI Law Tracker — Public Laws Webhooks API
  version: v1
  description: Read-only, versioned JSON API over the audited AI-regulation dataset (US state + federal, EU, and global). FREE beta. Data is CC BY 4.0 — attribution required. Informational only, not legal advice.
  license:
    name: CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/
servers:
- url: https://ai-law-tracker.com/api/v1
security:
- {}
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: Webhooks
paths:
  /webhooks:
    post:
      summary: Subscribe to change events (Pro+ · requires an API key)
      description: 'Create a webhook. When a matching legal record change is observed, an HMAC-SHA256-signed POST is delivered to target_url. The signing_secret is returned ONCE in this response. Verify each delivery (see x-webhooks). TIER-GATING: Pro+ only (Free/Developer allowance = 0 → 403 tier_upgrade_required). Per-key subscription cap: Pro 3, Business 25, Enterprise unlimited.'
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - target_url
              properties:
                target_url:
                  type: string
                  description: Public HTTPS endpoint.
                events:
                  type: array
                  items:
                    type: string
                    enum:
                    - law.created
                    - law.updated
                  description: 'Default: law.created, law.updated.'
                scope:
                  type: string
                  enum:
                  - state
                  - federal
                  - eu
                  - global
                  description: Optional filter.
                jurisdiction:
                  type: string
                  description: Optional exact-slug filter.
      responses:
        '201':
          description: Created (includes signing_secret, shown once).
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Webhook'
        '400':
          description: Invalid target_url or events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: API key required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Per-key webhook limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Webhooks not enabled yet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: createWebhook
      tags:
      - Webhooks
    get:
      summary: List this key's webhooks
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: The key’s subscriptions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Webhook'
        '401':
          description: API key required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: listWebhooks
      tags:
      - Webhooks
  /webhooks/{id}:
    get:
      summary: Get one subscription
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The subscription
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Webhook'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getWebhook
      tags:
      - Webhooks
    delete:
      summary: Unsubscribe
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Deleted
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: deleteWebhook
      tags:
      - Webhooks
components:
  schemas:
    Webhook:
      type: object
      description: A change-notification subscription.
      properties:
        id:
          type: string
          format: uuid
        target_url:
          type: string
          description: HTTPS endpoint that receives signed POSTs.
        events:
          type: array
          items:
            type: string
            enum:
            - law.created
            - law.updated
        scope:
          type:
          - string
          - 'null'
          enum:
          - state
          - federal
          - eu
          - global
          description: Optional filter — only changes in this scope.
        jurisdiction:
          type:
          - string
          - 'null'
          description: Optional filter — only changes for this jurisdiction slug.
        active:
          type: boolean
        failure_count:
          type: integer
          description: Consecutive failed deliveries; the webhook auto-disables at 10.
        disabled_at:
          type:
          - string
          - 'null'
          format: date-time
        disabled_reason:
          type:
          - string
          - 'null'
        last_delivery_at:
          type:
          - string
          - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        api_version:
          type: string
        error:
          type: object
          properties:
            code:
              type: string
              example: rate_limited
            message:
              type: string
            docs:
              type: string
            retry_after:
              type: integer
              description: Seconds (429 only).
          required:
          - code
          - message
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer
x-news:
  description: GET /v1/news copyright + tier gate. We serve ONLY the headline, a short excerpt, the publisher name and the source URL — never full article text. Free = a taste (newest headlines only, low volume, excerpt withheld); Developer+ = the full archive, high volume + the excerpt.
  recency_window_days:
    anonymous: 14
    free_key: 45
    developer: null
    pro: null
    business: null
  excerpt: Developer+ only (withheld on the free/anon taste).
x-webhooks:
  description: Outbound change notifications. Subscribe with POST /v1/webhooks; deliveries are POSTed to target_url with an HMAC-SHA256 signature.
  events:
  - law.created
  - law.updated
  payload:
    $ref: '#/components/schemas/WebhookPayload'
  headers:
    X-ALT-Signature: sha256=<hex HMAC-SHA256 of `${timestamp}.${rawBody}` under your signing_secret>
    X-ALT-Timestamp: Unix seconds; folded into the signed content (reject if skew is large).
    X-ALT-Event: law.created | law.updated
    X-ALT-Delivery: Delivery uuid — use as an idempotency key.
    X-ALT-Webhook-Id: The subscription uuid.
  delivery: At-least-once. Up to 6 attempts with exponential backoff; 10 consecutive failures auto-disable the webhook. De-duplicate on X-ALT-Delivery / event_id.
  verify_example_node: "const crypto = require('crypto');\nfunction verify(req, secret) {\n  const ts = req.headers['x-alt-timestamp'];\n  const sig = (req.headers['x-alt-signature'] || '').replace(/^sha256=/, '');\n  const expected = crypto.createHmac('sha256', secret).update(`${ts}.${req.rawBody}`).digest('hex');\n  const a = Buffer.from(sig), b = Buffer.from(expected);\n  return a.length === b.length && crypto.timingSafeEqual(a, b);\n}"
x-rate-limits:
  description: 'A KEY IS REQUIRED on every data endpoint (since 2026-08-20); a keyless request answers 401 key_required. Free keys are self-serve and need no card — POST /v1/keys, or https://ai-law-tracker.com/developers#get-key. Open without a key: /v1/health, /v1/openapi.json, /v1/keys, /v1/checkout, /v1/auth, /v1/us-law/taxonomy and /v1/us-law/jurisdictions. Per-key limits are enforced by the gate; every response carries X-RateLimit-Limit/Remaining/Reset and a 429 includes Retry-After. Per-key overrides (rate_limit/daily_limit/monthly_limit) take precedence over the tier defaults — GET /v1/me always reports YOUR effective numbers.'
  keyless: not served — 401 key_required (see the open-endpoint list above)
  free_key: 60 req/min, 300 req/day, 9000 req/month
  starter: 150 req/min, 5000 req/day, 150000 req/month
  pro: 300 req/min, 10000 req/day, 300000 req/month
  business: 1000 req/min, 15000 req/day, 450000 req/month
  oem: 1500 req/min, 20000 req/day, 600000 req/month
  enterprise: 2000 req/min, 2000000 req/day (custom above this — contact sales)
  us_law_platform:
    us_free: US Law — Free — 60 req/min, 500 req/day, 750 records/day
    us_entry: US Law — Starter — 100 req/min, 5000 req/day, 2500 records/day
    us_solo: US Law — Solo — 150 req/min, 10000 req/day, 2800 records/day
    us_starter: US Law — Pro — 300 req/min, 25000 req/day, 3100 records/day
    us_pro: US Law — Business — 600 req/min, 100000 req/day, 75000 records/day
    us_enterprise: US Law — Enterprise — 2000 req/min, 500000 req/day, 250000 records/day
x-pricing:
  description: Two product lines over two corpora. AI Law Tracker sells the AI-specific corpus (/laws, /search, /news, the interpreted obligations layer); the US Law Platform sells the general US-law corpus (/us-law) and is metered on RECORDS SERVED rather than requests. A key is licensed for one line or the other (or both). See https://ai-law-tracker.com/pricing.
  ai_law:
  - id: free
    name: Free
    price_usd_month: 0
    self_serve: false
    note: Demo & prototyping
  - id: starter
    name: Starter
    price_usd_month: 49
    self_serve: true
    note: Ship your first integration
  - id: pro
    name: Pro
    price_usd_month: 99
    self_serve: true
    note: AI products & vendors
  - id: business
    name: Business
    price_usd_month: 299
    self_serve: true
    note: Vendors, firms & gov-affairs
  - id: oem
    name: OEM / White-label
    price_usd_month: 499
    self_serve: false
    note: Embed & redistribute the data
  - id: enterprise
    name: Enterprise
    price_usd_month: null
    self_serve: false
    note: Big 4, insurers & RegTech platforms
  us_law:
  - id: us_free
    name: US Law — Free
    price_usd_month: 0
    records_per_day: 750
    self_serve: false
    note: Evaluate the corpus before you commit
  - id: us_entry
    name: US Law — Starter
    price_usd_month: 99
    records_per_day: 2500
    self_serve: true
    note: Evaluate in production, on one project
  - id: us_solo
    name: US Law — Solo
    price_usd_month: 199
    records_per_day: 2800
    self_serve: true
    note: One developer, one application
  - id: us_starter
    name: US Law — Pro
    price_usd_month: 499
    records_per_day: 3100
    self_serve: true
    note: A team building on the corpus, over the API
  - id: us_pro
    name: US Law — Business
    price_usd_month: 1500
    records_per_day: 75000
    self_serve: false
    note: Pipelines & bulk export, under licence
  - id: us_enterprise
    name: US Law — Enterprise
    price_usd_month: null
    records_per_day: 250000
    self_serve: false
    note: Platforms, insurers & redistribution
  retired:
  - id: developer
    name: Developer
    price_usd_month: 29
    note: Withdrawn from sale 2026-08-19. Existing keys keep every limit and capability they had; no new checkout is accepted. Replaced by Starter ($49).
x-attribution: Data by AI Law Tracker (CC BY 4.0) — https://ai-law-tracker.com