Quickstart: your first socket.help API request

What you can do in five minutes

The socket.help HTTP API runs browser utilities on the server and creates temporary resources: webhook inboxes, mock REST APIs, file shares and mock MCP servers. You can call it from any language or shell with no account and no client library. Anonymous requests use the smallest allowances; an API key moves usage to your workspace.

This page walks through one utility run, one webhook inbox and the switch to an API key. Every example uses plain curl against https://socket.help.

Run a utility without an account

Send text in input and string options in options. The JSON formatter has the tool ID json and an action option of format or minify.

The response contains the tool ID, the result as a string in output, and your daily hosted run usage. Invalid input returns a 400 response with an error message and a request ID.

curl https://socket.help/api/tools/json/run \
  -H 'Content-Type: application/json' \
  -d '{"input":"{\"hello\":true}","options":{"action":"format"}}'

# 200 OK
{
  "toolId": "json",
  "output": "{\n  \"hello\": true\n}",
  "usage": { "used": 1, "limit": 100, "resetsAt": "2026-10-28T00:00:00.000Z" }
}

Create a webhook inbox

POST /api/inboxes creates an inbox that lasts one hour. New resources are private, so the response includes two separate secrets: inspectionToken lets you read and delete the inbox, and accessToken lets a sender deliver requests to it.

Both tokens are returned only once. Save them before you continue; anonymous tokens cannot be recovered.

curl -X POST https://socket.help/api/inboxes

# 201 Created
{
  "id": "INBOX_ID",
  "inspectionToken": "INSPECTION_TOKEN",
  "expiresAt": "2026-10-27T13:00:00.000Z",
  "visibility": "private",
  "accessVersion": "ACCESS_VERSION",
  "accessToken": "ACCESS_TOKEN",
  "webhookUrl": "https://socket.help/hooks/INBOX_ID"
}

Send a callback and read it back

Send any request to the webhook URL with the access token in X-Access-Token. The inbox answers 200 with a capture ID. Then read the captured history with the inspection token as a Bearer token.

curl -X POST https://socket.help/hooks/INBOX_ID \
  -H "X-Access-Token: $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"event":"ping"}'
# {"received":true,"requestId":"CAPTURE_ID"}

curl https://socket.help/api/inboxes/INBOX_ID/requests \
  -H "Authorization: Bearer $INSPECTION_TOKEN"
# {"requests":[{"method":"POST","path":"/hooks/INBOX_ID","headers":{...},
#   "query":{},"body":"{\"event\":\"ping\"}","bodyEncoding":"utf8",
#   "bodySize":16,"id":"CAPTURE_ID","timestamp":"..."}]}

curl -X DELETE https://socket.help/api/inboxes/INBOX_ID \
  -H "Authorization: Bearer $INSPECTION_TOKEN"
# 204 No Content

Switch to an API key

Create a free account at /account/, open your workspace’s API keys section and create a key. Keys start with sh_ and are shown once. Send the key as a Bearer token on any request.

With a key, resources belong to your workspace, usage counts against the workspace plan, and you can list everything you own with GET /api/account/resources. GET /api/usage shows the plan, its limits and today’s hosted runs for the caller.

export SOCKET_HELP_API_KEY='sh_...'

curl https://socket.help/api/usage \
  -H "Authorization: Bearer $SOCKET_HELP_API_KEY"

curl -X POST https://socket.help/api/inboxes \
  -H "Authorization: Bearer $SOCKET_HELP_API_KEY"

Next steps

Each resource type has its own page with the full request and response shapes. The interactive reference at /docs/reference/ lists every endpoint, and /api/openapi.json is the OpenAPI 3.1 document you can import into your own tooling or client generator.

• Authentication and API keys: which credential goes in which header.
• Limits and errors: allowances, rate limits and how to handle 429 responses.
• Webhook inboxes, mock REST APIs, file sharing and mock MCP servers.
• The CLI, TypeScript SDK, SSH gateway and MCP endpoint for agents.