Connect and authenticate

Open one WebSocket that streams every document NOSIBLE crawls, already enriched, so you receive the web as it happens.

Explanation

Opens one WebSocket that streams every document NOSIBLE crawls, already enriched with entities, ontologies, tickers, locations and embeddings. Use it to receive the web as it is crawled instead of polling for it, and to filter it on NOSIBLE's side before it reaches you.

WSSwss://firehose.nosible.world/v2.0/firehoseGet access

Request

Authorizations

API key

X-Api-Keystringheader

Your approved API key, sent on the upgrade request. Or use Authorization, or the auth frame.

Example: nos_sk_...

Authorizationstringheader

The same key as a bearer token.

Example: Bearer nos_sk_...

Frame fields

JSON text frame

auth frameobject (text frame)body

For browsers, which cannot set headers: send it first, within 3 seconds.

Example: {"type":"auth","api_key":"nos_sk_..."}

Response

Frame you receive

application/json

These are the fields you can build against. Nested names use dot notation; optional sections are called out in their descriptions.

typestring

Always authenticated.

Example: authenticated

can_replayboolean

Whether this key may resume from a cursor or time.

Example: true

time_msinteger

When the server prepared this message, UTC Unix milliseconds.

Example: 1793880000000

Errors and close codes

WebSocket

TEXTA JSON text frame, shown in the response example.

1008unauthorized — The key is invalid, revoked or expired, or authorization ended. Do not retry.

1000firehose_access_pending — The key is valid but not yet approved. Reconnect once access is approved.

1000too_many_connections — The key already has 4 active subscriptions.

1000auth_unavailable — Authentication is busy or unreachable. Retry with backoff.

1000timeout — You did not authenticate or subscribe in time.