Referenz der öffentlichen API v1

Diese Referenz wird beim Bauen der Doku aus dem OpenAPI-Dokument der öffentlichen API erzeugt (openapi-v1.json, PollYou Public API 1.0.0). Die laufende API liefert dasselbe Dokument unter GET /api/v1/openapi.json – ohne Anmeldung, zum Import in Postman, Insomnia oder einen Code-Generator.

Alle Endpunkte verlangen einen API-Schlüssel (Authorization: Bearer py_live_…) mit dem jeweils genannten Scope. Einstieg, Scopes, Rate-Limits und Beispiele: Öffentliche API.

Surveys

`GET /api/v1/surveys`

List surveys (scope surveys:read)

Most recently updated first. Archived surveys only appear with `status=archived`.

Parameter	Ort	Pflicht	Beschreibung
`status`	query	nein	Only surveys with this status
`type`	query	nein	Only polls or only surveys
`page`	query	nein	Page number (1-based)

Status	Bedeutung	Schema
`200`	V1Survey resource	`V1Survey.V1SurveyPage`
`401`	Missing, invalid, expired or revoked API key
`403`	The API key lacks the required scope, or X-Organization-Id names another organization
`404`	Not found	`Error`
`429`	Rate limit of the API key exceeded (see Retry-After)

`POST /api/v1/surveys`

Create a draft (scope surveys:write)

A poll starts with one page holding one single choice question with two options, a survey with one empty page. Questions are edited in the dashboard.

Request-Body (V1Survey.V1SurveyCreateInput):

Feld	Typ	Beschreibung
`type`	string (poll, survey)
`title`	string
`description`	string \| null

Status	Bedeutung	Schema
`201`	V1Survey resource created	`V1Survey`
`400`	Invalid input	`Error`
`401`	Missing, invalid, expired or revoked API key
`403`	The API key lacks the required scope, or X-Organization-Id names another organization
`422`	An error occurred	`ConstraintViolation`
`429`	Rate limit of the API key exceeded (see Retry-After)

`GET /api/v1/surveys/{id}`

Get a survey with its structure (scope surveys:read)

Get a survey with its structure (scope surveys:read)

Parameter	Ort	Pflicht	Beschreibung
`id`	path	ja	V1Survey identifier

Status	Bedeutung	Schema
`200`	V1Survey resource	`V1Survey`
`401`	Missing, invalid, expired or revoked API key
`403`	The API key lacks the required scope, or X-Organization-Id names another organization
`404`	Not found	`Error`
`429`	Rate limit of the API key exceeded (see Retry-After)

`PATCH /api/v1/surveys/{id}`

Change title or description (scope surveys:write)

Merge patch (`application/merge-patch+json`): omitted fields stay unchanged. Changes the draft; respondents see them after the next publish. Archived surveys: 409.

Parameter	Ort	Pflicht	Beschreibung
`id`	path	ja	V1Survey identifier

Request-Body (V1Survey.V1SurveyUpdateInput.jsonMergePatch):

Feld	Typ	Beschreibung
`title`	string \| null
`description`	string \| null

Status	Bedeutung	Schema
`200`	V1Survey resource updated	`V1Survey`
`400`	Invalid input	`Error`
`401`	Missing, invalid, expired or revoked API key
`403`	The API key lacks the required scope, or X-Organization-Id names another organization
`404`	Not found	`Error`
`422`	An error occurred	`ConstraintViolation`
`429`	Rate limit of the API key exceeded (see Retry-After)

`POST /api/v1/surveys/{id}/close`

Close a live or scheduled survey (scope surveys:write; 409 from other statuses)

Close a live or scheduled survey (scope surveys:write; 409 from other statuses)

Parameter	Ort	Pflicht	Beschreibung
`id`	path	ja	V1Survey identifier

Status	Bedeutung	Schema
`200`	V1Survey resource created	`V1Survey`
`400`	Invalid input	`Error`
`401`	Missing, invalid, expired or revoked API key
`403`	The API key lacks the required scope, or X-Organization-Id names another organization
`422`	An error occurred	`ConstraintViolation`
`429`	Rate limit of the API key exceeded (see Retry-After)

`POST /api/v1/surveys/{id}/publish`

Publish the draft as a new version (scope surveys:write)

The status becomes `scheduled` if the start lies in the future, otherwise `live`. 409 for archived surveys, 422 if the draft is not publishable.

Parameter	Ort	Pflicht	Beschreibung
`id`	path	ja	V1Survey identifier

Status	Bedeutung	Schema
`200`	V1Survey resource created	`V1Survey`
`400`	Invalid input	`Error`
`401`	Missing, invalid, expired or revoked API key
`403`	The API key lacks the required scope, or X-Organization-Id names another organization
`422`	An error occurred	`ConstraintViolation`
`429`	Rate limit of the API key exceeded (see Retry-After)

Responses

`GET /api/v1/responses/{id}`

Get a response with all answers (scope responses:read)

Get a response with all answers (scope responses:read)

Parameter	Ort	Pflicht	Beschreibung
`id`	path	ja	V1Response identifier

Status	Bedeutung	Schema
`200`	V1Response resource	`V1Response`
`401`	Missing, invalid, expired or revoked API key
`403`	The API key lacks the required scope, or X-Organization-Id names another organization
`404`	Not found	`Error`
`429`	Rate limit of the API key exceeded (see Retry-After)

`DELETE /api/v1/responses/{id}`

Delete a response permanently (scope responses:write)

For example for data subject requests. Removes the response with its answers; aggregates are recomputed. Audit-logged (`response.deleted`).

Parameter	Ort	Pflicht	Beschreibung
`id`	path	ja	V1Response identifier

Status	Bedeutung	Schema
`204`	V1Response resource deleted
`401`	Missing, invalid, expired or revoked API key
`403`	The API key lacks the required scope, or X-Organization-Id names another organization
`404`	Not found	`Error`
`429`	Rate limit of the API key exceeded (see Retry-After)

`GET /api/v1/surveys/{surveyId}/responses`

List the responses of a survey (scope responses:read)

Newest first (by completion, unfinished responses by start). Range: `from`/`to` (default: since the survey was created). Excluded responses only with `includeExcluded=true`. Pagination by cursor: pass `nextCursor` as `cursor` for the next page; it stays stable while new responses arrive. `answers` maps question keys to display values.

Parameter	Ort	Pflicht	Beschreibung
`status`	query	nein	completed (default), started (not completed) or all
`from`	query	nein	Start: local date `YYYY-MM-DD` (midnight in `timezone`) or ISO 8601 date-time with offset
`to`	query	nein	End: local date `YYYY-MM-DD` (inclusive) or ISO 8601 date-time with offset (exclusive)
`timezone`	query	nein	IANA timezone of the dates (default UTC)
`includeExcluded`	query	nein	Also list excluded (flagged) responses
`limit`	query	nein	Page size
`cursor`	query	nein	`nextCursor` of the previous page
`surveyId`	path	ja	V1Response identifier

Status	Bedeutung	Schema
`200`	V1Response resource	`V1Response.V1ResponsePage`
`401`	Missing, invalid, expired or revoked API key
`403`	The API key lacks the required scope, or X-Organization-Id names another organization
`404`	Not found	`Error`
`429`	Rate limit of the API key exceeded (see Retry-After)

Analytics

`GET /api/v1/surveys/{id}/analytics`

Key figures and results per question (scope analytics:read)

Completed, not excluded responses in the range (default: the last 30 days including today). Same numbers as the dashboard.

Parameter	Ort	Pflicht	Beschreibung
`from`	query	nein	Start: local date `YYYY-MM-DD` (midnight in `timezone`) or ISO 8601 date-time with offset
`to`	query	nein	End: local date `YYYY-MM-DD` (inclusive) or ISO 8601 date-time with offset (exclusive)
`timezone`	query	nein	IANA timezone of the dates (default UTC)
`id`	path	ja	V1SurveyAnalytics identifier

Status	Bedeutung	Schema
`200`	V1SurveyAnalytics resource	`V1SurveyAnalytics`
`401`	Missing, invalid, expired or revoked API key
`403`	The API key lacks the required scope, or X-Organization-Id names another organization
`404`	Not found	`Error`
`429`	Rate limit of the API key exceeded (see Retry-After)

Schemas

`V1Response`

Feld	Typ	Beschreibung
`id`	string (uuid)
`surveyId`	string (uuid)
`status`	string (in_progress, completed)
`startedAt`	string (date-time)
`completedAt`	string \| null (date-time)
`durationMs`	integer \| null
`channel`	string	How the response was collected: script, react, vue, angular, angularjs, iframe, embed, link or api
`embedId`	string \| null (uuid)
`deviceType`	string \| null
`browserFamily`	string \| null
`osFamily`	string \| null
`country`	string \| null	ISO 3166-1 alpha-2
`locale`	string \| null
`referrerHost`	string \| null
`utm`	object
`meta`	object
`identified`	boolean	Started with a verified identity token
`versionNumber`	integer \| null	Survey version the respondent answered
`excluded`	boolean	Excluded from analytics and results (spam, test, …)
`answers`	array	Every question of the response's survey version in order, answered or not.

`V1Response.V1ResponsePage`

Feld	Typ	Beschreibung
`items`	array
`totalItems`	integer	Number of responses matching the filter (all pages)
`nextCursor`	string \| null	Cursor of the next page; null on the last page

`V1Survey`

Feld	Typ	Beschreibung
`id`	string (uuid)
`publicId`	string
`type`	string (poll, survey)
`title`	string
`description`	string \| null
`status`	string (draft, scheduled, live, closed, archived)
`questionCount`	integer
`publishedVersion`	integer \| null
`publishedAt`	string \| null (date-time)
`hasUnpublishedChanges`	boolean
`createdAt`	string (date-time)
`updatedAt`	string (date-time)
`pages`	array

`V1Survey.V1SurveyPage`

Feld	Typ	Beschreibung
`items`	array
`page`	integer
`itemsPerPage`	integer
`totalItems`	integer	Number of surveys matching the filter (all pages)

`V1SurveyAnalytics`

Feld	Typ	Beschreibung
`surveyId`	string (uuid)
`meta`	object	Where the numbers come from and the resolved range (ISO 8601 in the filter timezone, `to` exclusive).
`overview`	object
`totalResponses`	integer	Completed responses counted in the question results
`questions`	array

Referenz der öffentlichen API v1 ​

Surveys

GET /api/v1/surveys

POST /api/v1/surveys

GET /api/v1/surveys/{id}

PATCH /api/v1/surveys/{id}

POST /api/v1/surveys/{id}/close

POST /api/v1/surveys/{id}/publish

Responses

GET /api/v1/responses/{id}

DELETE /api/v1/responses/{id}

GET /api/v1/surveys/{surveyId}/responses