Get started

Authentication

Sailor public API requests use bearer authentication. Send the token from your backend. Do not put it in browser code, mobile clients, extensions, public repositories, or support screenshots.

Every request should include Authorization: Bearer $SAILOR_API_TOKEN.

Request Shape

$curl https://api.sailorhq.io/phone-system/outcomes \
>  -H "Authorization: Bearer $SAILOR_API_TOKEN" \
>  -H "Content-Type: application/json"

Token Scope

Requests act on the workspace attached to the token. If the token is missing, invalid, or not allowed to manage phone-system outcomes, Sailor returns an error body with an error string.

Treat the token as a workspace-scoped secret. A public token leak is a workspace incident.

Write Requests

Create and update requests require an Idempotency-Key header. Use a stable unique value for the operation you are attempting so retries do not create duplicate outcomes.

$curl https://api.sailorhq.io/phone-system/outcomes \
>  -X POST \
>  -H "Authorization: Bearer $SAILOR_API_TOKEN" \
>  -H "Idempotency-Key: $SAILOR_REQUEST_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "outcome_name": "Interested",
>    "outcome_type": "action",
>    "destination_type": "smart_list",
>    "destination_id": "00000000-0000-4000-8000-000000000000",
>    "webhook_url": "https://example.com/sailor/outcomes"
>  }'

Header Checklist

RequestRequired headers
GET /phone-system/outcomesAuthorization
POST /phone-system/outcomesAuthorization, Idempotency-Key, Content-Type
PATCH /phone-system/outcomes/{outcomeId}Authorization, Idempotency-Key, Content-Type
DELETE /phone-system/outcomes/{outcomeId}Authorization

Idempotency Keys

SituationUse this key
Retrying the same logical operationReuse the same Idempotency-Key.
Starting a new intended operationGenerate a new Idempotency-Key.

If Sailor returns idempotency_key_in_use, the first request with that key is still processing. Wait, then retry the same logical operation with the same key.

Common Auth Errors

ErrorMeaningWhat to check
unauthorizedSailor could not authenticate the request.Confirm the bearer token is present and current.
forbiddenThe token is valid, but the workspace cannot perform that action.Confirm the token has access to manage phone-system outcomes.
no_subaccountSailor could not resolve the workspace scope.Confirm the token is attached to the expected workspace.
feature_disabledThe phone-system API is not enabled for this workspace.Enable the phone-system feature before calling these endpoints.

Security Checklist

  • Store tokens in server-side secret storage.
  • Rotate tokens if they appear in logs, screenshots, or client bundles.
  • Use HTTPS for webhook URLs and API calls.
  • Treat webhook payloads as operational events, not as an authentication mechanism.