Server API

Trigger surveys and manage targets from your backend using your project’s secret key. The project is always resolved from the secret key — there’s no projectId in the URL.

Authentication

Every request requires a secret key (sk_...) in the Authorization header:


POST https://api.1sygnal.app/v1/surveys/{surveyId}/targets
Authorization: Bearer sk_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
Content-Type: application/json

Secret keys are created from your project’s settings page. A public key (pk_...) is rejected here — it can only authenticate the SDK. Never expose your secret key in client-side code; it grants write access to your project.

Base URL

https://api.1sygnal.app/v1

Add survey targets

Target specific users for a survey. Targeted users see the survey on their next page load regardless of trigger rules. Requires a plan with API-triggered surveys enabled.


POST /v1/surveys/{surveyId}/targets

Request body

Field	Type	Required	Description
`userIds`	`string[]`	One of	External user IDs (from `identify()`). Max 100.
`userProfileIds`	`string[]`	One of	Internal profile IDs. Max 100.
`expiresAt`	`string`	No	ISO 8601 timestamp. Target expires after this time.

Response


{ "added": 3, "notFound": ["user-xyz"] }

notFound lists any user IDs that couldn’t be resolved to a known profile.

Remove survey targets


DELETE /v1/surveys/{surveyId}/targets

Request body

Field	Type	Required	Description
`userIds`	`string[]`	One of	External user IDs. Max 100.
`userProfileIds`	`string[]`	One of	Internal profile IDs. Max 100.

Returns 204 No Content.

List survey targets


GET /v1/surveys/{surveyId}/targets?limit=50&cursor={cursor}

Response


{
  "data": [...],
  "nextCursor": "...",
  "hasMore": true,
  "total": 42
}

Errors

Status	Code	Description
401	`UNAUTHORIZED`	Missing Authorization header, or the key isn’t a valid, active `sk_` secret key.
403	`FEATURE_NOT_AVAILABLE`	Plan doesn’t support API-triggered surveys.
404		Survey not found, or doesn’t belong to the project resolved from your secret key.
400	`VALIDATION_ERROR`	Invalid request body (e.g., empty user list, > 100 users).
429		Rate limit exceeded.

Rate limits

60 requests per minute per secret key. Rate limit headers are included in every response (X-RateLimit-Limit, X-RateLimit-Remaining).

Webhook signing with your secret key

When you add a webhook endpoint, 1Sygnal uses your project’s secret key as the HMAC signing key instead of generating a separate signing secret — creating one automatically if you don’t already have one. This means you verify webhook signatures with the same sk_... key you use for API calls. See Webhooks → Verifying the signature.