Overview

REST API reference for Swarmhit.

All endpoints live under the production base URL:

https://app.swarmhit.com/api/v1

Every request must carry an API key as a bearer token; see Authentication. Endpoints are grouped by resource in the sidebar, and each page documents parameters, request and response schemas, and code examples, with an interactive playground to try requests against your own workspace.

The raw OpenAPI specification is available at https://app.swarmhit.com/openapi.yaml for Postman, Insomnia, or code generators.

Connect a sender POST

Connect a LinkedIn sender with its email/username and password; optionally a proxy and country. The sender lands in the effective workspace (the one named by the X-Swarmhit-Workspace header, if set), consuming a seat from its allocation. Credentials are stored encrypted and never returned. The outcome and later changes arrive via the account.* webhooks. Add a 2FA setup key (`totpSecret`) for automatic (infinite) login: the sign-in then completes hands-free, solving a 2FA challenge from the secret. Anything else fails with 400 and an account.connection_failed webhook rather than leaving a half-connected sender holding a seat. Without a `totpSecret` the connect is interactive. If LinkedIn asks for a verification step the response is 200 with `status` `checkpoint_required` and a `checkpoint` object describing it; answer it on POST /accounts/{id}/checkpoint within five minutes. An account.checkpoint_required webhook fires at the same time. On failure the error body carries a stable `error.code` to branch on and a plain-language `error.message` describing what went wrong. Codes for this endpoint: `invalid-credentials` (wrong email/password), `rate-limited` (LinkedIn is throttling sign-in; retry later), `proxy-failed` (the proxy sent with the request did not respond, so the sign-in never reached LinkedIn), `provider-timeout` / `provider-unreachable` (LinkedIn answered too slowly, or could not be reached at all; safe to retry), `checkpoint-code-rejected` (the account's 2FA setup key is wrong, so the authenticator code is rejected), `checkpoint-restricted` (LinkedIn has restricted the account; clear it on linkedin.com and connect again), `unsupported-verification` (automatic login was requested but the account signs in with a method other than authenticator 2FA — connect it without a `totpSecret` and answer the challenge instead), `verification-required` / `verification-failed` (a verification step that can't be completed automatically), `invalid-totp-secret` (the 2FA key isn't a valid authenticator key), `already-connected`, `no-plan`, and `seat-limit-reached` (409), and `connection-failed` for anything else, where `error.message` carries the specific reason. The same `code` is included on the account.connection_failed webhook.