Documentation Index
Fetch the complete documentation index at: https://docs.55-tech.com/llms.txt
Use this file to discover all available pages before exploring further.
Protocol overview
The WebSocket relay at wss://scraping-api.55-tech.com/ws provides a bidirectional proxy. You connect to the gateway, send a JSON connect message, and the gateway relays all frames between you and the target through a geo-distributed agent.
Client ←→ Gateway (wss://.../ws) ←→ Agent ←→ Target WebSocket
Interactive playground
The /ws/docs endpoint returns the protocol schema:
curl https://scraping-api.55-tech.com/ws/docs
{
"type": "connected",
"status": 101,
"node_id": "scraping-de1",
"message": "This is a documentation endpoint. Connect via WebSocket at wss://scraping-api.55-tech.com/ws"
}
wscat:
npm install -g wscat
wscat -c wss://scraping-api.55-tech.com/ws
{"apiKey":"YOUR_API_KEY","url":"wss://echo.websocket.events"}
Connect message (client → gateway)
Must be sent as JSON text within 10 seconds of connecting.
{
"apiKey": "YOUR_API_KEY",
"url": "wss://target.example.com/stream",
"headers": {
"Authorization": "Bearer token",
"Origin": "https://target.example.com"
},
"cookies": {
"session": "abc123"
},
"geo": "US,DE",
"agent": "de1",
"idle_timeout": 0,
"proxy": "socks5://user:pass@host:1080"
}
Fields
| Field | Type | Required | Default | Description |
|---|
apiKey | string | Yes | — | API key for authentication. key is also accepted. |
url | string | Yes | — | Target WebSocket URL (wss://... or ws://...) |
headers | object | No | {} | Custom headers sent with the WS upgrade request to the target. Useful for Authorization, Origin, Cookie headers that the target expects. |
cookies | object | No | {} | Cookies sent with the WS upgrade request. Merged into the Cookie header. |
geo | string | No | — | Restrict agent selection to specific countries. Comma-separated ISO codes (e.g. US,DE,AT). |
agent | string | No | — | Pin to specific agent(s) by slug (e.g. de1) or comma-separated for random pick (de1,at5,us3). |
idle_timeout | float | No | 0 | If > 0, disconnect after this many seconds without receiving a message from the target. 0 = no idle timeout. |
subprotocols | array | No | [] | WS sub-protocol negotiation. Sent as Sec-WebSocket-Protocol header during upgrade. E.g. ["centrifuge-protobuf"] |
proxy | string | No | "" | Proxy URL for the WebSocket connection (http:// or socks5://). Useful for routing through residential or ISP proxies. |
Response messages (gateway → client)
Connected
Sent once after the agent successfully connects to the target WebSocket.
{
"type": "connected",
"status": 101,
"node_id": "scraping-de1"
}
| Field | Type | Description |
|---|
type | string | Always "connected" |
status | int | HTTP status code of the WS upgrade. 101 = success. |
node_id | string | Proxy node handling the relay (e.g. scraping-de1) |
Error
Sent when connection fails or an error occurs. The WebSocket is closed after this message.
{
"type": "error",
"message": "Invalid or missing API key"
}
| Field | Type | Description |
|---|
type | string | Always "error" |
message | string | Human-readable error description |
Relayed frames
After the connected message, all subsequent frames are raw relay — no JSON wrapping. Text frames stay text, binary frames stay binary.
Close codes
| Code | Meaning |
|---|
1000 | Normal closure (you or target closed) |
1008 | Policy violation — invalid API key, rate limited, or connect timeout |
1011 | Internal error — agent failure or target unreachable |
Error scenarios
| Scenario | What happens |
|---|
| No connect message within 10s | Gateway closes with code 1008 |
| Invalid API key | Gateway sends error JSON, closes with 1008 |
| Rate limit exceeded | Gateway sends error JSON, closes with 1008 |
| Target connection refused | Gateway sends error JSON, closes with 1011 |
| No agent available | Gateway sends error JSON, closes with 1011 |
| Target closes connection | Gateway forwards the close frame with target’s code and reason |
| Client closes connection | Gateway forwards close to target, cleans up |
| Agent crashes mid-relay | Gateway closes with 1011 |
Frame flow diagram
Rate limiting
WebSocket connections consume 1 token from your rate limit bucket on connect (when the connect message is validated). Subsequent frames do not consume tokens. If your bucket is empty, the gateway sends an error and closes with 1008.
Testing with wscat
# Install
npm install -g wscat
# Connect
wscat -c wss://scraping-api.55-tech.com/ws
# Paste connect message:
{"apiKey":"YOUR_KEY","url":"wss://echo.websocket.events"}
# After "connected" response, type messages to relay:
hello world
# The echo server will send back your message
Testing with Python
import asyncio
import json
import websockets
async def test():
async with websockets.connect("wss://scraping-api.55-tech.com/ws") as ws:
await ws.send(json.dumps({
"apiKey": "YOUR_API_KEY",
"url": "wss://echo.websocket.events",
}))
resp = json.loads(await ws.recv())
print(f"Status: {resp}")
if resp["type"] == "connected":
await ws.send("test message")
reply = await ws.recv()
print(f"Echo: {reply}")
asyncio.run(test())
