Authentication

Sending your key

The key works like a password for programs. Send it with every request in the Authorization header, after the word Bearer. Live keys start with sc_live_, followed by 32 characters.

Authorization: Bearer sc_live_…

Store it in an environment variable, not in your code. We only keep a hash of it, so you see the full key exactly once, right after you create it.

export HULLWISE_API_KEY="sc_live_…"
curl "https://hullwise.co/api/v1/scan?url=example.com" \
  -H "Authorization: Bearer $HULLWISE_API_KEY"

Getting a key

Sign in and open API keys in your account. That is where you create new keys and revoke old ones. A revoked key stops working immediately.

For a first try, there is the test key sc_test_demo. It works without an account and has the limit of free access. Everyone who uses it shares that limit, and the report is always shortened. For real work, use your own key.

Without a key

Two routes work without a key. The REST API is not one of them.

• The MCP server at https://hullwise.co/mcp. Without a header, the limit is 20 checks per hour per IP address. With a key, the limit of your access applies. An invalid key returns status 401. The server does not fall back to keyless access in that case.
• The homepage endpoint GET /api/scan. It is meant for the browser and counts per IP address or, when you are signed in, per account. Details are in the API reference.

Shortened or full report

How much the report contains depends on the plan of the account the key belongs to. The shortening happens on our server, so locked findings never leave it.

How to recognize a locked finding in the JSON is described in the API reference.

Limits

Every request counts within a one-hour window. The window starts with the first request. On the MCP server, every tool call counts.

The limits are there to slow down abuse and are not counted to the exact request. Plan your load with some headroom below the limit and always handle status 429.

Rate limit headers

Every REST API response to a request with a valid key tells you how much is left.

Once the limit is reached, you get status 429 with the code rate_limited. Wait until the time in X-RateLimit-Reset, then try again. The MCP server reports the same as a tool error with the text rate_limited. All codes are listed under Errors.