POST /api/v1/auth/register

curl -X POST https://api.alexambros.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "you@example.com",
    "name": "my-integration"
  }'

{
  "user_ref":   "3XPT7SS5VG3B",
  "email":      "you@example.com",
  "message":    "Registration successful. Check your email to initialize your account.",
  "expires_at": "2026-03-18T10:48:59+00:00"
}

POST /api/v1/auth/init

curl -X POST https://api.alexambros.com/api/v1/auth/init \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "token": "6d6c675fcebf98fdbeed11055f98fada..."
  }'

{
  "user_ref":      "3XPT7SS5VG3B",
  "email":         "you@example.com",
  "master_token":  "sk_live_5a4a9438c8b8d46836b2dd70bc95d0ee...",
  "token_ref":     "O752ABABBLBE",
  "message":       "Account initialized successfully. Save your Master Token securely - you will not see it again!"
}

POST /api/v1/auth/recover

curl -X POST https://api.alexambros.com/api/v1/auth/recover \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "you@example.com"
  }'

{
  "message":    "If an account with this email exists, a recovery email has been sent.",
  "expires_at": "2026-03-27T09:15:20+00:00"
}

{
  "message": "Recovery confirmation failed",
  "errors":  { "email": ["The email field is required."] }
}

POST /api/v1/tokens

curl -X POST https://api.alexambros.com/api/v1/tokens \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-integration",
    "expires_in_days": 90
  }'

{
  "success": true,
  "data": {
    "token_ref":  "NAHZ4GW2C26H",
    "name":       "my-integration",
    "expires_at": "2026-06-24T11:10:57+00:00",
    "is_active":  true,
    "plaintext":  "sk_api_4b06f7ebafdd3b3cde52712e12de4a5d...",
    "warning":    "Save this token now - it will never be shown again!"
  },
  "meta": {
    "timestamp": "2026-03-24T11:10:57+00:00"
  }
}

GET /api/v1/tokens

curl https://api.alexambros.com/api/v1/tokens \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Accept: application/json"

GET /api/v1/tokens/{token_ref}

curl https://api.alexambros.com/api/v1/tokens/{token_ref} \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Accept: application/json"

PUT /api/v1/tokens/{token_ref}

curl -X PUT https://api.alexambros.com/api/v1/tokens/{token_ref} \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "name": "production-name-change" }'

DELETE /api/v1/tokens/{token_ref}

curl -X DELETE https://api.alexambros.com/api/v1/tokens/{token_ref} \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Accept: application/json"

POST /api/v1/tokens/verify

curl -X POST https://api.alexambros.com/api/v1/tokens/verify \
  -H "Authorization: Bearer sk_api_xxxx" \
  -H "Accept: application/json"

POST /api/v1/tokens/{token_ref}/rotate

curl -X POST https://api.alexambros.com/api/v1/tokens/{token_ref}/rotate \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Accept: application/json"

GET /api/v1/wallet

curl https://api.alexambros.com/api/v1/wallet \
  -H "Authorization: Bearer sk_api_xxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

{
  "status": "success",
  "data": {
    "balance":         99845,
    "total_purchased": 100000
  }
}

POST /api/v1/wallet/topup

curl -X POST https://api.alexambros.com/api/v1/wallet/topup \
  -H "Authorization: Bearer sk_api_xxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "package_slug": "pack_10k" }'

{
  "status": "success",
  "data": {
    "checkout_url": "https://api.alexambros.com/checkout-pay?_ptxn=txn_01kkxrrc...",
    "package":      "pack_10k",
    "credits":      10000
  }
}

GET /api/v1/wallet/transactions?page=1

curl "https://api.alexambros.com/api/v1/wallet/transactions?page=1" \
  -H "Authorization: Bearer sk_api_xxxx" \
  -H "Accept: application/json"

{
  "status": "success",
  "data": [
    {
      "type":          "deposit",
      "amount":        "10000.00",
      "balance_after": "10100.00",
      "description":   "Wallet top-up (Paddle)",
      "created_at":    "2026-03-30T08:40:05.000000Z"
    },
    {
      "type":          "start",
      "amount":        "100.00",
      "balance_after": "100.00",
      "description":   "Welcome bonus credits",
      "created_at":    "2026-03-30T06:55:25.000000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page":    1,
    "per_page":     20,
    "total":        2,
    "next_page":    null,
    "prev_page":    null
  }
}

POST /api/v1/companies/add

curl -X POST https://api.alexambros.com/api/v1/companies/add \
  -H "Authorization: Bearer sk_api_xxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "identifier_type":  "REGON9",
    "identifier_value": ["241150780", "290368057", "543478623"]
  }'

{
  "success": true,
  "message": "Accepted for processing."
}

GET /api/v1/companies/watched

curl "https://api.alexambros.com/api/v1/companies/watched?page=1" \
  -H "Authorization: Bearer sk_api_xxxx" \
  -H "Accept: application/json"

{
  "success": true,
  "data": [
    {
      "primary_identifier": "241150780",
      "name":               "Aleksander Ambros",
      "watched_since":      "2026-03-24",
      "last_event_at":      null,
      "events_count":       0
    },
    {
      "primary_identifier": "790313678",
      "name":               "LIPIŃSKI MARCIN",
      "watched_since":      "2026-03-18",
      "last_event_at":      null,
      "events_count":       6
    }
  ],
  "meta": {
    "total":        38,
    "per_page":     20,
    "current_page": 1,
    "last_page":    2
  }
}

DELETE /api/v1/companies/watched

curl -X DELETE https://api.alexambros.com/api/v1/companies/watched \
  -H "Authorization: Bearer sk_api_xxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "identifier_type":  "REGON9",
    "identifier_value": ["241150780"]
  }'

{
  "success": true,
  "data": {
    "removed":     ["241150780"],
    "not_found":   [],
    "not_watched": []
  },
  "meta": {
    "total":       1,
    "removed":     1,
    "not_found":   0,
    "not_watched": 0,
    "removed_at":  "2026-03-24T15:18:25+00:00"
  }
}

GET /api/v1/companies/events

curl "https://api.alexambros.com/api/v1/companies/events?identifier_type=NIP&identifier_value=6842685591" \
  -H "Authorization: Bearer sk_api_xxxx" \
  -H "Accept: application/json"

{
  "status": "success",
  "data": {
    "events": [
      {
        "event_type": "COMPANY_NAME_CHANGED",
        "old_value":  "Ireneusz Kupiec",
        "new_value":  "Ireneusz Kupiec wspólnik spółki cywilnej RAZBUD S.C.",
        "event_date": "2025-10-06",
        "severity":   "info"
      },
      {
        "event_type": "COMPANY_CLOSED_DATE",
        "old_value":  null,
        "new_value":  "2026-02-28",
        "event_date": "2025-10-06",
        "severity":   "info"
      }
    ]
  },
  "meta": {
    "total":        8,
    "per_page":     20,
    "current_page": 1,
    "last_page":    1,
    "fetched_at":   "2026-03-24T15:20:44+00:00"
  }
}

GET /api/v1/watchlist/events

curl "https://api.alexambros.com/api/v1/watchlist/events?from_date=2026-03-01&to_date=2026-03-24" \
  -H "Authorization: Bearer sk_api_xxxx" \
  -H "Accept: application/json"

{
  "status": "success",
  "data": [
    {
      "primary_identifier": "543701794",
      "identifier_type":    "CAR-PRO MAX DETAILING",
      "event_type":         "COMPANY_START_DATE_CHANGE",
      "old_value":          "2026-02-25",
      "new_value":          "2026-03-02",
      "event_date":         "2026-03-02",
      "severity":           "info"
    }
  ],
  "meta": {
    "total":        170,
    "per_page":     20,
    "current_page": 1,
    "last_page":    9,
    "fetched_at":   "2026-03-24T15:55:25+00:00"
  }
}

GET /api/v1/companies/search

curl "https://api.alexambros.com/api/v1/companies/search?activity_start_from=2026-02-01&activity_start_to=2026-03-01&has_contact=phone" \
  -H "Authorization: Bearer sk_api_xxxx" \
  -H "Accept: application/json"

{
  "status": "success",
  "data": {
    "total":        508254,
    "per_page":     20,
    "current_page": 1,
    "last_page":    25413,
    "results": [
      {
        "identifiers": [
          { "type": "NIP",    "value": "7721824982" },
          { "type": "REGON9", "value": "260343017" }
        ],
        "name":           "GOSPODARSTWO ROLNE KRZYSZTOF NOWAK",
        "city":           "Rączki",
        "voivodeship":    "świętokrzyskie",
        "activity_start": "1998-02-13",
        "activity_main":  "0111Z",
        "status":         "ACTIVE",
        "contacts": [
          { "type": "phone", "value": "515698087" }
        ]
      }
    ]
  }
}

POST /api/v1/companies/snapshot

curl -X POST https://api.alexambros.com/api/v1/companies/snapshot \
  -H "Authorization: Bearer sk_api_xxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "identifier_type": "REGON9",
    "identifier_value": "021168364"
  }'

{
  "status": "success",
  "data": {
    "identity": {
      "identifiers": [
        { "type": "NIP",    "value": "6121106077" },
        { "type": "REGON9", "value": "021168364"  }
      ],
      "company_type": "Osoba fizyczna",
      "country_code": "PL"
    },
    "profiles": [
      {
        "name":       "Indywidualna Specjalistyczna Praktyka Lekarska Elżbieta Cieśla",
        "status":     "Aktywny",
        "legal_form": "OSOBY FIZYCZNE PROWADZĄCE DZIAŁALNOŚĆ GOSPODARCZĄ",
        "address": {
          "street":      "ul. staroszkolna",
          "building":    "2a",
          "apartment":   "9",
          "city":        "Bolesławiec",
          "postal_code": "59-700",
          "voivodeship": "dolnośląskie",
          "country_code": "PL"
        },
        "units": [
          {
            "identifier": "02116836400027",
            "name":       "Indywidualna Praktyka Lekarska Elżbieta Cieśla",
            "address":   { /* same structure as above */ },
            "dates": [
              { "type": "Data powstania",             "date": "2013-09-19" },
              { "type": "Data zakończenia działalności", "date": "2015-08-21" }
            ]
          }
        ],
        "contacts":   [],
        "activities": [
          { "code": "8622Z", "name": "PRAKTYKA LEKARSKA SPECJALISTYCZNA", "is_primary": true }
        ],
        "dates": [
          { "type": "Data powstania",           "date": "2026-01-02" },
          { "type": "Data wpisu do regon",      "date": "2026-01-02" }
        ],
        "websites": []
      }
    ],
    "persons": [
      { "full_name": "ELŻBIETA DANUTA CIEŚLA", "role": "Właściciel" }
    ]
  },
  "meta": {
    "fetched_at": "2026-03-24T14:48:49+00:00"
  }
}

GET /api/v1/stats/range/2026-04-01

curl "https://api.alexambros.com/api/v1/stats/range/2026-04-01" \
  -H "Accept: application/json"

{
  "meta": {
    "from_date":   "2026-04-01",
    "to_date":     "2026-04-08",
    "source":      "GUS",
    "description": "Registry activity in Poland for the given date range"
  },
  "data": {
    "new":     6941,
    "updated": 41571,
    "deleted": 5690,
    "total":   54202
  }
}

GET /api/v1/stats/day/2026-04-01

curl "https://api.alexambros.com/api/v1/stats/day/2026-04-01" \
  -H "Accept: application/json"

{
  "meta": {
    "date":        "2026-04-01",
    "type":        "daily_snapshot",
    "source":      "GUS",
    "description": "Daily registry activity in Poland"
  },
  "data": {
    "new":     1507,
    "updated": 12665,
    "deleted": 2057,
    "total":   16229
  }
}

{
  "error": "Missing API token",
  "code":  "UNAUTHORIZED"
}

{
  "error": "Malformed token format",
  "code":  "UNAUTHORIZED"
}

{
  "message": "The route api/v1/stats/day could not be found."
}

{
  "message": "The email field must be a valid email address. (and 1 more error)",
  "errors": {
    "email": [
      "The email field must be a valid email address."
    ],
    "name": [
      "The name field is required."
    ]
  }
}

{
  "message": "Too Many Attempts."
}

{
  "message": "Server Error"
}